Meta Conversions API (CAPI): een praktische gids

Met de Meta Conversions API (CAPI) kan je server events zoals Purchase rechtstreeks naar Meta sturen. De Meta-pixel stuurt dezelfde events vanuit de browser van de shopper. CAPI stuurt ze vanaf je server, dus ze komen nog steeds aan als een adblocker de pixel tegenhoudt, een cookie weg is of de bedankpagina nooit laadt.

Deze gids behandelt wat een Conversions API-event bevat, hoe je het naast de pixel laat draaien met één event_id, welke parameters Meta vereist en aanbeveelt, hoe je test met Test events en welke fouten het vaakst voorkomen.

Wat is de Meta Conversions API?

De Conversions API is onderdeel van de Graph API van Meta. Je server stuurt een HTTPS POST-verzoek naar graph.facebook.com/VERSION/PIXEL_ID/events met een toegangstoken en een data-lijst met maximaal 1,000 events. Elk event beschrijft één actie, zoals een aankoop, in drie delen: wat er gebeurde, wie het deed en de details.

Een ingekort Purchase-event ziet er zo uit:

{
  "data": [{
    "event_name": "Purchase",
    "event_time": 1792929600,
    "event_id": "order-1042",
    "action_source": "website",
    "event_source_url": "https://yourstore.com/checkouts/thank-you",
    "user_data": {
      "em": ["<SHA-256 of the normalized email>"],
      "ph": ["<SHA-256 of the normalized phone>"],
      "client_ip_address": "203.0.113.24",
      "client_user_agent": "Mozilla/5.0 (iPhone; ...)",
      "fbp": "fb.1.1792928400000.1234567890",
      "fbc": "fb.1.1792928400000.AbCdEf123"
    },
    "custom_data": { "value": 74.00, "currency": "USD" }
  }]
}

Contactvelden zoals e-mailadres en telefoonnummer worden genormaliseerd en met SHA-256 gehasht voordat ze je server verlaten. Het IP-adres, de user agent, fbp en fbc worden ongewijzigd verstuurd.

Waarom de Conversions API naast de pixel gebruiken?

Meta raadt aan om de Conversions API naast de pixel te gebruiken en dezelfde events via beide te sturen. Elke kant ziet iets wat de andere niet ziet, en samen geven ze Meta completere data.

De prijs van beide gebruiken is dat Meta nu twee kopieën van elk event ontvangt. In het volgende gedeelte zie je hoe Meta er maar één bewaart.

Hoe werkt ontdubbeling met één event_id?

Meta behandelt een browserevent en een serverevent als hetzelfde event wanneer twee dingen overeenkomen: de eventnaam en het event-id. In de pixel gaat het id in de optie eventID. In de Conversions API komt dezelfde waarde in event_id.

fbq('track', 'Purchase', { value: 74.00, currency: 'USD' }, { eventID: 'order-1042' });

Meta ontdubbelt een overeenkomend paar alleen als de twee kopieën binnen 48 uur na elkaar aankomen. Een paar regels zorgen dat dit in de praktijk werkt:

• Maak het id één keer aan. Bouw het op uit iets wat beide kanten kennen, zoals het bestelnummer, en geef het door aan de browser en de server. Twee systemen die elk hun eigen id maken, komen niet overeen.
• Gebruik één formaat. order-1042 en 1042 zijn verschillende id's.
• Zorg dat de eventnaam exact overeenkomt. Purchase en purchase zijn verschillende events.
• Verstuur het serverevent snel. Een serverevent dat meer dan 48 uur na het browserevent aankomt, wordt een tweede keer geteld.

Meta beschrijft ook een tweede methode die events koppelt via fbp of external_id. Volgens Meta werkt die over het algemeen alleen als het browserevent vóór het serverevent aankomt, dus een gedeeld event_id is de betrouwbaardere keuze. Meldt Meta nog steeds meer aankopen dan je webshop had, dan staan in onze gids over dubbele aankoopevents de gebruikelijke oorzaken.

Welke parameters zijn verplicht en welke worden aanbevolen?

De verplichte velden maken een event geldig. De aanbevolen velden bepalen hoeveel van je events Meta aan een persoon kan koppelen, en alleen gekoppelde events kunnen worden gebruikt voor attributie en advertentielevering.

Drie details veroorzaken de meeste problemen:

