Meta Conversions API (CAPI) : un guide pratique

La Meta Conversions API (CAPI) permet à votre serveur d’envoyer des événements comme Purchase directement à Meta. Le pixel Meta envoie les mêmes événements depuis le navigateur de l’acheteur. CAPI les envoie depuis votre serveur : ils arrivent donc même quand un bloqueur de publicités arrête le pixel, qu’un cookie a disparu ou que la page de remerciement ne se charge jamais.

Ce guide présente ce que contient un événement de la Conversions API, comment l’utiliser en parallèle du pixel avec un seul event_id, quels paramètres Meta exige et recommande, comment tester avec Test events, et les erreurs les plus fréquentes.

Qu’est-ce que la Meta Conversions API ?

La Conversions API fait partie de la Graph API de Meta. Votre serveur envoie une requête HTTPS POST à graph.facebook.com/VERSION/PIXEL_ID/events avec un jeton d’accès et une liste data de 1,000 événements au maximum. Chaque événement décrit une action, comme un achat, en trois parties : ce qui s’est passé, qui l’a fait et les détails.

Voici à quoi ressemble un événement Purchase simplifié :

{
  "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" }
  }]
}

Les champs de contact comme l’e-mail et le téléphone sont normalisés et hachés avec SHA-256 avant de quitter votre serveur. L’adresse IP, le user agent, fbp et fbc sont envoyés tels quels.

Pourquoi utiliser la Conversions API en parallèle du pixel ?

Meta recommande d’utiliser la Conversions API en parallèle du pixel et d’envoyer les mêmes événements par les deux voies. Chacune voit ce que l’autre ne voit pas, et ensemble elles donnent à Meta des données plus complètes.

Utiliser les deux a un coût : Meta reçoit désormais deux copies de chaque événement. La section suivante montre comment Meta n’en garde qu’une.

Comment fonctionne la déduplication avec un seul event_id ?

Meta considère un événement navigateur et un événement serveur comme un seul et même événement quand deux éléments correspondent : le nom de l’événement et l’identifiant d’événement. Dans le pixel, l’identifiant va dans l’option eventID. Dans la Conversions API, la même valeur va dans event_id.

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

Meta ne déduplique une paire correspondante que si les deux copies arrivent à moins de 48 heures d’intervalle. Quelques règles permettent que cela fonctionne en pratique :

• Créez l’identifiant une seule fois. Construisez-le à partir d’un élément que les deux côtés connaissent, comme le numéro de commande, et transmettez-le au navigateur et au serveur. Deux systèmes qui fabriquent chacun leur propre identifiant ne correspondront pas.
• Utilisez un seul format. order-1042 et 1042 sont deux identifiants différents.
• Respectez exactement le nom de l’événement. Purchase et purchase sont des événements différents.
• Envoyez rapidement l’événement serveur. Un événement serveur qui arrive plus de 48 heures après l’événement navigateur est compté une seconde fois.

Meta décrit aussi une seconde méthode qui associe les événements par fbp ou external_id. Meta indique qu’elle ne fonctionne généralement que si l’événement navigateur arrive avant l’événement serveur : un event_id commun est donc le choix le plus fiable. Si Meta signale encore plus d’achats que votre boutique n’en a eu, notre guide sur les événements d’achat en double liste les causes habituelles.

Quels paramètres sont obligatoires, et lesquels sont recommandés ?

Les champs obligatoires rendent un événement valide. Les champs recommandés déterminent combien de vos événements Meta peut associer à une personne, et seuls les événements associés peuvent servir à l’attribution et à la diffusion des publicités.

Trois détails causent la plupart des problèmes :

• Normalisez avant de hacher. Meta attend un e-mail sans espaces superflus et en minuscules, et des numéros de téléphone sous forme de chiffres avec l’indicatif du pays. Anna@Example.com et anna@example.com donnent des empreintes différentes, et seule la seconde peut correspondre.
• Ne hachez pas les identifiants du navigateur. fbp, fbc, l’adresse IP et le user agent sont envoyés en clair.
• Conservez l’identifiant de clic exactement tel quel. La valeur fbc se compose de fb.1., de l’heure de création en millisecondes, d’un point, puis du fbclid de l’URL de la page d’arrivée. Le fbclid est sensible à la casse. Enregistrez-le quand le visiteur arrive, car il n’est plus dans l’URL au moment du checkout.

