Pinterest Conversions API voor Shopify: een installatiegids

De Pinterest Conversions API is de server-naar-server-manier van Pinterest om conversie-events te versturen. Je webshop, of een tool zoals ROASaurus, stuurt events zoals aankopen rechtstreeks naar je Pinterest-advertentieaccount, in plaats van alleen te vertrouwen op de Pinterest Tag in de browser van de shopper. Pinterest gebruikt de data voor conversierapportage, campagneoptimalisatie en targeting.

Deze gids behandelt de v5-API en de events die die accepteert, het click-id epik, hoe klantgegevens worden gehasht, hoe ontdubbeling met de Pinterest Tag werkt, hoe je test en hoe je alles instelt op Shopify.

Wat is de Pinterest Conversions API?

De Pinterest Tag is een script in de browser van de shopper. De Conversions API doet hetzelfde werk vanaf een server. In API-versie 5 stuur je events naar het events-endpoint van je advertentieaccount, geautoriseerd met een toegangstoken voor conversies dat je aanmaakt in Pinterest Ads Manager. Elk event geeft aan waar het plaatsvond: voor een webshop is de actiebron web.

Pinterest vraagt adverteerders die ook de Tag gebruiken om een conversie niet dubbel te tellen, door bij elk event een event_id mee te sturen. Pinterest vraagt ook om events in realtime, of uiterlijk een uur nadat ze plaatsvinden.

Op Shopify heeft een serververbinding één duidelijk voordeel: aankopen komen uit de bestelling zelf. Shopify meldt elke betaalde bestelling via een webhook aan ROASaurus, en ROASaurus stuurt die kort na de betaling naar Pinterest, ongeacht of de Tag in de browser is afgegaan. De gids over server-side tracking op Shopify legt het idee uitgebreider uit.

Welke events accepteert de Pinterest Conversions API?

Pinterest heeft een vaste lijst met standaardeventnamen, geschreven in kleine letters met underscores, zoals page_visit, add_to_cart en checkout. Je kunt per adverteerder ook maximaal 15 custom eventtypes definiëren. ROASaurus koppelt de vijf winkelevents van Shopify als volgt:

De naam kan verwarrend zijn. De checkout van Pinterest is de afgeronde aankoop, niet het begin van de checkout. Het begin van de checkout is een apart event, initiate_checkout.

Voor het checkout-event raadt Pinterest aan om de waarde, de valuta, het bestel-id, de content-id's en het aantal artikelen mee te sturen. ROASaurus stuurt alle vijf mee, plus de hoeveelheid en prijs van elk artikel. Pinterest vraagt om de waarde vóór belasting en verzendkosten. Op Shopify stuurt ROASaurus precies dat: het bestelbedrag min belasting en verzendkosten, vanaf de server en vanuit de browsertag. Als een webshopplatform belasting en verzendkosten niet apart doorgeeft, stuurt ROASaurus het bestelbedrag.

Hoe koppelt Pinterest een event aan een persoon?

Elk event bevat gebruikersdata. Pinterest vereist minstens één van drie dingen: een gehasht e-mailadres, een gehasht mobiel advertentie-id, of het IP-adres samen met de user agent. Een webshop heeft geen advertentie-id, dus die heeft het e-mailadres of het IP-adres en de user agent nodig. ROASaurus slaat een event over dat geen van beide heeft, in plaats van een event te versturen dat Pinterest niet kan gebruiken.

Het click-id epik

Het click-id van Pinterest kan uit twee bronnen komen: een parameter epik in de URL van de landingspagina, of de cookie _epik op je domein. De API-gids van Pinterest raadt aan de waarde van de cookie _epik door te geven, omdat die ook werkt als de URL-parameter ontbreekt of is verwijderd, wat een betere dekking geeft.

ROASaurus leest beide in je webshop en gebruikt de URL-parameter wanneer een nieuwe klik er een meebrengt, en anders de cookie. Het slaat het click-id op bij de bezoeker en verstuurt het in het veld click_id van elk serverevent, ook bij de aankoop. Bezoeken met een epik tellen in de attributierapporten van ROASaurus als Pinterest-bezoeken.

POST https://api.pinterest.com/v5/ad_accounts/549755885175/events

{
  "data": [{
    "event_name": "checkout",
    "action_source": "web",
    "event_time": 1793016000,
    "event_id": "order-5512345678901",
    "event_source_url": "https://example-store.com/checkouts/…/thank-you",
    "user_data": {
      "em": ["a3f1…9c2e"],
      "ph": ["7b40…11d8"],
      "external_id": ["e05c…4a7f"],
      "client_ip_address": "203.0.113.24",
      "client_user_agent": "Mozilla/5.0 (iPhone; …)",
      "click_id": "dj0yJnU9…"
    },
    "custom_data": {
      "currency": "USD",
      "value": "84",
      "order_id": "5512345678901",
      "content_ids": ["44123456789"],
      "contents": [{ "id": "44123456789", "quantity": 2, "item_price": "42" }],
      "num_items": 2
    }
  }]
}

Hoe werkt ontdubbeling met de Pinterest Tag?

