TikTok Events API voor Shopify: installatie en ontdubbeling

De TikTok Events API is de server-naar-server-verbinding van TikTok voor conversiedata. In plaats van alleen te vertrouwen op de TikTok-pixel in de browser van de shopper, stuurt je webshop, of een tool zoals ROASaurus, events zoals aankopen rechtstreeks naar TikTok. TikTok raadt aan de Events API naast de pixel te draaien en de twee te ontdubbelen met een gedeelde event_id.

Deze gids behandelt wat de Events API vanuit een Shopify-webshop verstuurt, de eventnamen Purchase en CompletePayment, het click-id en de cookie waarop TikTok koppelt, hoe ontdubbeling werkt, hoe je test in TikTok Events Manager en hoe je alles instelt in ROASaurus.

Wat is de TikTok Events API?

De TikTok-pixel is een script op je webshop. Hij vuurt events af vanuit de browser van de shopper, dus hij telt alleen wat gebeurt terwijl het script laadt en draait. Een adblocker, een scriptfout of een shopper die het tabblad sluit voordat de bestelbevestiging laadt, kan hem allemaal stoppen.

De Events API verstuurt dezelfde soort event vanaf een server. Op Shopify is het meest betrouwbare bewijs van een aankoop de bestelling zelf. Shopify meldt elke betaalde bestelling via een webhook, of het script in de browser nu draaide of niet. Dat is het idee achter server-side tracking op Shopify.

De twee zijn geen alternatieven. Het advies van TikTok is om events via beide kanalen te delen, ze consistent te houden langs de hele klantreis en TikTok de duplicaten te laten verwijderen.

Welke events stuurt ROASaurus naar TikTok?

Vier momenten in een Shopify-webshop zijn belangrijk voor de optimalisatie door TikTok: een productweergave, een toevoeging aan de winkelwagen, de start van de checkout en de aankoop. ROASaurus stuurt alle vier naar de Events API en vuurt dezelfde vier af via de TikTok-pixel, met dezelfde event-id's. Paginaweergaven gaan alleen via de pixel.

In de pixelinstellingen kun je serverevents die je niet wilt versturen uitvinken en filters toevoegen, zoals een land of een minimale bestelwaarde.

Purchase of CompletePayment?

TikTok heeft zijn aankoopevent hernoemd. De huidige naam is Purchase. De oude naam, CompletePayment, werkt nog steeds: TikTok zet oude namen aan zijn kant om, toont ze onder de nieuwe naam in rapportage, doelgroepen en optimalisatie, en zegt dat CompletePayment voor onbepaalde tijd wordt ondersteund. TikTok vraagt nieuwe pixelopzetten om Purchase te gebruiken.

ROASaurus verstuurt CompletePayment, in de pixel en in de Events API. In TikTok Events Manager en Ads Manager worden die events als Purchase getoond. Voor ontdubbeling telt dat beide kopieën van een aankoop dezelfde eventnaam gebruiken, en dat doen ze.

Hoe koppelt TikTok een event aan een shopper?

Een event helpt je campagnes alleen als TikTok het kan koppelen aan de persoon die de advertentie zag of aanklikte. TikTok noemt deze identifiers matchsleutels, en de Events API-gids vraagt je alle relevante matchsleutels terug te geven om het matchpercentage te verhogen. Events Manager toont het resultaat als een Event Match Quality-score, een gewogen gemiddelde van hoe vaak elke matchsleutel aanwezig is.

TikTok merkt op dat de pixel het IP-adres en de user agent standaard deelt, maar dat ze bij de Events API met de hand moeten worden toegevoegd. ROASaurus haalt ze uit de checkoutsessie van de shopper, of uit de bestelling als er geen sessie was. Twee andere sleutels vragen op Shopify aandacht.

ttclid: het click-id van TikTok

Wanneer een shopper op een TikTok-advertentie klikt, voegt TikTok ttclid toe aan de URL van de landingspagina. Als je webshop het niet op die eerste pagina opslaat, is het weg tegen de tijd dat de bestelling binnenkomt, meerdere pagina's later. ROASaurus leest ttclid op de landingspagina, slaat het op bij het bezoeker-id, schrijft het naar de winkelwagen van Shopify en voegt het toe aan het serverevent wanneer de bestelling binnenkomt.

_ttp: de pixelcookie

De cookie _ttp is een first-party cookie die de TikTok-pixel op je domein gebruikt. ROASaurus leest hem in de webshop en in de checkout en verstuurt hem als ttp in het serverevent. Het is een reden te meer om de pixel naast de Events API te laten draaien.

