3 : Mise en œuvre par le ou la développeur·se

Cette page traite de l’intégration manuelle, qui comprend les étapes suivantes :

Créer une charge utile pour l’intégration de l’outil de CRM
Générer un token d’accès et préparer un appel d’API
Envoyer une charge utile de test
Envoyer les données de production

Cette section s’applique uniquement si vous décidez de réaliser cette intégration manuellement à l’aide de ressources de développement. Si vous préférez réaliser l’intégration en utilisant un partenaire, suivez les instructions d’intégration du partenaire. Une fois l’intégration du partenaire terminée, vous pourrez passer à la section 4 : Vérification de vos données de ce guide.

Vous aurez besoin d’un accès admin au Business Manager pour réaliser cette intégration. Si vous avez reçu un message d’invitation en tant que développeur·se, vous trouverez les informations d’accès dans cet e-mail. Sinon, demandez un accès à un admin du Business Manager.

Étape 1 : Créer une charge utile

Cette étape présente les spécifications de charge utile pour l’intégration des prospects de conversion et fournit des recommandations sur la façon de les envoyer à partir de votre serveur.

Commencez par ouvrir le guide d’intégration CRM depuis l’onglet Paramètres du pixel de votre outil de CRM.

Consultez le guide de l’API Conversions pour les développeur·ses afin de comprendre comment fonctionne l’API Conversions.

Nous vous recommandons de créer votre charge utile à l’aide de l’outil Assistant Charge utile. Cet outil va mettre en forme la charge utile et vérifier les éventuelles erreurs. Après avoir résolu toutes les erreurs de charge utile, cliquez sur le bouton Obtenir le code dans l’outil Assistant Charge utile pour générer un modèle de code pour votre langage de programmation.

Les paramètres obligatoires sont indiqués ci-dessous. Vous trouverez une description complète de chaque paramètre dans le guide Intégration des prospects de conversion - Spécification de charge utile. Cette spécification de charge utile ne vaut que pour les évènements d’optimisation des prospects de conversion. Cela signifie que les évènements ne doivent concerner que les publicités à formulaire Meta et être associés à un ID de prospect valide. Évitez d’utiliser cette spécification de charge utile pour d’autres types d’évènements, tels que les prospects de site Web.

Paramètres

Nom	Description
`event_name` chaîne	Champ de texte libre permettant de saisir les étapes de prospect que vous utilisez dans votre outil de CRM. Le paramètre `event_name` doit indiquer la progression d’un prospect dans le funnel de ventes dans votre outil de CRM. Assurez-vous d’envoyer chaque étape au fur et à mesure, y compris l’étape Prospect pré-qualifié.
`event_time` entier	Horodatage Unix exprimé en secondes indiquant l’heure à laquelle votre outil de CRM a actualisé l’évènement de mise à jour de l’étape du prospect. Le prospect doit déjà avoir été généré, sans quoi l’évènement pourra être supprimé.
`action_source` chaîne	Valeur :`system_generated` En utilisant l’API Conversions, vous certifiez que le paramètre `action_source` est, à votre connaissance, exact.
`lead_id` entier	`leadgen_id` à 15 ou 16 chiffres provenant des prospects téléchargés.
`lead_event_source` chaîne	Nom de l’outil de CRM d’où proviennent les évènements.
`event_source` chaîne	Valeur :`crm`

Exemple
Voici à quoi pourrait ressembler la charge utile. Remarque : veillez à utiliser un lead_id valide, sinon votre évènement sera rejeté.

{
    "data": [
        {
            "event_name": "initial_lead",
            "event_time": 1629424350,
            "action_source": "system_generated",
            "user_data": {
                "lead_id": 525645896321548
            },
            "custom_data": {
                "event_source": "crm",
                "lead_event_source": "salesforce"
            }
        }
    ]
}

Si les évènements ne respectent pas la spécification de charge utile ou ne correspondent pas à une publicité à formulaire Meta, ils ne seront pas reconnus pour l’intégration et ne seront pas utilisés pour entraîner le modèle.
Par exemple, la charge utile Web peut être acceptée par l’API Conversions et s’afficher dans le Gestionnaire d’évènements. Pourtant, elle ne sera pas reconnue pour cette intégration. Veillez aussi à utiliser un lead_id valide, sinon l’évènement sera rejeté.
Seule la charge utile de prospects de conversion sera reconnue pour l’intégration et utilisée pour l’entraînement.