Als de Tag en de API allebei een aankoop melden, ontvangt Pinterest twee events voor één bestelling. Om ze als één te behandelen, is aan beide kanten hetzelfde id nodig: het event-id in de Tag moet overeenkomen met de event_id in het serverevent. Pinterest houdt het eerste event dat het ontvangt en verwijdert duplicaten die binnen 48 uur binnenkomen.

ROASaurus bouwt het id van de aankoop op uit het bestel-id van Shopify. De aankoop van bestelling 5512345678901 heeft het event-id order-5512345678901, zowel in de Tag die in de checkout afgaat als in het serverevent.

Alle vijf de events worden ontdubbeld

Elk shoppingevent in ROASaurus heeft één event-id, dat de Tag in de browser en het serverevent gebruiken. De Tag gebruikt de eigen namen van Pinterest voor dezelfde events: pagevisit, viewcontent, addtocart, initiatecheckout en checkout, die overeenkomen met page_visit, view_content, add_to_cart, initiate_checkout en checkout in de API. Als beide draaien, houdt Pinterest dus één kopie over van elk paginabezoek, elke productweergave, elke toevoeging aan de winkelwagen, elke start van de checkout en elke aankoop.

Je kunt het op twee manieren draaien:

• Tag en Conversions API samen. De Tag voegt browsersignalen toe, de server vult aan wat de Tag mist, en Pinterest voegt de kopieën samen.
• Draai de API zonder de Tag. Laat het Tag-ID leeg of zet Also load the browser tag uit. Elk event wordt dan één keer verstuurd, alleen vanaf de server.

Het helpartikel over dubbel tellen behandelt dezelfde controles voor de andere advertentieplatforms.

Hoe test je de Pinterest Conversions API?

De API heeft een testvlag. Verzoeken die met test=true worden verstuurd, gaan naar een sandbox: Pinterest behandelt ze als testdata en gebruikt ze niet voor rapportage of optimalisatie.

1. Zet de testmodus aan

   Bewerk in ROASaurus de Pinterest-pixel onder Tracking & platforms en vink Test mode (events show under Test events, max 20) aan. Elk serverevent wordt dan met test=true verstuurd. Pinterest verwerkt maximaal 20 testevents per batch.

2. Plaats een testbestelling

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

3. Lees het resultaat

   Open de Event log. Pinterest kan met HTTP 200 antwoorden terwijl één event in een verzoek is mislukt, dus ROASaurus controleert de status van elk event en toont mislukkingen daar.

4. Zet de testmodus uit

   Vink de testmodus uit, zodat events meetellen in rapportage en optimalisatie.

5. Controleer de Events Overview

   Open in Pinterest Ads Manager de pagina Events Overview. Die toont de events die binnenkomen en de ontdubbelde conversies. Pinterest raadt aan te streven naar een Good Event Quality Score.

Zo stel je de Pinterest Conversions API in op Shopify met ROASaurus

Je hebt een Shopify-webshop nodig met de ROASaurus-app en toegang tot Pinterest Ads Manager. De Pinterest-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. Die legt epik en de cookie _epik vast op elke pagina. De Shopify-installatiegids toont elke stap.

2. Maak een toegangstoken voor conversies aan

   Ga in Pinterest Ads Manager naar Conversions en maak een toegangstoken voor conversies aan. Noteer je ID van het advertentieaccount.

3. Voeg de Pinterest-pixel toe in ROASaurus

   Ga naar Tracking & platforms, klik op Add pixel bij de Pinterest-kaart en vul Ad account ID en Conversion access token in.

4. Voeg je Tag-ID toe

   Vul voor ontdubbeling met de Tag Pinterest Tag ID in en laat Also load the browser tag aangevinkt. Zonder Tag-ID verstuurt ROASaurus alleen serverevents en laadt het de Tag niet.

5. 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 het checkout-event van de Tag af in de checkout van Shopify, met het bestel-id als event_id.

6. Kies serverevents en test dan

   Kies de serverevents die je wilt en test met de testmodus voordat je live gaat.

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 Pinterest Tag niet geladen, wordt er geen bezoeker-id ingesteld, zodat de klikken niet aan die shopper worden gekoppeld, en worden de browse-events niet naar Pinterest gestuurd. De betaalde bestelling wordt nog steeds vanaf de server naar de Conversions API verstuurd, met gehashte bestelgegevens en het IP-adres en de user agent van de bestelling, maar zonder click-id. De gids over toestemming en privacy legt uit wat er wordt opgeslagen en verstuurd.

Koppel je Pinterest-advertentieaccount onder Setup › Ad spend en ROASaurus haalt elk uur de campagne-uitgaven op, zodat je Pinterest-ROAS en winst na advertenties ziet in winstanalyse. De gids over de TikTok Events API behandelt dezelfde opzet voor TikTok, waar elk event dat beide kanten op gaat wordt ontdubbeld.

Bronnen

1. Pinterest Developers: Track conversion events in the API
2. Pinterest Business help: The Pinterest Conversions API
3. Pinterest Developers: Track conversions with Pinterest Tag

In ROASaurus

• Pinterest-integratie
• Server-side tracking in ROASaurus
• Help: dubbeltelling voorkomen

Lees verder