API Conversions pour le gestionnaire de balises Google (GTM) côté serveur

L’API Conversions a été conçue pour établir un lien direct entre vos données marketing et les systèmes, ce qui permet d’optimiser le ciblage publicitaire, de réduire le coût par action et de mesurer les résultats sur l’ensemble des technologies Meta. Vous pouvez configurer un serveur que vous paramétrez sur Google Cloud Platform (GCP) ou sur un autre fournisseur dans le cloud pour envoyer des données clés d’évènements Web et hors ligne via l’API Conversions. Grâce à cette configuration, après avoir paramétré le tag Web Google Analytics 4 (GA4), vous pouvez envoyer ces données à votre propre serveur hébergé sur Google Cloud Platform (GCP) et à Meta grâce à l’API Conversions.

Le tag de l’API Conversions est écrit et géré par Meta selon le modèle de tag personnalisé de Google. Contactez Google pour toute question sur la configuration des produits Google ou pour obtenir la documentation pour les développeur·ses de Google.

Ce document présente les éléments suivants :

• Les conditions requises, y compris comment créer un conteneur de serveur
• Comment configurer le conteneur pour permettre l’implémentation à l’aide du tag Web GA4
• Comment envoyer les données de votre site Web à votre serveur GCP
• Comment partager ces données avec Meta via l’API Conversions
• Questions/réponses

Conditions requises

Avant cette intégration, nous vous recommandons les étapes suivantes :

1. Se familiariser avec l’intégration de l’API Conversions et les recommandations de configuration
2. Se familiariser avec le balisage côté serveur et le modèle de tag personnalisé.

Si votre système utilise une version antérieure à GA4, vous devrez procéder à la mise à niveau de la configuration actuelle de votre gestionnaire de balises de manière à pouvoir utiliser GA4 avant d’effectuer cette intégration.

Intégration

Créer un conteneur de serveur GTM

Vous devrez configurer un conteneur de serveur et un conteneur Web :

• Conteneur Web : si vous utilisez GTM pour la première fois, commencez par installer un conteneur Web sur votre compte. Pour en savoir plus, consultez cette page.
• Conteneur de serveur : vous devrez créer un conteneur de serveur sur votre portail GTM pour configurer une URL de serveur de tags. En savoir plus sur cette étape.

Pour configurer un conteneur de serveur, vous devez paramétrer un serveur de tags. Vous pouvez réaliser le déploiement GCP par défaut lorsque vous configurez le conteneur de serveur. Reportez-vous aux conseils suivants. Pour tout autre fournisseur dans le cloud (comme AWS ou Microsoft Azure), consultez le guide de configuration manuelle d’un serveur.

Configurer les conteneurs de serveur et Web

1. Sur votre conteneur Web, créez les artefacts suivants :
   • Configuration GA4 pour paramétrer votre URL de serveur de tags.
   • Évènement GA4 pour configurer le schéma des évènements à transmettre au serveur.
2. Sur votre conteneur de serveur, créez les artefacts suivants :
   • Client GA4, un écouteur pour l’évènement qui déclenche l’évènement sur Meta.
   • Tag API Conversions Meta, un tag côté serveur qui convertit le modèle d’évènement standard du client GA4 en schéma d’évènement API Conversions et l’envoie à graph.facebook.com.

Étape 1 : Configuration de GA4 – Configurer l’URL de serveur de tags

Configurez votre conteneur Web pour envoyer les données de votre site Web au serveur de tags créé. En savoir plus sur la configuration du tag Google Analytics : configuration GA4.

• Si vous sélectionnez Send to server container (Envoyer au conteneur de serveur), définissez l’URL de votre conteneur de serveur (Server Container URL) comme URL du serveur de tags.
• Si vous ne sélectionnez pas Send to server container (Envoyer au conteneur de serveur), sous Fields to Set (Champs à définir), cliquez sur Add Row (Ajouter une ligne) et définissez les éléments suivants :

  • Nom du champ : transport_url
  • Valeur du champ : URL de votre serveur de tags

