Facebook Conversions API

Facebook est un service de médias sociaux et de réseau social en ligne appartenant à Meta. Cette destination vous permet d'envoyer tous types d'événements directement à Facebook via API : en envoyant des conversions en ligne et hors ligne, vous pouvez augmenter la portée et la précision de vos campagnes.

Vous pouvez, par exemple, ne pas envoyer de campagnes liées à un produit spécifique aux utilisateurs qui l'ont déjà acheté, ou vous pouvez aussi envoyer des campagnes aux utilisateurs qui ont acheté un produit spécifique dans une logique de cross-sell.

Comment envoyer des événements à Facebook ?

Facebook a développé une API appelée 'Facebook Conversions API' https://developers.facebook.com/docs/marketing-api/conversions-api

Vous avez besoin d'un compte Facebook Business Manager https://business.facebook.com/

Ensuite, dans le menu, cliquez sur 'Events Manager' :

Ici vous devez créer un nouveau Web Pixel :

Sélectionnez Conversions API et donnez un nom à votre connexion :

Votre pixel est maintenant créé et vous aurez accès aux ID nécessaires sur notre connector.

Où puis-je trouver l'ID du Pixel ?

Vous devez renseigner l'ID du pixel dans notre connector, c'est l'ID du pixel que vous venez de créer dans les étapes ci-dessus.

Vous pouvez trouver cet ID en cliquant sur le nom du pixel et à droite du graphique d'activités. Vous pouvez également le trouver dans l'onglet paramètres.

Vous pouvez maintenant copier et coller cet ID dans notre connector.

Ensuite, vous avez besoin de l'Access Token

Où puis-je trouver l'access token ?

Vous pouvez définir votre access token de deux façons :

1. Facebook Login For Business Authentication

2. Générer un token longue durée

Facebook Login For Business Authentication

1. Dans votre compte Commanders Act, accédez à (1) Administration → (2) Connector Credentials ou cliquez sur le lien ajouter un nouveau compte dans les paramètres de la destination.

2. Cliquez (3) Add connector credentials en haut à droite :

3. Sélectionnez (4) Facebook Ads

4. Connectez-vous avec les identifiants de votre compte Facebook.

5. Allez dans les paramètres de votre destination et sélectionnez vos identifiants ajoutés dans le menu déroulant sous (5) API Authentication → (6) Credentials

6. Enregistrez les paramètres de votre destination.

Générer un token longue durée

1. Allez sur Meta Event Manager

2. Dans le menu de gauche, sélectionnez (1) Data sources .

1. Localisez votre (2) jeu de données existant et sélectionnez-le ou créez un nouveau jeu de données.

1. Cliquez sur l'onglet (3) Settings

1. Localisez le lien (4) Generate access token et cliquez dessus pour générer un access token

1. Copiez et collez votre access token dans le champ API Access Token de votre destination et enregistrez les paramètres de la destination.

Comment gérer les consentements ?

• Seuls les événements avec un consentement seront envoyés à Facebook

• Seules les conversions contenant des informations personnelles (email et/ou numéro de téléphone...) seront envoyées à Facebook

Pour les clients avec notre produit TRUST Commander :

