API Conversions

Bibliothèque de l’éditeur de paramètres

Meta propose une gamme de bibliothèques de SDK côté client (JavaScript) et côté serveur (PHP, Java, Python, NodeJS, Ruby). Ces bibliothèques SDK sont destinées à aider les développeur·ses à améliorer la qualité des paramètres des évènements de l’API Conversions (par exemple, fbc, fbp, client_ip_address et d’autres paramètres d’informations clientèle comme em et ph), et à permettre aux annonceurs de se conformer aux recommandations de Meta concernant la génération de ces paramètres.

Ce document comprend une présentation des deux bibliothèques, des conseils sur la bibliothèque à utiliser et des exemples de cas d’utilisation.

Présentation des bibliothèques

Côté client : la bibliothèque et les évènements sont disponibles dans le front-end côté navigateur. Les bibliothèques sont implémentées en JavaScript. Les développeur·ses peuvent les intégrer directement sur leur page Web.

Côté serveur : les bibliothèques et les évènements sont disponibles dans le back-end côté serveur. Selon le langage utilisé par le back-end, Meta fournit des bibliothèques en différents langages (PHP, Java, Python, NodeJS et Ruby).

Choix de la bibliothèque

Toutes les bibliothèques peuvent fonctionner indépendamment. Pour optimiser votre potentiel ou celui de votre clientèle, veuillez consulter les recommandations suivantes.

ParamBuilder respecte les recommandations de la documentation pour les développeurs de Meta. Elle est implémentée côté client (JavaScript) et côté serveur (PHP, Java, Python, NodeJS, Ruby).

Exemples de cas d’utilisation pour référence

Les cas d’utilisation suivants peuvent être pris en compte lors de l’élaboration de la solution.

Recommandé : éditeur de paramètres côté serveur + éditeur de paramètres côté client

L’association de l’éditeur de paramètres côté serveur et de l’éditeur de paramètres côté client peut vous aider à optimiser vos chances d’obtenir une couverture fbc et IPv6 élevée.

Pour ce faire, vous devez intégrer deux bibliothèques : l’éditeur de paramètres côté serveur et l’éditeur de paramètres côté client.




Exemple de flux de travail

  • L’application client de l’annonceur charge l’éditeur de paramètres côté client et appelle le processus API processAndCollectAllParams fourni avec un pointeur de fonction getIpFn.
  • Le pointeur de fonction getIpFn fourni sera invoqué et récupérera l’IPv6 à partir d’un point de terminaison configuré par l’annonceur en fonction de l’implémentation getIpFn réelle.
  • Le point de terminaison configuré par l’annonceur renverra l’IPv6 qui sera transmis à l’éditeur de paramètres côté client à partir de la valeur retournée par getIpFn. L’IPv6 récupéré sera stocké dans le cookie avec la clé _fbi pour une récupération ultérieure.
  • Côté client, lancez vos communications habituelles avec le serveur back-end à l’aide de l’API Fetch (ou d’une autre méthode de communication entre le front-end et le back-end) avec les cookies internes.
  • Côté serveur, intégrez la bibliothèque côté serveur en fonction du langage choisi dans le point de terminaison du destinataire (par exemple, ExampleController) et appelez l’API processRequest fournie pour traiter la requête.
  • L’API processRequest renvoie une liste des cookies recommandés à mettre à jour côté client.
  • Définissez les cookies recommandés dans les en-têtes de réponse pour demander au navigateur client de les stocker.
  • Invoquez diverses API fournies comme getFbc(), getFbp(), getClientIpAddress() et getNormalizedAndHashedPII().
  • Le SDK renvoie diverses valeurs comme fbc, fbp, client_ip_address, email et phone number.
  • Renvoyez ces valeurs récupérées à Meta via l’API Conversions.
// Example Controller which processes all requests to example.com
// Start process
ParamBuilder paramBuilder = new ParamBuilder(Arrays.asList('example.com', 'yourDomain.com'));
// Input the request's full URL, such as: example.com?fbclid=xxxxx
// Process and get recommended updated cookie
List<CookieSetting> updatedCookieList =
        paramBuilder.processRequest(
            request.getHeader("host"),  // example.com
            request.getParameterMap(), // {'fbclid':['xxxxx']}
            cookieMap, 
            request.getHeader("referer"),
request.getHeader("X-Forwarded-For"),
request.getRemoteAddr(),
); // optional: referer full url


// Save cookie from server side
for (CookieSetting updatedCookie : updatedCookieList) {
      Cookie cookie = new Cookie(updatedCookie.getName(), updatedCookie.getValue());
      cookie.setMaxAge(updatedCookie.getMaxAge());
      cookie.setDomain(updatedCookie.getDomain());
      response.addCookie(cookie);
 }

// Get fbc, fbp, client_ip_address
String fbc = paramBuilder.getFbc();
String fbp = paramBuilder.getFbp();
String client_ip_address = paramBuilder.getClientIpAddress();