{
  "event_source": "web",
  "event_source_id": "CXXXXXXXXXXXXXXXXXXX",
  "data": [{
    "event": "CompletePayment",
    "event_time": 1793016000,
    "event_id": "order-5512345678901",
    "user": {
      "email": "a3f1…9c2e",
      "phone": "7b40…11d8",
      "external_id": "e05c…4a7f",
      "ttclid": "E.C.P.v3…",
      "ttp": "2Xb7…",
      "ip": "203.0.113.24",
      "user_agent": "Mozilla/5.0 (iPhone; …)"
    },
    "page": { "url": "https://example-store.com/checkouts/…/thank-you" },
    "properties": {
      "currency": "USD",
      "value": 84,
      "content_type": "product",
      "contents": [{ "content_id": "44123456789", "content_name": "Linen shirt", "quantity": 2, "price": 42 }],
      "order_id": "5512345678901"
    }
  }]
}

Hoe werkt ontdubbeling?

Wanneer de pixel en de Events API dezelfde aankoop melden, ontvangt TikTok twee events voor één bestelling. Om er maar één te houden, moet TikTok in beide kopieën twee identieke waarden zien: de eventnaam en de event_id. TikTok registreert dan de eerste kopie die het ontvangt voor meting en rapportage, zodat de bestelling één keer telt. Dit werkt voor overeenkomende kopieën die binnen een venster van 48 uur na de eerste binnenkomen.

ROASaurus bouwt het event-id voor een aankoop op uit het bestel-id van Shopify. De aankoop van bestelling 5512345678901 heeft het event-id order-5512345678901, in de checkout-pixel en op de server. Events in de webshop, zoals productweergaven en toevoegingen aan de winkelwagen, krijgen een willekeurig id wanneer ze plaatsvinden, en de browserkopie en de serverkopie delen dat.

Zo werkt dat uit voor de cijfers. Neem een voorbeeldwebshop met 200 bestellingen in een week. De pixel gaat af voor 150 daarvan. De andere 50 shoppers gebruikten een adblocker, weigerden marketingcookies of vertrokken voordat de bevestigingspagina laadde. De Events API verstuurt alle 200.

De 350 is het getal waar je je zorgen over moet maken. Het zou het aantal aankopen van TikTok, en de ROAS die daarop is gebaseerd, 75% hoger maken dan de werkelijkheid, omdat 350 ÷ 200 = 1.75. TikTok gebruikt deze events ook voor optimalisatie en targeting, dus het bieden zou leren van 150 aankopen die niet hebben plaatsgevonden.

Waarom worden aankopen op Shopify twee keer geteld?

Dubbel tellen gebeurt wanneer TikTok twee kopieën van een aankoop ontvangt die het niet kan koppelen. Controleer deze oorzaken voordat je een sprong in TikTok-aankopen vertrouwt:

• Twee tools versturen dezelfde pixel. De app voor het verkoopkanaal van TikTok op Shopify kan ook events voor je pixel versturen. De event-id's daarvan komen niet overeen met de id's die ROASaurus gebruikt, dus TikTok telt elke bestelling twee keer. Koppel de pixel in die app los.
• De pixel staat ook in je themacode. Een pixelsnippet die in het thema is geplakt, vuurt eigen events af zonder jouw event-id's. Verwijder hem en laat één tool de pixel laden.
• Eén kant heeft geen event_id. Een serveraankoop zonder event_id, of met een nieuw willekeurig id, kan niet worden gekoppeld aan de pixelkopie.
• De eventnamen verschillen. TikTok ontdubbelt alleen identieke events. Beide kopieën van een aankoop moeten dezelfde eventnaam gebruiken.

Het helpartikel over dubbel tellen doorloopt dezelfde controles voor Meta en de andere platforms.

Hoe test je de Events API in TikTok Events Manager?

TikTok Events Manager heeft een tabblad Test events voor zowel browser- als serverevents. Gebruik het voordat je op de data vertrouwt:

1. Kopieer een testeventcode

   Open in TikTok Events Manager je pixel en ga naar Test events. Kopieer de testeventcode.

2. Plak hem in ROASaurus

   Open Tracking & platforms, bewerk de TikTok-pixel en plak de code in het veld Test event code. Serverevents bevatten hem vanaf dan.

3. Plaats een testbestelling

   Bezoek je webshop, bekijk een product, voeg het toe aan de winkelwagen en rond een bestelling af.

