Facebook Conversions API

Aka Facebook CAPI

Facebook est un service en ligne de médias sociaux et de réseautage social appartenant à Meta. Cette destination vous permet d'envoyer directement tout type d'événement à 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 aux utilisateurs qui l'ont déjà acheté des campagnes liées à un produit spécifique, ou vous pouvez aussi envoyer des campagnes aux utilisateurs qui ont acheté un produit spécifique selon 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 devez disposer d'un compte Facebook Business Manager https://business.facebook.com/

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

Events Manager

Ici, vous devez créer un nouveau Web Pixel :

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 connecteur.

Où puis-je trouver le Pixel ID ?

Vous devez renseigner le pixel ID sur notre connecteur, il s'agit de l'ID du pixel que vous venez de créer aux étapes ci-dessus.

Vous pouvez trouver cet ID lorsque vous cliquez sur le nom du pixel et à droite des activités du graphique. Vous pouvez aussi le trouver dans l'onglet des paramètres.

Trouver le Pixel ID

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

Ensuite, vous avez besoin du Access Token

Où puis-je trouver le 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

Si vous configurez les deux, "Facebook Login For Business Authentication" sera priorisé.

Facebook Login For Business Authentication

C'est la méthode d'authentification recommandée.

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 à Meta Event Manager

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

1. Localisez votre (2) dataset existant et sélectionnez-le ou créez un nouveau dataset.

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

Si vous ne pouvez pas cliquer sur le lien "Generate access token", alors vous n'avez pas les droits admin.

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

Comment gérer les consentements ?

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

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

Pour les clients disposant de notre produit TRUST Commander :

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

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

Pour les clients ne disposant pas de 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 category ids consentis 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 category IDs de consentement de l'utilisateur. Ensuite, dans les paramètres du connecteur, utilisez le champ 'User Consent Category' pour saisir un category ID, 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 renseignez pas le champ ‘User Consent Category’ dans le connecteur.

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

L'utilisation simultanée du pixel et du serveur est recommandée par Facebook, car cela peut éviter de perdre des données.

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

event_id doit être identique

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 serveur dans integrations.facebook.event_id. Par conséquent, ces 2 valeurs doivent être identiques. Event_name doit également être identique.

Fbp parameter est automatiquement récupéré afin de conserver la même valeur entre le pixel et le serveur.

La déduplication fonctionne lorsque le même événement est envoyé d'abord depuis le navigateur puis 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 serveur :

integrations.facebook.event_id

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

Mappings vers 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"
      }
    }
  },
}

...en Facebook CAPI des événements comme :

{
  "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 mappings suivants sont entièrement automatisés et ne nécessitent par défaut aucune configuration supplémentaire. Vous pouvez toutefois personnaliser chacun d'eux comme suit.

Mapping : (root)

Developer Platformdevelopers.facebook.com

La plupart des propriétés peuvent être remappées à l'aide de notre fonctionnalité "Smart Mapping".

Propriétés Commanders Act	Propriétés Facebook
event_id [2][3]	event_id [1]
event_name	event_name [4]
context.event_timestamp	event_time [5]
context.page.url	event_source_url
context.page.referrer	referrer_url
Enable App tracking type	action_source [6]
opt_out [3]	opt_out [7]
data_processing_options [3]	data_processing_options [7]
data_processing_options_country [3]	data_processing_options_country [7]
data_processing_options_state [3]	data_processing_options_state [7]

1. Défini en fonction des propriétés disponibles, dans l'ordre indiqué à gauche. Par défaut, une valeur générée aléatoirement à partir du timestamp est utilisée. 2. Dans le chemin de base/root de votre événement. 3. Dans integrations.facebook de votre événement. 4. Voir Mapping: event_name pour plus de détails. 5. Si aucune valeur n'est fournie, le timestamp actuel est utilisé. 6. Voir Mapping: action_source pour plus de détails. 7. Voir plus de détails via ce LINK.

Mapping : event_name

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 Facebook Standard Event nom associé. Sinon, il sera envoyé sans aucune transformation

Commanders Act Events	Facebook Events
begin_checkout	InitiateCheckout
purchase	Purchase
add_to_cart	AddToCart
view_item	ViewContent
view_item_list	ViewContent
search	Search
add_payment_info	AddPaymentInfo
add_to_wishlist	AddToWishlist
generate_lead	Lead
page_view	PageView
sign_up	CompleteRegistration
contact	Contact
customize_product	CustomizeProduct
donate	Donate
find_location	FindLocation
schedule	Schedule
search	Search
start_trial	StartTrial
submit_application	SubmitApplication
subscribe	Subscribe

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 (HORS de la liste), elle enverra un custom_name à Facebook CAPI (aucune transformation)

Remarque : Vous pouvez personnaliser le event_name en utilisant Properties Transformations dans les paramètres de la destination.

Mapping : action_source

Developer Platformdevelopers.facebook.com

Par défaut, action_source sera défini sur 'website' (la plupart des événements concernent une activité en ligne). SI Enable App tracking 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",
  // ...
}