• Normaliseer voordat je hasht. Meta verwacht e-mailadressen zonder spaties en in kleine letters, en telefoonnummers als cijfers met landcode. Anna@Example.com en anna@example.com geven verschillende hashes, en alleen de tweede kan matchen.
• Hash browser-id's niet. fbp, fbc, het IP-adres en de user agent gaan als gewone waarden mee.
• Houd het click-id precies zoals het is. De waarde van fbc is fb.1., de aanmaaktijd in milliseconden, een punt en de fbclid uit de URL van de landingspagina. De fbclid is hoofdlettergevoelig. Sla die op wanneer de bezoeker landt, want bij de checkout staat die niet meer in de URL.

In hoeverre deze velden overeenkomen, meet de Event Match Quality-score van Meta. In onze gids over Event Match Quality komen elke parameter, de hashregels en de score waar je naar moet streven aan bod.

Hoe test je events met Test events?

Events Manager heeft een tabblad Test events dat events toont zodra ze binnenkomen. Gebruik het voordat je op een nieuwe opzet vertrouwt.

1. Open Test events

   Selecteer in Events Manager je dataset (pixel) en open het tabblad Test events. Kopieer de testcode die daar staat.

2. Voeg de code toe aan je serverevents

   Verstuur hem als test_event_code in het verzoek. Plak hem in ROASaurus in het veld Test event code van de Meta-pixel.

3. Plaats een testbestelling

   Bezoek de webshop, voeg een product toe en betaal, zodat zowel de pixel als de server een Purchase verstuurt.

4. Vergelijk de twee kopieën

   Beide kopieën moeten dezelfde eventnaam, hetzelfde event-id, dezelfde waarde en dezelfde valuta tonen.

5. Controleer de klantgegevens

   Het serverevent moet gehasht e-mailadres en telefoonnummer bevatten, het IP-adres, de user agent en fbp, plus fbc als het bezoek met een advertentieklik begon.

6. Verwijder de testcode

   Meta zegt dat het veld alleen voor testen is, dus verwijder het voordat je op de events vertrouwt.

Veelvoorkomende fouten in de Conversions API en hoe je ze oplost

Open na een paar dagen live verkeer het tabblad Diagnostics in Events Manager. Meta toont daar problemen met aanbevelingen om ze op te lossen. Vergelijk daarna het dagelijkse aantal Purchase-events in Events Manager met de betaalde bestellingen in je webshop voor dezelfde dagen. Is Meta duidelijk hoger, dan staan in onze helppagina over dubbeltelling voorkomen de instellingen die je moet controleren.

De Conversions API instellen met ROASaurus

ROASaurus stuurt Conversions API-events vanuit de bestelgegevens van je webshop, dus je hoeft de serverkant niet zelf te bouwen. Klik in Tracking & platforms op Connect with Facebook en kies je advertentieaccount en pixel, of plak het id van de pixel (dataset) en een Conversions API-token. De Meta-instelgids loopt door beide opties heen, en de Meta-integratiepagina toont elk veld dat wordt verstuurd.

• Eén id aan beide kanten. Browser- en serverevents delen één event-id. Bij een aankoop is dat order- gevolgd door het bestel-id.
• Een korte wachttijd vóór de aankoop. De Purchase van de server wacht even nadat de bestelling binnenkomt, zodat het aankoopevent van de browser eerst kan worden gekoppeld. Het IP-adres, de user agent en de pagina-URL daarvan gaan dan mee met het serverevent, samen met de fbp en fbc die voor de bezoeker zijn opgeslagen.
• Klantgegevens uit de bestelling. E-mailadres, telefoonnummer, naam en adres worden genormaliseerd en gehasht met SHA-256. Het klant-id van de webshop en het bezoeker-id van ROASaurus gaan gehasht mee als external_id.
• Events die Meta niet kan koppelen, worden overgeslagen. Een event zonder fbc, fbp, e-mailadres, telefoonnummer of IP-adres wordt niet verstuurd.

De Event log toont elke serverlevering met het verzoek en het antwoord van Meta. Verschillen je marges sterk tussen producten, dan kun je naast elke aankoop ook een winstwaarde meesturen: onze gids over Meta-waardeoptimalisatie op winst legt uit hoe. Voor het volledige datapad van klik tot bestelling zie je server-side tracking.

Bronnen

1. Meta for Developers: Handling Duplicate Pixel and Conversions API Events
2. Meta for Developers: Server Event Parameters
3. Meta for Developers: Customer Information Parameters
4. Meta for Developers: Using the API - Conversions API
5. Meta for Developers: ClickID and the fbp and fbc Parameters

In ROASaurus

• Meta-integratie
• Help: Meta koppelen
• Help: dubbeltelling voorkomen
• Server-side tracking

Lees verder