Bibliotheek

Hoe stel je de ChatGPT Ads Conversions API in met server-side Google Tag Manager?

uitleg-Hoe stel je de OpenAI-ChatGPT Ads CAPI in met sGTM

De ChatGPT Ads Conversions API stuurt conversie-events vanaf je server naar OpenAI. Dat is handig als je een aankoop pas na betaling wilt bevestigen, een lead in je CRM wilt terugkoppelen of browser-side meting wilt aanvullen met server-side events.

De Conversions API is geen vervanger voor de ChatGPT Ads Pixel. De pixel vangt oppref automatisch op uit de URL en bewaart die als first-party cookie. De API doet dat niet. Gebruik je beide routes voor dezelfde conversie, stuur dan via browser en server dezelfde event ID mee. OpenAI kan de events dan dedupliceren.

De ChatGPT Ads Conversions API stelt je in staat om:

  • browser-side en server-side conversies naast elkaar te meten;
  • oppref mee te sturen wanneer deze beschikbaar is;
  • belangrijke CRM-, betaal- of offline events terug te sturen;
  • events met dezelfde event ID te dedupliceren;
  • eligible first-party data gehasht mee te sturen om de matchkwaliteit te verbeteren, mits je daarvoor de juiste toestemming hebt.

Een servercontainer maakt de implementatie niet automatisch privacyvriendelijker en haalt een cookiebanner niet weg. Dezelfde toestemmingseisen gelden voor het verzamelen en doorsturen van persoonsgegevens, cookies en conversiegegevens.

Wat heb je nodig?

  • Toegang tot ChatGPT Ads Manager met een aangemaakte web data source, Pixel ID en Conversions API key.
  • Een werkende Google Tag Manager webcontainer en servercontainer.
  • Een server-side tagging endpoint op een subdomein van je eigen domein.
  • Een browser-side eventstroom naar de servercontainer, bijvoorbeeld via de Google tag en GA4 Client.
  • Een consent-opzet die marketingtoestemming betrouwbaar doorgeeft aan je servercontainer.
  • Een plan voor eventnamen, event IDs, waarden en eventueel user data.

Heb je nog geen servercontainer? Volg eerst onze gids GTM server-side tagging opzetten in 8 stappen. Voor een servercontainer op een eigen meetdomein kun je Savvy Track gebruiken. Gebruik je al GA4-events als bron voor je servercontainer, controleer dan ook je GA4-gebeurtenissen en conversies.

De ChatGPT Ads Conversions API installeren met server-side Google Tag Manager in 5 stappen

Stap 1: Maak je Pixel ID en Conversions API key aan

  1. Open ChatGPT Ads Manager.
  2. Ga naar Conversions of data sources.
  3. Maak een web data source aan als die nog niet bestaat.
  4. Kopieer de Pixel ID.
  5. Maak een Conversions API key aan en bewaar die veilig. Plak de key niet in je webcontainer of in client-side JavaScript.

De API key hoort uitsluitend in een server-side omgeving te staan. Iemand die de key via de browser kan uitlezen, kan events namens jouw Pixel ID versturen. Dat is precies het soort onnodig gedoe dat je later niet wilt oplossen.

Stap 2: Zorg dat je eventdata de servercontainer bereikt

Voor een standaard webimplementatie stuurt de Google tag in je webcontainer events naar je servercontainer. De servercontainer ontvangt ze vervolgens via de GA4 Client.

  1. Open je webcontainer in GTM.
  2. Open de Google tag die events naar je servercontainer stuurt.
  3. Controleer dat server_container_url naar je eigen server-side tagging subdomein wijst.
  4. Zorg dat de events die je wilt doorsturen een duidelijke naam hebben. Bijvoorbeeld generate_lead, purchase of begin_checkout.
  5. Zorg dat belangrijke parameters in de dataLayer beschikbaar zijn, zoals event_id, value, currency, transaction_id en items.
  6. Geef de consentstatus mee op een manier die je servercontainer kan uitlezen.

Gebruik je alleen een thank-you page voor leadgeneratie? Dan kan een generate_lead event al voldoende zijn. Voor e-commerce wil je minimaal een stabiel order- of transaction ID en de orderwaarde hebben. Gebruik geen timestamp als event ID. Een bezoeker die opnieuw laadt of later terugkomt, kan dan een nieuw ID krijgen voor dezelfde conversie.

Stap 3: Installeer de OpenAI Ads Conversions API-tag in je servercontainer