// Event envoyé à Facebook API :
{
  "event_name": "Purchase",
  "action_source": "physical_store"
  "custom_data": { /* */ }
  // ...
}

Si vous devez écraser cette valeur, vous pouvez actuellement utiliser Properties Transformation pour définir integrations.facebook.action_source.

Mapping : user_data

Developer Platformdevelopers.facebook.com

La plupart des propriétés peuvent être remappées à l'aide de notre fonctionnalité "Smart Mapping".

Propriétés Commanders Act	Propriétés Facebook
user.id (haché) context.device.sdk_id user.tcId , user.tcid ou user.tc_id	user_data.external_id [1]
user.email	user_data.em (email, haché)
user.phone	user_data.ph (téléphone, haché)
user.gender	user_data.ge (genre, haché)
user.birthdate	user_data.db (date de naissance, haché)
user.lastname	user_data.ln (nom de famille, haché)
user.firstname	user_data.fn (prénom, haché)
user.city	user_data.ct (ville, haché)
user.state	user_data.st (état/région, haché)
user.zipcode	user_data.zp (code postal, haché)
user.country	user_data.country (haché)
ip [3][4]	user_data.client_ip_address
user_agent [3][4]	user_data.client_user_agent
fbc [2] Le cookie "_fbc" [5]	user_data.fbc (Click ID)
fbp [2] Le cookie "_fbp" [5]	user_data.fbp (Browser ID)
advertising_id [3]	user_data.anon_id [6] user_data.madid [6]
partners.facebook.fb_login_id	user_data.fb_login_id [7]
user_data[Property Name] [8]	user_data[Property Name]

1. Chaîne séparée par des virgules : valeurs dans l'ordre fourni à gauche. 2. Dans integrations.facebook ou à la racine de vos événements, la première ayant priorité. 3. Dans context.device de votre événement. 4. Défini automatiquement s'il est généré par Commanders Act OneTag. 5. Créé automatiquement par le Facebook Pixel tag client-side. 6. Uniquement pour les événements d'application. 7. L'identifiant attribué par Meta lorsqu'une personne se connecte pour la première fois à une instance d'une application. Il est également appelé App-Scoped ID. 8. Dans integrations.facebook de votre événement.