TRUST Commander est notre Consent Management Platform. (Plus d'informations : https://www.commandersact.com/en/solutions/trustcommander/)

Sur le connector, le consentement est géré avec le champ 'User Consent Category'. Vous devez entrer un ID de catégorie, celui correspondant à Facebook (advertising) dans les catégories de consentement Trust.

Pour les clients sans notre produit TRUST Commander :

Nous devons distinguer 3 cas :

• Vos événements en ligne sont collectés via notre tag d'événements Commanders Act : vous devez fournir, dans les tags d'événements, la liste des IDs de catégories consenties par l'utilisateur, via la consent_categories propriété.

• Vous nous envoyez vos événements via API ou fichier CSV : un champ consent_categories doit être ajouté dans le JSON ou le CSV pour préciser les IDs de catégories de consentement de l'utilisateur. Ensuite, dans les paramètres du connector, utilisez le champ 'User Consent Category' pour entrer un ID de catégorie, celui correspondant à Facebook (advertising)

• Vous gérez déjà les consentements de votre côté et vous ne nous envoyez, depuis votre serveur,

  que des événements ayant obtenu le consentement pour la catégorie advertising. Dans ce cas, ne remplissez pas le champ ‘User Consent Category’ dans le connector.

Comment la déduplication entre le pixel et le serveur est-elle gérée ?

L'utilisation à la fois du pixel et du server est recommandée par Facebook car elle peut éviter la perte de données.

Pour que cela fonctionne, vous devez avoir la même configuration pour le pixel et le server, en utilisant les mêmes paramètres Facebook.

Sur le pixel, event_id est généré automatiquement par notre Commanders Act Tag et nous récupérons la même valeur pour le server sur integrations.facebook.event_id. En conséquence, ces 2 valeurs doivent être identiques. Event_name doit être identique également.

Fbp le paramètre est récupéré automatiquement pour garder la même valeur entre le pixel et le server.

La déduplication fonctionne lorsque le même événement est envoyé d'abord depuis le navigateur et ensuite depuis le serveur, sinon cela crée un doublon. Les événements sont envoyés en temps réel.

Exemples

Sur le pixel :

fbq('track', 'AddToCart', {
  value: #CARTVALUE#,
  currency: #CURRENCY#,
  contents: fb_addtocart_products,
  content_type: 'product'
}, { eventID: tC.uniqueEventId });

eventID: tC.uniqueEventId est généré automatiquement.

Sur le server :

integrations.facebook.event_id

integrations.facebook.event_id récupère automatiquement la valeur eventID venant du pixel (eventID: tC.uniqueEventId) pour les événements standard.

Correspondances vers les Facebook Standard Events

Le Facebook CAPI Destination transformera l' événement Commanders Act comme...

{
  "event_name": "purchase",
  "id": "purchase_id_1234",
  "type": "online",
  "user": {
    "email": "[email protected]",
    "id": "user_example_id",
    "tcId": "202205231352367212315156",
    "consistent_anonymous_id": "202205231352367212315156",
    "consent_categories": [ "1", "2", "3", "4" ]
  }
  "value": 246.9,
  "currency": "EUR",
  "items": [
    {
      "product": {
        "id": "product123"
      },
      "price": "123.45",
      "id": "ET",
      "item_category": "Car",
      "item_quantity": 2
    }
  ],
  "context": {
    "event_id": "1a01c3e940f150eb9b8c542587f1abfd8f0e1cc1f",
    "event_timestamp": 1707830130234,
    "page": {
      "location": {
        "href": "https://site.com/path?s=2",
        "hostname": "site.com",
        "pathname": "/path",
        "search": "?s=2"
      },
      "url": "https://site.com/path?s=2"
    },
    "device": {
      "ip": "123.123.123.123",
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36"
    },
    "cookie": "_fbp=fb.1.1653472342558.832801021; some_other=cookie;"
  },
  "integrations": {
    "facebook": {
      "custom_data": {
        "category": "category1"
      },
      "user_data": {
        "fbp": "fb.1.1558571054389.1098115397"
      }
    }
  },
}

...dans Facebook CAPI des événements tels que :

{
  "event_name": "Purchase",
  "event_time": 1707830130,
  "event_source_url": "https://site.com/path?s=2",
  "action_source": "website",
  "user_data": {
    "em": [
      "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514"
    ],
    "external_id": [
      "user_example_id"
    ],
    "client_ip_address": "123.123.123.123",
    "client_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",
    "fbc": "fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890",
    "fbp": "fb.1.1558571054389.1098115397"
  },
  "custom_data": {
    "id": "purchase_id_1234",
    "currency": "EUR",
    "value": 246.9,
    "contents": [
      {
        "id": "product123",
        "quantity": 2,
        "item_price": 123.45
      }
    ]
  }
}

Les correspondances suivantes sont entièrement automatisées et ne nécessitent par défaut aucune configuration supplémentaire. Vous pouvez néanmoins personnaliser chacune comme suit.

Mapping : (root)

Server Event Parameters - Conversions API - Documentation - Meta for DevelopersMeta for Developers

Mapping : event_name

Le Facebook Pixel spécifie Standard Events dont la sémantique correspond aux événements dans le Commanders Act Standard

Si la destination reçoit un Commanders Act Event avec event_name correspondant à la liste, il sera automatiquement envoyé sous le nom du Facebook Standard Event associé. Sinon, il sera envoyé sans aucune transformation

Exemples :

• Si la destination voit un add_to_cart événement (DANS la liste), elle enverra un AddToCart à Facebook CAPI

• Si la destination voit un custom_name événement (PAS DANS la liste), elle enverra un custom_name à Facebook CAPI (aucune transformation)

Mapping : action_source

Server Event Parameters - Conversions API - Documentation - Meta for DevelopersMeta for Developers

Par défaut, action_source sera défini sur 'website' (la plupart des événements concernent l'activité en ligne). SI Activer le suivi d'app est coché ALORS action_source='app'

Spécificité des conversions hors ligne :

• SI votre événement a la propriété type='offline'

• ALORS le Facebook Event aura action_source='physical_store'

• SINON le Facebook Event aura action_source='website'

Exemple :

// CommandersAct
{
  "event_name": "purchase",
  "type": "offline",
  // ...
}

// Événement envoyé à l'API Facebook :
{
  "event_name": "Purchase",
  "action_source": "physical_store"
  "custom_data": { /* */ }
  // ...
}

Si vous avez besoin d'écraser cette valeur, vous pouvez actuellement utiliser Properties Transformation pour définir le integrations.facebook.action_source.

Mapping : user_data

Customer Information Parameters - Conversions API - Documentation - Meta for DevelopersMeta for Developers

Chaque propriété peut être remplacée en utilisant integrations.facebook.user_data.<property>

Informations minimales requises

Les événements ne peuvent être utilisés que s'il y a suffisamment d'informations pour correspondre à un utilisateur. Facebook attend au moins une user_data propriété, mais conseille fortement d'envoyer autant de propriétés que possible.

Voici nos conditions pour envoyer les événements :

• au moins 1 de ces champs : em, ph, external_id, fbp, fbc

• au moins 3 des autres champs

Note : external_id, fbp, fbc permettront d'apparier un événement avec d'autres événements. Mais pour apparier un utilisateur, un de ces événements doit contenir des informations supplémentaires (em et ph sont les mieux adaptés pour l'appariement)

Mapping : custom_data

Standard Parameters - Conversions API - Documentation - Meta for DevelopersMeta for Developers

Comportement par défaut

Facebook spécifie des règles pour standard properties. Le reste est complètement libre.

Par défaut, nous remplissons custom_data comme suit :

1. Nous copions tous les CommandersAct Event properties into custom_data (à l'exception de certains champs de contexte comme source_key)

2. Ensuite, nous mappont les propriétés standard selon le tableau ci-dessus (peut écraser 1. valeurs)

3. Enfin, nous écrasons avec integrations.facebook.custom_data.<property> si existe

Écraser custom_data

Le meilleur choix serait d'utiliser Properties Transformation pour modifier les propriétés de votre événement qui seront copiées dans custom_data.

Mais vous pouvez remplacer la valeur finale en utilisant integrations.facebook.custom_data.<property>.

Exemple :

cact('trigger', 'purchase', {
    "currency": "EUR",
    "value": 101,
    "integrations": {
        "facebook": {
            "custom_data": {
                "content_name": "some_custom_name",
                "your_field": "your_value"
            }
        }
    }
});

Mapping : app_data

App Data Parameters - Conversions API - Documentation - Meta for DevelopersMeta for Developers

integrations.facebook.* deprecation

Vérifier les résultats sur l'interface Facebook

Pour voir la qualité de matching sur l'interface Facebook, allez ici : Events manager > sélectionnez l'événement > View Details > Event Matching > Rating Background

Comment envoyer des conversions hors ligne

La façon recommandée est d'utiliser le HTTP Tracking API source pour envoyer vos événements hors ligne depuis vos serveurs (ou tout autre émetteur). Vous devez simplement envoyer un purchase event avec le type property equals to offline Plus de détails sur le mapping automatique ici : Mapping action_source