Vous pouvez configurer d’autres champs pour n’importe quel autre paramètre que vous souhaitez envoyer pour tous les évènements.

• Définissez la valeur du marqueur first_party_collection sur « true ». Vous devez effectuer cette opération pour pouvoir transmettre les paramètres « user_data » au GTM côté serveur. Sous Fields to Set (Champs à définir), cliquez sur Add Row (Ajouter une ligne) et définissez les éléments suivants :

  • Nom du champ : first_party_collection
  • Valeur du champ : true

Utiliser un tag de configuration GA4 existante

Si vous disposez déjà d’une configuration GA4, vous pouvez la modifier ou y ajouter un tag de configuration pour le GTM côté serveur.

S’il s’agit de votre première configuration du GTM côté serveur, l’ajout de l’URL du conteneur de serveur déclenchera l’envoi de tout votre trafic vers le conteneur de serveur. Si vous souhaitez continuer à envoyer vos données à GA4, vous devez ajouter le tag du GA4 côté serveur à votre conteneur de serveur et vérifier qu’il se déclenche pour tous les évènements. Vous pouvez être amené·e à créer d’autres tags d’évènements GA4 ou à modifier des tags existants afin qu’ils correspondent parfaitement aux évènements du pixel Meta.

Envoyer l’ID de navigateur et l’ID de clic Meta

Si vous avez configuré un domaine personnalité et si votre serveur de tags GTM est hébergé sur un domaine interne, vous recevez automatiquement les ID de navigateur et de clic Meta.

Si vous utilisez le domaine fourni par défaut ou ne recevez pas les ID de navigateur et de clic dans Gestionnaire d’évènements, suivez les étapes ci-dessous pour les configurer :

• Accédez à la section relative aux variables et créez une variable personnalisée pour les ID de navigateur et de clic. Utilisez le type de variable Cookie interne.

  • Pour l’ID de navigateur Meta, nommez le cookie _fbp.
  • Pour l’ID de clic Meta, nommez le cookie _fbc.
• Enregistrez ces variables.
• Dans votre tag de configuration GA4, sous Fields to Set (Champs à définir), cliquez sur Add Row (Ajouter une ligne) et définissez les éléments suivants :

  • Nom du champ : x-fb-ck-fbp
  • Valeur du champ : la variable de votre ID de navigateur Meta
• Ajoutez une ligne pour l’ID de clic :
• Nom du champ : x-fb-ck-fbc
• Valeur du champ : la variable de votre ID de clic Meta

Créez une variable de couche de données pour chacun des paramètres « user_data » du schéma d’évènement commun de GTM. En savoir plus sur la configuration des variables de couche de données. Par exemple, pour transmettre une adresse e-mail au GTM côté serveur, créez une variable (par exemple, user_data_email_address) pouvant être mappée au nom de la variable de la couche de données eventModel.user_data.email_address.

Si vous n’utilisez pas de couche de données, configurez les variables à utiliser en remplacement pour chaque paramètre selon les indications ci-dessous. Voici une liste de tous les mappages pour les paramètres « user_data » de Meta et GTM, ainsi que leur priorité générale pour améliorer la qualité de correspondance des évènements. Pour optimiser votre utilisation des publicités Meta, nous vous conseillons de suivre ces recommandations relatives à l’API Conversions lorsque vous configurez une intégration. Si vous avez déjà configuré l’API Conversions, nous conseillons de suivre les recommandations ci-après pour améliorer votre configuration existante. Les recommandations relatives à l’API Conversions permettent d’améliorer vos performances publicitaires en réduisant votre coût par action.

Étape 2 : Évènement GA4 – Configurer le schéma des évènements à transmettre au serveur

• Configurez votre conteneur Web pour envoyer les données de votre site Web au serveur de tags créé afin d’ajouter Google Analytics. En savoir plus sur la configuration du tag Google Analytics : configuration GA4.