Chaque propriété peut être remplacée à l'aide de 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 faire correspondre un utilisateur. Facebook attend au moins une user_data propriété, mais recommande fortement d'en envoyer le plus 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'associer l'événement à d'autres événements. Mais pour associer un utilisateur, l'un de ces événements doit contenir des informations supplémentaires (em et ph sont les plus adaptés à l'association)

Mapping : custom_data

Developer Platformdevelopers.facebook.com

La plupart des propriétés peuvent être remappées à l'aide de notre fonctionnalité "Smart Mapping". Les champs custom_data.contents et custom_data.content_ids sont mutuellement exclusifs, ce qui signifie qu'un seul d'entre eux peut être présent selon cette logique :

• Si toutes ces propriétés sont présentes et définies dans items : product.id , quantity , et product.price , alors custom_data.contents est défini avec toutes les informations produit.

• sinon, custom_data.content_ids est défini avec tous les product.id .

Propriétés Commanders Act	Propriétés Facebook
value	custom_data.value
currency items.0.currency	custom_data.currency
partners.facebook.net_revenue	custom_data.net_revenue
id	custom_data.order_id
search_term	custom_data.search_string
items.X.product.id	custom_data.contents.X.id [1]
items.X.quantity	custom_data.contents.X.quantity [1]
items.X.product.price	custom_data.contents.X.item_price [1]
items.0.product.name	custom_data.content_name
items.0.product.category_1	custom_data.content_category
items.X.product.id	custom_data.content_ids [2]
Valeur du type de contenu	custom_data.content_type [3]
status	custom_data.status
items.length	custom_data.num_items
Envoyez toutes les propriétés de votre event comme custom data	custom_data[Property Name] [4]
custom_data[Propery Name] [5]	custom_data[Property Name]

1. Mutuellement exclusif avec custom_data.content_ids et définie si toutes les propriétés suivantes sont présentes et valides : items.X.product.id , items.X.product.price , items.x.quantity . 2. Tableau contenant tous les identifiants produit. Mutuellement exclusif avec custom_data.contents. 3. Selon la valeur sélectionnée pour Valeur du type de contenu , qui se trouve sous Paramètres avancés , c’est soit product ou non défini. 4. Lorsque Envoyez toutes les propriétés de votre event comme custom data est coché, toutes les propriétés de votre event de type "string", "number" et "boolean" seront incluses dans custom_data avec le même nom de propriété. 5. Dans integrations.facebook dans votre event.

Comportement par défaut

Facebook définit des règles pour les propriétés standard. Le reste est totalement libre.

Par défaut, nous remplissons custom_data comme suit :

1. Nous copions toutes les CommandersAct Event propriétés dans custom_data (sauf certains champs de contexte comme source_key)

2. Ensuite, nous faisons correspondre 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 event 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

Developer Platformdevelopers.facebook.com

La plupart des propriétés peuvent être remappées à l'aide de notre fonctionnalité "Smart Mapping".

Propriétés Commanders Act	Propriétés Facebook
ad_tracking_enabled [1]	advertiser_tracking_enabled [*]
application_tracking_enabled [1]	application_tracking_enabled [*]
context.campaign.name	campaign_ids
install_referrer [2]	install_referrer
installer_package [2]	installer_package
url_schemes [2]	url_schemes
windows_attribution_id [2]	windows_attribution_id
type [1]	extinfo[0] [3]
app.namespace [1]	extinfo[1]
app.build [1]	extinfo[2]
app.version [1]	extinfo[3]
os.version [1]	extinfo[4]
model [1]	extinfo[5]
language [1]	extinfo[6]
[Aucun champ par défaut] [4]	extinfo[7]
network.carrier [1]	extinfo[8]
screen.width [1]	extinfo[9]
screen.height [1]	extinfo[10]
screen.density [1]	extinfo[11]
[Aucun champ par défaut] [5]	extinfo[12]
[Aucun champ par défaut] [6]	extinfo[13]
[Aucun champ par défaut] [7]	extinfo[14]
timezone [1]	extinfo[15]

* Propriété obligatoire. 1. Dans context.device de votre événement. 2. Dans integrations.facebook ou à la racine de vos événements, la première ayant priorité. 3. Lorsque context.device.type est défini avec Android ou iOS (sans tenir compte de la casse), ceci est défini avec a2 ou i2 respectivement. 4. Peut être défini dans Smart Mapping → App Data → Fuseau horaire abrégé de l'appareil . 5. Peut être défini dans Smart Mapping → App Data → Cœurs CPU . 6. Peut être défini dans Smart Mapping → App Data → Taille du stockage externe . 7. Peut être défini dans Smart Mapping → App Data → Taille du stockage disponible .

integrations.facebook.* dépréciation

integrations.facebook.* l’utilisation sera dépréciée. La fonctionnalité fonctionne toujours, mais il est recommandé d’utiliser à la place les paramètres de destination pour des raisons de maintenance et de fiabilité.

Vérifier les résultats dans l’interface Facebook

Pour consulter la qualité de correspondance dans l’interface Facebook, allez ici : Events manager > sélectionnez l’event > View Details > Event Matching > Rating Background

Comment envoyer des conversions hors ligne

La méthode recommandée consiste à utiliser la HTTP Tracking API source pour envoyer vos events hors ligne depuis vos serveurs (ou tout autre émetteur). Vous devez simplement envoyer un event purchase avec la type propriété égale à offline Plus de détails sur le mapping automatique ici : Mapping action_source