La qualité de correspondance de ces champs est ce que mesure le score Event Match Quality de Meta. Notre guide sur l’Event Match Quality couvre chaque paramètre, les règles de hachage et le score à viser.

Comment tester les événements avec Test events ?

Events Manager propose un onglet Test events qui affiche les événements à mesure qu’ils arrivent. Utilisez-le avant de vous fier à une nouvelle configuration.

1. Ouvrez Test events

   Dans Events Manager, sélectionnez votre jeu de données (pixel) et ouvrez l’onglet Test events. Copiez le code de test qu’il affiche.

2. Ajoutez le code à vos événements serveur

   Envoyez-le sous le nom test_event_code dans la requête. Dans ROASaurus, collez-le dans le champ Test event code du pixel Meta.

3. Passez une commande de test

   Visitez la boutique, ajoutez un produit et payez, afin que le pixel et le serveur envoient chacun un Purchase.

4. Comparez les deux copies

   Les deux copies doivent afficher le même nom d’événement, le même identifiant d’événement, la même valeur et la même devise.

5. Vérifiez les informations client

   L’événement serveur doit contenir l’e-mail et le téléphone hachés, l’adresse IP, le user agent et fbp, ainsi que fbc si la visite a commencé par un clic publicitaire.

6. Retirez le code de test

   Meta précise que ce champ sert uniquement aux tests : retirez-le donc avant de vous fier aux événements.

Erreurs courantes de la Conversions API et comment les corriger

Après quelques jours de trafic réel, ouvrez l’onglet Diagnostics dans Events Manager. Meta y liste les problèmes avec des recommandations pour les corriger. Comparez ensuite le nombre quotidien de Purchase dans Events Manager avec les commandes payées de votre boutique pour les mêmes jours. Si Meta est nettement au-dessus, notre page d’aide sur la prévention du double comptage liste les réglages à vérifier.

Comment configurer la Conversions API avec ROASaurus

ROASaurus envoie les événements de la Conversions API à partir des données de commande de votre boutique : vous n’avez donc pas à construire vous-même la partie serveur. Dans Tracking & platforms, cliquez sur Connect with Facebook et choisissez votre compte publicitaire et votre pixel, ou collez l’identifiant du pixel (jeu de données) et un jeton de la Conversions API. Le guide de configuration de Meta détaille les deux options, et la page de l’intégration Meta liste chaque champ envoyé.

• Un seul identifiant des deux côtés. Les événements navigateur et serveur partagent un même identifiant d’événement. Pour un achat, c’est order- suivi de l’identifiant de la commande.
• Une courte attente avant l’achat. Le Purchase serveur attend un court instant après l’arrivée de la commande, afin que l’événement d’achat du navigateur puisse être associé d’abord. Son adresse IP, son user agent et l’URL de la page partent alors avec l’événement serveur, ainsi que les fbp et fbc enregistrés pour le visiteur.
• Les informations client issues de la commande. L’e-mail, le téléphone, le nom et l’adresse sont normalisés et hachés avec SHA-256. L’identifiant client de la boutique et l’identifiant visiteur ROASaurus sont envoyés hachés comme external_id.
• Les événements que Meta ne peut pas associer sont ignorés. Un événement sans fbc, fbp, e-mail, téléphone ni adresse IP n’est pas envoyé.

L’Event log montre chaque envoi serveur avec la requête et la réponse de Meta. Si vos marges diffèrent beaucoup d’un produit à l’autre, vous pouvez aussi envoyer une valeur de bénéfice à côté de chaque achat : notre guide sur l’optimisation de la valeur Meta pour le bénéfice explique comment. Pour le chemin complet des données, du clic à la commande, voir le suivi côté serveur.

Sources

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

Dans ROASaurus

• Intégration Meta
• Aide : connecter Meta
• Aide : éviter le double comptage
• Suivi côté serveur

À lire aussi