Voor server-side Google Tag Manager kun je de community template OpenAI Ads Conversions API by Stape gebruiken. Dit is een community template, geen officiële OpenAI-tag. De payload en vereisten hieronder zijn wel gebaseerd op de officiële OpenAI-documentatie.

  1. Open je servercontainer in Google Tag Manager.
  2. Ga naar Templates en voeg onder Tag Templates een nieuwe template uit de Community Template Gallery toe.
  3. Zoek op OpenAI Ads Conversions API by Stape.
  4. Voeg de template toe en maak daarna een nieuwe tag aan met dit tagtype.
  5. Geef de tag een naam, bijvoorbeeld ChatGPT Ads | CAPI.
  6. Vul je Pixel ID en API Key in. Gebruik voor beide bij voorkeur een constante variabele of een geheimenbeheer-oplossing die past bij jouw werkwijze.
  7. Kies bij Action Source voor Web wanneer het event op je website plaatsvindt.
  8. Laat Validate Only tijdens de eerste test op true staan.
  9. Koppel de tag aan de events die je wilt doorsturen. Begin bijvoorbeeld met alleen een lead of purchase, niet met alle events tegelijk.

De template kan GA4-eventnamen automatisch mappen. De belangrijkste mappings zijn:

  • page_view naar page_viewed
  • view_item naar contents_viewed
  • add_to_cart naar items_added
  • begin_checkout naar checkout_started
  • purchase naar order_created
  • generate_lead naar lead_created
  • sign_up naar registration_completed

Controleer de mapping altijd in GTM Preview. Gebruik voor een conversion-optimized campaign liefst een standaardevent dat inhoudelijk klopt. Een custom event kan technisch werken, maar wordt op dit moment niet ondersteund voor oCPC-campagnes.

Stap 4: Map click reference, event ID en eventdata

Dit is het belangrijkste deel van de setup. Een server event zonder de juiste context is wel verstuurd, maar niet per se bruikbaar voor attributie of optimalisatie.

oppref behouden

OpenAI voegt bij een advertentieklik mogelijk oppref toe aan je landing page URL. De browser Pixel leest dit automatisch en bewaart het in de first-party __oppref cookie. Voor de Conversions API moet je de originele waarde zelf doorsturen wanneer die beschikbaar is.

De Stape-template zoekt oppref onder meer in de URL, de __oppref cookie en incoming event data. Schakel daarom Set Click ID cookie in als je de click reference server-side als cookie wilt bewaren. Laat de cookie draaien op je eigen meetdomein en test of hij ook op volgende pagina’s beschikbaar blijft.

Verwijder oppref niet uit je URL voordat je meetopzet hem heeft opgeslagen. Controleer redirects, consent scripts en scripts die URL-parameters opschonen. Dit is dezelfde categorie probleem als een verloren GCLID. Zie ook onze uitleg over click ID’s en GCLID veiligstellen.

Eén event ID voor browser en server

Meet je dezelfde conversie via de ChatGPT Ads Pixel én de Conversions API? Gebruik dan exact dezelfde ID:

  • in de browser: event_id in de vierde parameter van oaiq(“measure”, …);
  • op de server: id in het API-event, of de Event ID-variabele in de server-side tag.

OpenAI dedupliceert op Pixel ID, eventnaam en event ID. Bij een custom event moet ook de custom_event_name gelijk zijn. OpenAI gebruikt de eerste ontvangen versie en negeert een later duplicaat.

Voor een purchase is een transaction ID doorgaans een geschikt event ID. Voor een formulier kun je een unieke ID genereren op het moment dat de succesvolle submit plaatsvindt en diezelfde waarde via de dataLayer naar beide tags sturen. Dit lijkt sterk op het principe uit onze gids over Meta Event Deduplication.

Waarde, valuta en inhoud

Voor een aankoop map je minimaal:

  • Amount: hele centen, bijvoorbeeld 4995 voor € 49,95;
  • Currency: EUR;
  • Contents: waar relevant de items, met bijvoorbeeld product-ID, naam, content_type en hoeveelheid.

De valuta is verplicht zodra je een bedrag meestuurt. Stuur geen 49.95 als amount. OpenAI verwacht een geheel getal in de kleinste valuta-eenheid.

De Conversions API ondersteunt onder meer gehashte e-mailadressen, gehashte external IDs, IP-adres en user agent. Dit kan de matchkwaliteit verbeteren, maar alleen als je die gegevens rechtmatig mag verzamelen en doorsturen.