4. Controleer beide kanten

   Filter in Test events op browser- en serverevents. Je zou de aankoop van beide moeten zien. In ROASaurus toont de Event log elke serverlevering als verzonden of mislukt.

5. Verwijder de testcode

   Verwijder de testeventcode als je klaar bent, zodat je live serverevents niet langer als testevents worden verstuurd.

TikTok kan een verzoek met HTTP 200 beantwoorden en het event toch afwijzen, met een foutcode in de responsbody. ROASaurus leest die code, dus een afgewezen event verschijnt als mislukt in de Event log in plaats van ongemerkt door te gaan.

Open na een dag live verkeer het overzicht van de pixel in Events Manager. Dat toont elk event met zijn verbindingsmethode, Event Match Quality-score en het moment van laatste ontvangst. De eventdetails bevatten informatie over matching en ontdubbeling, en Diagnostics toont kwaliteitsproblemen met uitleg over hoe je ze oplost.

Zo stel je de TikTok Events API in op Shopify met ROASaurus

Je hebt een Shopify-webshop nodig met de ROASaurus-app en toegang tot TikTok Events Manager. De TikTok-integratiepagina toont elk veld dat ROASaurus verstuurt.

1. Koppel je Shopify-webshop

   Ga naar Add a store › Shopify, klik op Install app en zet de ROASaurus-app-embed aan in de thema-editor. De embed legt ttclid en de cookie _ttp vast op elke pagina. De Shopify-installatiegids toont elke stap.

2. Voeg de checkout-pixel toe

   Voeg in Shopify admin › Settings › Customer events een custom pixel met de naam ROASaurus toe en plak de snippet van je pagina Tracking & platforms. Die vuurt de TikTok-pixel af in de checkout, inclusief de browserkopie van de aankoop.

3. Maak een toegangstoken aan

   Open in TikTok Events Manager je pixel en genereer in de instellingen een toegangstoken voor de Events API. Kopieer het token en de pixelcode.

4. Voeg de TikTok-pixel toe in ROASaurus

   Ga naar Tracking & platforms, klik op Add pixel bij de TikTok-kaart en vul Pixel code en Events API access token in. Laat Also load the browser pixel (recommended, deduplicated) aangevinkt, zodat browser- en serverevents id's delen.

5. Voeg uitgaven toe (optioneel)

   Vul Advertiser ID for spend en een Marketing API token in. ROASaurus importeert dan de uitgaven van TikTok, zodat TikTok-campagnes ROAS en CPA tonen naast je andere kanalen.

6. Test, en ga dan live

   Verstuur een testbestelling met een testeventcode zoals hierboven beschreven en verwijder daarna de code.

Met Respect visitor consent aan, wat de standaard is, volgt ROASaurus de keuze van de shopper in de cookiebanner van Shopify. Wanneer een shopper marketingcookies weigert, wordt de TikTok-pixel niet geladen, wordt er geen bezoeker-id ingesteld, zodat de klikken niet aan die shopper worden gekoppeld, en worden de browse-events niet naar TikTok gestuurd. De betaalde bestelling wordt nog steeds vanaf de server naar de Events API verstuurd, met gehashte bestelgegevens en het IP-adres en de user agent van de bestelling, maar zonder ttclid of _ttp. De gids over toestemming en privacy legt uit wat er wordt opgeslagen en verstuurd.

Als de uitgaven zijn gesynchroniseerd, verschijnen TikTok-campagnes in attributierapporten naast Meta, en voegt creative-analyse de videostatistieken van TikTok per advertentie toe. ROASaurus crediteert bestellingen aan de advertentieklikken en UTM's die het heeft vastgelegd en telt view-through-conversies alleen als gemodelleerde schatting in het model Clicks & views, dus de totalen verschillen meestal van TikTok Ads Manager. Zie voor de andere server-side platforms de gids over de Pinterest Conversions API en de gids over de Meta Conversions API.

Bronnen

1. TikTok For Business: About Events API
2. TikTok Ads Manager: About Event Deduplication
3. TikTok Ads Manager: How to Adopt TikTok's Updated Standard Events
4. TikTok Ads Manager: How to set up matching events with Events API
5. TikTok Ads Manager: About diagnostic and monitoring tools in TikTok Events Manager

In ROASaurus

• TikTok-integratie
• Server-side tracking in ROASaurus
• Help: dubbeltelling voorkomen
• Help: ROASaurus instellen in Shopify

Lees verder