Étape 2 : Créer un token d’accès et un appel d’API

Une fois que les données à envoyer ont été configurées, l’étape suivante consiste à définir leur destination.

Vous allez donc générer un token d’accès pour votre pixel Meta, lequel permettra d’établir une connexion entre votre serveur et l’API Conversions.

Revenez au guide d’intégration CRM dans l’onglet Paramètres du pixel de votre outil de CRM.

Faites défiler la page vers le bas jusqu’à la section Créez un point de terminaison et cliquez sur le bouton Générer un token d’accès. Le token d’accès permettra d’exécuter l’appel d’API.
Vous pouvez générer un nouveau token d’accès en revenant au guide d’intégration ou, depuis l’onglet Paramètres du Gestionnaire d’évènements, en accédant à la section API Conversions et en cliquant sur le lien Générer un token d’accès.

La suite de la procédure varie selon que vous utilisez ou non le SDK de Meta. Nous recommandons d’utiliser le SDK Meta Business, car il fournit des messages d’erreur et de diagnostic plus précis. Vous aurez besoin de votre ID de pixel et du token d’accès pour exécuter l’appel d’API via le SDK Meta Business. Pour obtenir le token d’accès, cliquez sur Copier le token d’accès dans le guide d’intégration CRM et enregistrez-le. Vous trouverez des exemples d’appels d’API via le SDK dans le guide de l’API Conversions pour les développeur·ses ou au niveau de la fonctionnalité Obtenir le code dans l’outil Assistant Charge utile de Meta.

Le point de terminaison pour envoyer une requête POST à l’API Conversions sans le SDK doit se présenter comme suit. Vous pouvez récupérer l’intégralité du point de terminaison en cliquant sur Copier le point de terminaison dans le guide d’intégration CRM et en l’enregistrant.
```
https://graph.facebook.com/API_VERSION/PIXEL_ID/events?access_token=ACCESS_TOKEN
```
- API_VERSION : version actuelle de l’API Marketing.
- PIXEL_ID : l’ID de chaque pixel peut être obtenu à partir du Gestionnaire d’évènements.
- ACCESS_TOKEN : token d’accès généré ci-dessus.
Pour connaître les dates de publication et d’expiration de l’API Marketing, consultez la documentation sur les versions des API. Pensez à modifier la version de l’API Marketing ou du SDK Meta Business dans votre code avant qu’elle n’expire. L’utilisation d’une version obsolète dans le code pourrait entraîner des erreurs et vos évènements pourraient être supprimés.

Étape 3 : Tester la charge utile (facultatif)

Vous pouvez maintenant envoyer une charge utile de test à votre pixel avant d’ajouter le code sur votre serveur. Pour ce faire, vous utiliserez l’onglet Évènements de test du Gestionnaire d’évènements.

Dans la section Tester les évènements du serveur cliquez sur le lien Explorateur de l’API Graph. Ce lien unique permet de préremplir certaines informations à partir de votre pixel. (Vous pouvez également accéder directement à l’Explorateur de l’API Graph si vous le souhaitez.) Notez la valeur test_event_code, qui peut changer au fil du temps.

Procédez comme suit dans l’Explorateur de l’API Graph :
1. Assurez-vous d’être en mode POST.
2. Vérifiez votre version d’API et votre ID de pixel.
3. Basculez vers la vue JSON.
4. Saisissez votre charge utile. Vous pouvez la créer manuellement ou la générer à l’aide de l’outil Assistant Charge utile. Assurez-vous d’ajouter le test_event_code de l’étape précédente et un lead_id valide.
Saisissez le token d’accès de votre pixel et cliquez sur le bouton Envoyer.

Si la charge utile ne contient pas d’erreurs de syntaxe ou d’API, vous devriez recevoir un message de confirmation contenant un fbtrace_id.

L’évènement de test devrait s’afficher rapidement dans l’onglet Évènements de test du Gestionnaire d’évènements.

Étape 4 : Envoyer les données de production

Les données de production doivent respecter le même format que la charge utile générée à l’étape 3. En revanche, elles proviennent directement de votre serveur. Cette section fournit des règles générales étant donné que la procédure varie en fonction de l’intégration.

Envoyez le lead_id plutôt que le PII pour la mise en correspondance.

Assurez-vous d’envoyer chaque étape de prospect au fur et à mesure, y compris l’évènement Prospect pré-qualifié qui représente tous les prospects générés sur Meta et téléchargés dans votre outil de CRM. Vous trouverez ci-dessous un exemple de funnel. Les noms d’évènement et les étapes ne correspondront pas forcément à cet exemple, car ils sont définis par l’annonceur.