De Stape-template kan veelgebruikte velden automatisch mappen en SHA-256 hashen. Controleer altijd of een veld al gehasht is en of de normalisatie klopt. Hashing is geen anonimiseren en verandert niets aan de noodzaak van een passende grondslag en transparante informatie aan de gebruiker.

Koppel de CAPI-tag aan de juiste consentstatus. De Stape-template ondersteunt een check op Google Consent Mode ad_storage. Gebruik dat als extra technische controle, maar valideer ook wat jouw CMP feitelijk doorgeeft aan de servercontainer.

Stap 5: Test met Validate Only en zet daarna live

Nu is het tijd om te controleren of alles goed werkt.

  1. Open Preview in zowel je webcontainer als servercontainer.
  2. Start met Validate Only ingeschakeld in de CAPI-tag. De API valideert het event dan zonder het voor meting op te slaan.
  3. Open een test-URL met oppref en accepteer marketingtracking.
  4. Voer je testconversie uit.
  5. Controleer in de webcontainer of het bron-event afvuurt.
  6. Controleer in de servercontainer of de GA4 Client het event ontvangt en de CAPI-tag precies één keer afvuurt.
  7. Controleer de tagoutput op Pixel ID, eventnaam, event ID, source_url, oppref, amount en currency.
  8. Zet Validate Only pas op false wanneer de testpayload klopt.
  9. Publiceer de container en test opnieuw met een nieuwe testconversie.
  10. Controleer in ChatGPT Ads Manager of het event wordt ontvangen en of de juiste conversion event aan je campagne hangt. Attributed conversions kunnen 24 tot 48 uur later in rapportages verschijnen.

Een geslaagde validate_only-test bewijst dat de payload valide is. Het bewijst niet dat er een advertentieklik gematcht kan worden, dat je campaign conversion event juist is ingesteld of dat een browser- en serverevent goed worden gededupliceerd. Test die onderdelen dus apart.

Vervolgstappen

Je server-side CAPI-event kan nu een aanvulling zijn op je browserpixel. Houd de setup overzichtelijk: kies één bron-event, map één correcte ChatGPT-eventnaam en breid pas uit als de data klopt.

Veelgestelde vragen over ChatGPT Ads Conversion API (CAPI)

Heb ik de ChatGPT Ads Pixel nog nodig als ik de Conversions API gebruik?

Niet voor elk scenario, maar de combinatie is meestal sterker dan alleen CAPI. De Pixel kan oppref automatisch uit de browser opvangen en in een first-party cookie bewaren. Gebruik je beide voor dezelfde conversie, regel dan deduplicatie met dezelfde event ID.

Kan ik de Conversions API direct vanuit mijn website aanroepen?

Nee. De API key hoort niet in browsercode. Stuur CAPI-events uitsluitend vanuit je server, bijvoorbeeld via server-side Google Tag Manager, je backend of een betrouwbare integratiepartner.

Welke events kan ik het beste gebruiken?

Kies het standaardevent dat de actie het best beschrijft. Voorbeelden: lead_created voor een contactaanvraag, appointment_scheduled voor een geboekte demo en order_created voor een voltooide bestelling. Gebruik een custom event alleen als geen standaardevent past.

Waarom krijg ik minder conversies in ChatGPT Ads Manager dan in GA4?

Dat hoeft geen fout te zijn. OpenAI, GA4 en andere advertentieplatforms kunnen andere attributiemodellen, tijdzones, consentcondities, deduplicatie en rapportagedata gebruiken. Controleer eerst of je dezelfde periode, tijdzone en eventdefinitie vergelijkt. Een ontvangen event is bovendien nog niet automatisch een aan een ChatGPT Ads-klik toegeschreven conversie.

Kan ik offline of CRM-conversies sturen?

Ja, de Conversions API ondersteunt ook action sources zoals offline, physical_store, phone_call en email. Dat vereist wel een eigen, betrouwbare server-to-server koppeling. Een standaard sGTM-webevent is daarvoor meestal niet voldoende, omdat het oorspronkelijke event niet vanuit een browser komt.

Bronnen

Deel dit artikel
Verhoog de effectiviteit van jouw campagnesBekijk Savvy Track

Denk je dat je genoeg weet?

Krijg het nieuwste in je inbox.
Copyright © 2023 - 2026