OpenAI Conversions API voor WooCommerce

In de browser verstuurt de Measurement Pixel productweergaven, toevoegingen aan de winkelwagen, het begin van het afrekenen en de aankoop. Zodra WooCommerce een betaalde bestelling bevestigt, wordt de aankoop ook vanaf je server verstuurd via de OpenAI Conversions API, met hetzelfde event-ID, zodat OpenAI hem één keer kan tellen.

De Measurement Pixel draait in de browser van de klant. Alleen daar zie je productweergaven en wat er in de winkelwagen gebeurt, maar het betekent ook dat een event verloren gaat zodra de pagina of het script niet helemaal wordt uitgevoerd:

• Contentblockers of privacytools houden het pixelscript tegen.
• De klant sluit na het betalen het tabblad, voordat de pagina Bestelling ontvangen laadt.
• Een betaling wordt pas later bevestigd, bijvoorbeeld bij een bankoverschrijving of sommige betaalmethoden met een doorverwijzing, als de klant al van de site weg is.
• Een trage of mislukte paginalading laat het verzoek wegvallen.

In al die gevallen legt WooCommerce de bestelling gewoon vast. Een server-side aankoop-event vertrekt vanuit die bestelling, dus geen van deze situaties houdt het tegen.

Je server doet een geauthenticeerd HTTPS-verzoek naar OpenAI met één of meer events. Het verzoek is geadresseerd aan je Pixel-ID en geautoriseerd met een Conversions API-key. Beide maak je aan op het tabblad voor conversies in Ads Manager (documentatie van de OpenAI Conversions API, Engelstalig, net als de andere documentatie van OpenAI waarnaar deze gids linkt).

Verstuur hem zodra WooCommerce de bestelling op een betaalde status zet, niet wanneer de pagina Bestelling ontvangen wordt getoond. Koppel je het event aan de bestelstatus in plaats van aan een paginaweergave, dan:

• wordt het één keer per bestelling verstuurd, hoe vaak de bedankpagina ook wordt herladen;
• gaat bij betaalmethoden met een latere bevestiging de aankoop pas weg als de betaling echt binnen is;
• worden onbetaalde, mislukte of afgebroken bestellingen niet als aankoop gemeld.

1. Afrekenen afgerond

   Bestelling aangemaakt in WooCommerce

2. Betaling bevestigd

   Bestelling krijgt een betaalde status

3. Aankoop verstuurd

   order_created vanaf je server

4. Resultaat vastgelegd

   Geaccepteerd, opnieuw geprobeerd of mislukt

Wordt een aankoop vanuit de browser én vanaf de server verstuurd, dan moet OpenAI kunnen zien dat het om één aankoop gaat. Volgens OpenAI gebeurt de deduplicatie op basis van je Pixel-ID, de event_name en het id: het eerste event dat binnenkomt met een overeenkomende sleutel telt, latere duplicaten worden genegeerd.

Het event-ID moet dus op beide routes identiek zijn. De betrouwbare manier om dat in WooCommerce te regelen, is het ID afleiden van de bestelling, die zowel de pagina Bestelling ontvangen als de server kent. Een willekeurig ID dat in de browser wordt aangemaakt, krijgt de server nooit te zien. De gids Pixel vs Conversions API laat zien hoe de twee routes in elkaar grijpen.

OpenAI weigert events buiten een bepaald tijdvenster: het tijdstempel mag niet ouder zijn dan 7 dagen en niet meer dan 10 minuten in de toekomst liggen. Voor een webshop heeft dat twee gevolgen:

• Verstuur het oorspronkelijke aankoopmoment, niet het moment van de poging. Anders beweert een opnieuw verstuurd event dat de aankoop later plaatsvond dan in werkelijkheid.
• Los mislukte leveringen snel op. Een bestelling waarvan het aankoopmoment meer dan 7 dagen oud is, kan niet meer worden verstuurd.

De API accepteert ook batches van maximaal 1.000 events, en volgens OpenAI mislukt de hele batch als één event erin mislukt. Eén foute bestelling kan dus andere tegenhouden als een implementatie slordig batcht.

De documentatie van OpenAI zegt dat je hetzelfde ID hergebruikt wanneer je een conversie opnieuw probeert of dezelfde conversie via een andere koppeling verstuurt. Een schema voor nieuwe pogingen publiceert OpenAI niet; dat beleid bepaalt de implementatie. Een verstandig beleid maakt onderscheid tussen:

Welk beleid je ook kiest, een fout moet ergens zichtbaar zijn. Zonder vastlegging per bestelling ziet een kapotte koppeling er precies zo uit als een rustige verkoopweek.

Server-side versturen is geen manier om toestemming te omzeilen. De Pixel zelf verstuurt geen meetpings als de toestemming op false staat (documentatie van de Measurement Pixel), en een server-side aankoop hoort de toestemming te volgen die voor die bestelling is vastgelegd. In WordPress is de WordPress Consent API de gangbare manier waarop een cookiebanner die status met andere plugins deelt.

Pixel for ChatGPT Ads is een WooCommerce-plugin die alleen de aankoop server-side verstuurt. Dit is wat de plugin doet op elk van de punten hierboven:

Vergroten (schermafbeelding)

Sluiten

Productweergaven, toevoegen aan winkelwagen en het begin van het afrekenen blijven browser-events. Het overzicht van de ChatGPT Pixel voor WooCommerce noemt elk event en van waaruit het wordt verstuurd.