Si vos campagnes génèrent 100 prospects, 100 évènements de type « Prospect pré-qualifié » seront normalement importés afin de représenter la première étape. En envoyant la première étape du prospect, vous indiquez au système que le prospect a été reçu et traité. À mesure que les prospects avancent dans le funnel de ventes, 70 étapes « Prospect qualifié par le marketing », 30 étapes « Opportunité de vente » et 15 étapes « Conversion » devraient être importées.

Pour résumer, 215 évènements seront importés, alors que 100 prospects ont été générés à partir des campagnes.

Créez une fonction qui récupère les mises à jour à partir de la base de données ou de l’API de votre outil de CRM lorsque le statut du prospect change. Envoyez ensuite la charge utile à l’API Conversions de Meta à l’aide d’une fonction personnalisée ou du SDK Meta Business, selon votre configuration CRM et de base de données.

Les variables sont recommandées pour :
- lead_id
- event_name
- event_time
La charge utile suivante définit les valeurs des paramètres de manière explicite :
```
{
  "event_name": "initial_lead",
  "event_time": 1628294742,
  "user_data": {
    "lead_id": 1234567890123456
  },
  "action_source": "system_generated",
  "custom_data:" {
    "lead_event_source": "Salesforce",
    "event_source": "crm"
  }
}
```
Voici un exemple de charge utile qui transmet des valeurs à partir de votre base de données à l’aide de variables :
```
{
  "event_name": lead_stage // "initial_lead"
  "event_time": unix_time // 1628294742
  "user_data": {
    "lead_id": fb_lead_id // 1234567890123456
  },
  "action_source": "system_generated",
  "custom_data:" {
    "lead_event_source": "Salesforce",
    "event_source": "crm"
  }
}
```

Importez les données au moins une fois par jour. Idéalement, les appels vers votre outil de CRM devraient être réalisés en temps réel. Si ce n’est pas possible, vous pouvez intégrer les données par lot toutes les heures ou tous les jours.
Si vous choisissez la méthode par lot, assurez-vous de capturer l’historique des changements de statut du prospect plutôt qu’un instantané du prospect au moment de l’intégration par lot. Par exemple, si le statut d’un prospect change 3 fois entre les lots, 3 évènements devraient être importés, et pas uniquement le dernier évènement mis à jour.
Remarque : chaque lot peut inclure jusqu’à 1 000 évènements. En cas d’erreur au niveau d’un lot, le lot complet sera supprimé. C’est pourquoi il est VIVEMENT recommandé d’utiliser des petits lots et d’ajouter une logique pour réitérer les tentatives.

Facultatif. Nous recommandons de consigner les messages d’erreur provenant de l’appel de l’API Conversions et de créer des alertes si des problèmes se produisent. Nous conseillons également de gérer les exceptions pour ces erreurs.

Le remplissage des données peut remonter jusqu’à 7 jours, entre le moment où l’évènement se produit (event_time) et où il est importé (upload_time). Remplir certaines données permet d’accélérer le processus d’entraîner.
ATTENTION : n’essayez jamais de remplir plus de 7 jours de données en modifiant les valeurs event_time. Le modèle s’appuie en effet sur un horodatage précis pour l’optimisation. Toutes vos données remplies pourraient être supprimées.
Assurez-vous que les valeurs event_time sont postérieures à la date de génération des évènements, sinon ceux-ci pourraient être supprimés.

Vous devriez commencer à voir des évènements apparaître dans le Gestionnaire d’évènements pour votre pixel dans l’heure qui suit, si votre intégration est en train d’importer des évènements dans Meta. Pensez à utiliser un lead_id valide dans vos charges utiles pour que les évènements apparaissent. Ouvrez chaque évènement envoyé pour l’intégration CRM des prospects de conversion dans le Gestionnaire d’évènements et vérifiez que les paramètres personnalisés lead_event_source et event_source sont renseignés. Si l’évènement ne contient pas ces paramètres, il ne sera pas enregistré comme un évènement de prospect de conversion.
Le système vérifie la validité de vos évènements de prospect de conversion. Au bout d’une journée, une coche verte s’affiche à côté de l’étape d’intégration Envoyer un évènement CRM si un évènement valide est détecté.

< 2: Getting Started With the CRM Integration

4 : Vérification de vos données >