• Ajoutez le tag Google Analytics : évènement GA4 à votre espace de travail à partir de la galerie de modèles :

  • Définissez un nom d’évènement pour le tag. Vous pouvez le définir comme une valeur statique ou le configurer pour qu’il soit lu à partir d’une variable. Pour certains évènements standard, nous trouvons automatiquement l’équivalent Meta des évènements Google Analytics standard. Pour ces évènements, vous pouvez donc utiliser indifféremment le nom Google Analytics ou le nom Meta. Pour tous les autres évènements standard, utilisez le nom Meta. Pour les évènements personnalisés, utilisez le nom de l’évènement personnalisé. En savoir plus.

• Dans la section des paramètres d’évènement :

  • Si vous utilisez le pixel Meta, ajoutez le paramètre ID de l’évènement. Utilisez « event_id » comme nom de paramètre et la variable créée pour l’ID d’évènement comme valeur. Consultez la section Déduplication pour savoir comment créer la variable de l’ID d’évènement et modifier le pixel Meta.
  • Mappez tous les paramètres que vous souhaitez configurer. Le nom de la variable doit être lu à partir de l’évènement à l’aide d’un schéma d’évènement courant. Par exemple, pour configurer l’e-mail comme paramètre d’évènement, vous devez le définir comme nom du paramètre : « user_data.email_address » et configurer la valeur comme le nom de la variable qui lit « email_address » (défini précédemment dans la Section 1).
  • Pour obtenir la liste complète, consultez la section Paramètres de données personnalisés ci-dessous.

Étape 3 : Créer un écouteur pour l’évènement qui déclenche l’évènement sur Meta

Chaque conteneur GTM côté serveur est livré avec un client GA4 par défaut pour auditer les évènements configurés à partir de son tag Web GA4. Le client GA4 audite la route /g/collect sur votre URL de serveur de tags et envoie eventModel au tag en aval. Si le client GA4 par défaut est déjà installé dans le conteneur de votre serveur dans la section Clients, passez à l’étape 4.

Étape 4 : Créer un tag d’API Conversions Meta, un tag côté serveur qui convertit le modèle d’évènement standard du client GA4 en schéma d’évènement API Conversions et l’envoie à graph.facebook.com

Pour envoyer l’évènement à l’API Conversions, vous devez installer le tag d’API Conversions Meta depuis la galerie de modèles. Le modèle de tag s’appelle Conversions API Tag, créé par facebookincubator. Ce tag peut être configuré pour être déclenché sur des évènements reçus par le client GA4 (à l’étape précédente) et envoyé à l’API Conversions. Pour installer le tag d’API Conversions Meta, vous devrez disposer d’un ID de pixel, d’un token d’accès et spécifier la source d’action « site Web ». En utilisant l’API Conversions, vous certifiez que le paramètre action_source est, à votre connaissance, exact.

Tester l’intégration

Nous vous recommandons d’utiliser le mode d’aperçu de Google Tag Manager pour tester les intégrations avant de publier les modifications. Les conteneurs serveur et Web disposent de modes d’aperçu qui peuvent être exécutés simultanément.

Vous pouvez vérifier vos évènements de serveur sont bien réceptionnés à l’aide de la fonctionnalité de test d’évènements du Gestionnaire d’évènements. Cet outil se trouve sous : Gestionnaire d’évènements > Sources de données > Votre Pixel > Tester les évènements.

L’outil de test d’évènements génère un ID de test. Envoyez cet ID en tant que paramètre test_event_code dans votre tag d’API Conversions pour commencer à visualiser l’activité des évènements dans la fenêtre Tester les évènements. Veillez à le supprimer avant de publier les modifications.

L’outil de test des évènements vous permet de vérifier la réception et la déduplication des évènements. Si les évènements n’apparaissent pas après une ou deux minutes, vérifiez dans le débogueur du GTM côté serveur que la requête a été transmise :