// Get Normalized and Hashed PII like email and phone number
String normalizedAndHashedEmail = paramBuilder.getNormalizedAndHashedPII(‘John_Smith@gmail.com’,’email’);
String normalizedAndHashedPhone = paramBuilder.getNormalizedAndHashedPII(‘(650)555-1212’,’phone’);

// Call CAPI endpoint
.....
.setFbc(fbc)
.setFbp(fbp)
.setClientIpAddress(client_ip_address)
.setEmail(normalizedAndHashedEmail)
.setPhone(normalizedAndHashedPhone)
....

ParamBuilder côté serveur uniquement

Consultez le guide d’intégration de l’éditeur de paramètres côté serveur ou les fichiers README en lien avec celui-ci pour obtenir des exemples détaillés.

Exemple de flux de travail

  • Dans le point de terminaison du serveur, importez la bibliothèque ParamBuilder en fonction du langage et du cadre pertinents.
  • Appelez ParamBuilder.processRequest pour obtenir une liste des cookies mis à jour recommandés.
  • Définissez les cookies sur votre réponse.
  • Définissez fbc, fbp, client_ip_address et d’autres PII tels que l’adresse e-mail et le numéro de téléphone dans l’appel de l’API Conversions à l’aide de paramBuilder.getFbc(), paramBuilder.getFbp(), paramBuilder.getClientIpAddress() et paramBuilder.getNormalizedAndHashedPII() respectivement

ParamBuilder côté client uniquement

Consultez le guide d’intégration de l’éditeur de paramètres côté client ou les fichiers README en lien avec celui-ci pour obtenir des exemples détaillés.

Exemple de flux de travail

  • Lors du chargement de la page de destination, appelez clientParamBuilder.processAndCollectAllParams(url, getIpFnl).
  • La requête est alors envoyée côté serveur. Le serveur peut ensuite lire fbc, fbp et client_ip_address à partir du cookie en utilisant les clés _fbc, _fbp et _fbi respectivement.
    • Remarque : si l’URL de destination ne contient pas fbclid, fbc peut être manquant. C’est un comportement normal.

Liens utiles

Lien principal vers Github

Veuillez vous assurer d’utiliser la dernière version.

Recommandations

  • Assurez-vous d’enregistrer les cookies _fbp et _fbc le plus tôt possible dans le parcours clientèle sur votre page Web. Dans l’idéal, récupérez les cookies _fbp et _fbc lors du chargement de votre page de destination. Il n’est pas recommandé de les récupérer uniquement lors d’évènements de bas de funnel ou lorsque certains évènements sont déclenchés.
  • Ne remplacez pas et n’ajustez pas le cookie _fbc ou _fbp. _fbc est sensible à la casse, ne normalisez pas et ne formatez pas _fbc en minuscules.
  • Assurez-vous que les bibliothèques sont appliquées à toutes les interfaces, telles que les appareils mobiles, les ordinateurs de bureau, les navigateurs, et aux domaines que vous souhaitez suivre.
  • La bibliothèque côté serveur est destinée au back-end et la bibliothèque côté client est destinée au navigateur côté front-end. Les développeur·ses peuvent intégrer la bibliothèque côté client directement dans leur page Web, tandis que les bibliothèques côté serveur sont appelées dans le back-end côté serveur. Notez que la bibliothèque côté client est uniquement disponible en JavaScript, tandis que la bibliothèque côté serveur prend en charge différents langages (PHP, Java, Python, NodeJS et Ruby).
  • Lorsque vous implémentez la fonctionnalité getIpFn, nous vous recommandons de récupérer d’abord l’adresse IPv6, puis de revenir à l’adresse IPv4 si la récupération de l’adresse IPv6 n’est pas disponible côté client de l’utilisateur·ice.
  • Nous vous recommandons d’intégrer à la fois l’éditeur de paramètres côté client et l’éditeur de paramètres côté serveur pour optimiser les performances. Vous pouvez utiliser l’éditeur de paramètres côté client pour récupérer client_ip_address et l’enregistrer dans un cookie. Vous pourrez ensuite utiliser l’éditeur de paramètres côté serveur pour obtenir les meilleures valeurs client_ip_address disponibles à partir des cookies et des requêtes à envoyer à Meta à l’aide de l’API Conversions.
  • Nous vous recommandons d’appliquer la normalisation et le hachage aux paramètres d’informations client une seule fois, soit côté client, soit côté serveur, avant de les envoyer à Meta via l’API Conversions.
  • Les valeurs de tous les champs de paramètres d’informations client renvoyées par l’éditeur de paramètres sont sensibles à la casse. Vous pouvez renvoyer ces valeurs telles quelles à Meta via l’API Conversions sans normalisation (par exemple, en minuscules), car cette opération a été automatiquement effectuée par le SDK ParamBuilder dans le processus.

Voir aussi