1. Dans le débogueur côté serveur, sélectionnez l’évènement que vous souhaitez vérifier dans le menu de gauche.
2. Vérifiez que votre tag est affiché dans la section Tags Fired (Tags déclenchés). Si c’est le cas, vous verrez le message « Conversions API Tag - Succeeded » (Tag de l’API Conversions – Réussite) ou « Conversions API Tag - Failed » (Tag de l’API Conversions – Échec).
   • Tag Not Fired (Tag non déclenché) : vérifiez le déclencheur de votre tag de l’API Conversions et le déclencheur d’évènement GA4 associé dans le conteneur Web. Dans le débogueur Web, vérifiez que l’évènement GA4 a été déclenché.
   • Tag Fired: Succeeded (Tag déclenché : réussite) : cliquez sur le tag et vérifiez que le code de test de l’évènement est correct. Modifiez le code si besoin et redémarrez le mode d’aperçu.
   • Tag Fired: Failed (Tag déclenché : Échec) : ouvrez l’onglet Request (Requête) et cliquez sur la requête sortante envoyée à https://graph.facebook.com. Examinez le corps de la réponse en bas des détails de la requête pour trouver l’erreur et modifiez votre intégration en conséquence. N’oubliez pas de redémarrer le mode d’aperçu après vos modifications.

Lorsque les évènements s’affichent correctement, vérifiez que l’ID de chaque évènement est envoyé et que les clés de correspondance et paramètres de données personnalisés associés s’affichent eux aussi correctement. L’outil de test des évènements vous indique si les évènements ont été dédupliqués. En cas de divergence entre les ID d’évènements, vérifiez que le déclenchement des tags GA4 et Pixel Meta s’effectue à partir du même déclencheur et vérifiez l’implémentation des variables des ID d’évènements.

Déduplication

Nous vous recommandons d’utiliser une configuration d’évènements redondante et de partager les mêmes évènements à partir de l’API Conversions et de votre pixel Meta. Assurez-vous que les deux évènements utilisent le même event_name et d’inclure event_id ou une combinaison de external_id et fbp.

Cela permettra à Meta de dédupliquer les évènements et de réduire les doubles signalements d’évènements identiques. En savoir plus sur la déduplication, les cas d’utilisation et sa configuration. external_id et fbp sont des solutions alternatives pour la déduplication et permettent aussi d’améliorer la qualité de la configuration. Nous recommandons d’inclure ces deux paramètres chaque fois que possible.

GTM offre plusieurs façons de configurer un paramètre avec la même valeur sur un tag de navigateur et un tag de serveur. L’une d’entre elles consiste à utiliser le même évènement GA4 pour déclencher l’évènement serveur et le tag de votre pixel Meta. Pour cela :

• Utilisez le même déclencheur pour le tag d’évènement GA4 et le tag HTML personnalisé de votre pixel Meta. Par exemple, vous pouvez définir une condition de déclenchement en fonction de l’URL de la page de confirmation de la commande.
• Utilisez le même event_id dans les deux tags :

  1. Définir un ID unique à partir du client : définissez un paramètre personnalisé (x-fb-event_id) à partir de l’évènement gtag. Générez un ID unique (par évènement) sur le site Web à l’aide d’une méthode javascript (ou de la variable Javascript personnalisée Gestionnaire d’évènements Google) et définissez la valeur dans l’évènement comme suit :

  gtag('event', 'purchase', {
   'x-fb-event_id': generateEventId(),
  ...:...
  
   });

  Vous pouvez créer une variable qui pointe vers la variable Javascript personnalisée illustrée ci-dessous. Dès qu’il est fait référence à la variable, le JavaScript ci-dessous est chargé dans la ligne :

  function() {
  var gtmData = window.google_tag_manager[{{Container ID}}].dataLayer.get('gtm');
  return gtmData.start + '.' + gtmData.uniqueEventId;
  }

  2. Créer et renseigner une variable de couche de données : vous pouvez créer votre propre variable sur le conteneur Web pour lire la valeur de event_id. Pour cela, créez une nouvelle variable de couche de données, par exemple, « FBEventIdVar », avec le nom eventModel.event_id.
  3. Une fois la variable définie, vous disposez de la variable à associer à l’évènement web dans votre tag HTML personnalisé, et à l’évènement serveur en tant que paramètre d’évènement GA4 supplémentaire.
  4. Sur le Web, vous pouvez configurer votre tag Meta sur les conteneurs Web du gestionnaire de balises Google pour lire le event_id d’une variable.

  fbq('track', Purchase, {..}, {eventID: FBEventIDVar });

  Configurez l’évènement GA4 pour envoyer un paramètre supplémentaire appelé event_id, défini sur la variable FBEventIdVar.

Paramètres de données personnalisés

Pour envoyer des données personnalisées, utilisez les mappages ci-dessous dans vos tags d’évènements GA4 :

Envoyer les données de votre site Web à votre serveur GCP

Après avoir configuré vos conteneurs web et de serveur, vous pouvez envoyer un exemple d’évènement depuis votre site web pour vérifier l’évènement serveur. Voici un exemple d’évènement disposant des paramètres configurés :

 gtag('event', 'purchase', 
  {
    'event_id': generateEventId(),
    'transaction_id': 't_12345',
    'currency': 'USD',
    'value': 1.23,
    user_data: {
      email_address: '<HASHED_DATA>',
      phone_number: '<HASHED_DATA>',
      address: {
        first_name: '<HASHED_DATA>',
        last_name: '<HASHED_DATA>',
        city: '<HASHED DATA>',
        region: '<HASHED_DATA>',
        postal_code: '<HASHED_DATA>',
        country: '<HASHED_DATA>'     
      },    
    },
    items: [
      {
        item_id: '1',
        item_name: 'foo',
        quantity: 5,
        price: 123.45,
        item_category: 'bar',
        item_brand: 'baz'     
      }
    ], 
  });      
     

Une fois que l’évènement est déclenché, vous devriez voir une demande envoyée, par exemple, au lien : www.analytics.example.com/g/collect, avec les paramètres configurés. Vous pouvez ajouter un code d’évènement test au tag de l’API Conversions Meta pour vérifier les évènements envoyés à l’API Conversions. Le code de test des évènements doit être utilisé uniquement à des fins de test. Vous devez le supprimer lorsque vous envoyez votre charge utile de production.

Lorsque vos modifications ont été publiées, utilisez la page Vérifier votre configuration pour vous assurer que vos évènements sont bien envoyés. Veillez notamment à ce que la qualité des correspondances est conforme à nos recommandations.

Questions/réponses

Est-il prévu d’ajouter la fonctionnalité d’envoi de paramètres personnalisés ? Si oui, quand sera-t-elle disponible ?
R : nous avons ajouté la correspondance pour la plupart des paramètres personnalisés standard de l’API Conversions pris en charge dans le schéma de GTM. Nous fournissons aussi une correspondance personnalisée. Pour en savoir plus, consultez cette page.

Un seul serveur ou cluster peut-il exécuter plusieurs conteneurs ?
R : non, seule la correspondance 1:1 est actuellement prise en charge par GTM. Lisez les recommandations sur l’organisation de vos conteneurs.

Le GTM côté serveur nécessite-t-il un tag basé sur navigateur pour envoyer des évènements ?
R : oui

Est-il possible de séparer GA4 et l’intégration côté serveur ?
R : pour que GA4 et l’intégration GTM côté serveur restent séparés, vous pouvez créer un nouvel ID de mesure dans Google Analytics. Créez un tag de configuration GA4 distinct pour le GTM côté serveur avec cet ID de mesure, en suivant les étapes ci-dessus. Dans cet exemple, votre tag de configuration GA4 continuera d’envoyer le trafic de GA via le conteneur web, tandis que le nouveau tag de configuration enverra les données au conteneur de serveur. Créez d’autres tags d’évènements GA4 en suivant l’étape 2 pour envoyer les évènements côté serveur avec le nouveau tag de configuration.

L’intégration de GTM dans l’API Conversions est-elle compatible avec des solutions d’hébergement cloud autres que GCP ?
R : l’intégration de GTM dans l’API Conversions est compatible avec GCP et toute autre plateforme de votre choix. Plus d’informations sur le provisionnement manuel.

En savoir plus

• API Conversions
• Déduplication des évènements du pixel Meta et de l’API Conversions