Suivi des conversions OpenAI CAPI avec Google Tag Manager

OpenAI CAPI : mesurer vos campagnes ChatGPT Ads de manière fiable

Le pixel OpenAI seul ne suffit pas

OpenAI propose deux méthodes pour mesurer les conversions de vos campagnes publicitaires dans ChatGPT : le pixel OpenAI, un script chargé dans le navigateur, et l’API de Conversions (CAPI), une communication de serveur à serveur. Comme pour les autres plateformes publicitaires, le pixel est exposé aux bloqueurs de publicité, aux restrictions des navigateurs comme Safari et à la durée de vie limitée des cookies posés depuis le navigateur. OpenAI indique d’ailleurs que l’API de Conversions est une source de mesure plus fiable que le pixel seul et recommande de l’utiliser dès que possible.

API de Conversions OpenAI + pixel OpenAI, et déduplication :

Le pixel OpenAI et l’API de Conversions ne collectent pas les données de la même manière. Le pixel collecte les données directement dans le navigateur, tandis que l’API de Conversions transmet les événements depuis votre serveur, sans dépendre du navigateur de l’internaute. Les deux méthodes peuvent être utilisées en parallèle pour maximiser le volume d’événements mesurés.

Lorsque les deux sources sont actives, OpenAI doit dédupliquer les événements reçus en doublon. Pour cela, il faut envoyer un même identifiant d’événement via chaque méthode : le paramètre event_id côté pixel et le champ id côté API. OpenAI conserve le premier événement reçu pour une même clé (identifiant du pixel, nom de l’événement et identifiant d’événement) et ignore les doublons. Si un événement n’est pas capté par le pixel mais bien transmis par le serveur, OpenAI l’enregistre : la collecte est ainsi exhaustive.

Balise OpenAI CAPI Addingwell : un tag côté serveur, des cookies qui durent

La balise OpenAI CAPI Addingwell lit les événements GA4 reçus par votre conteneur serveur, les convertit au format attendu par OpenAI et les envoie à l’API de Conversions. Elle prend en charge pour vous :

• la correspondance automatique entre les événements GA4 et les événements standard OpenAI (purchase devient order_created, page_view devient page_viewed, etc.) ;
• la normalisation et le hachage des données utilisateur (email, téléphone, nom, prénom, identifiant externe) selon les règles d’OpenAI ;
• la récupération de l’identifiant de clic oppref présent dans l’URL d’arrivée depuis une publicité ChatGPT, et sa transmission avec chaque événement ;
• la prolongation de la durée de vie des cookies : les identifiants oppref (clic) et obref (navigateur) sont réécrits côté serveur dans les cookies FPOPPREF et FPOBREF pour une durée de 365 jours. Si aucun obref n’existe encore, la balise en génère un au même format que le pixel, ce qui permet la mesure serveur même sans pixel. Le pixel les pose en JavaScript pour 30 et 365 jours, mais Safari plafonne ces cookies à 7 jours.

Configurer la balise OpenAI CAPI d’Addingwell

Importer la balise dans GTM Server

Cliquez ici  pour télécharger la balise OpenAI Conversions API et cliquez sur l’icône de téléchargement pour récupérer le fichier.

Rendez-vous ensuite dans l’onglet Templates du conteneur serveur, puis, dans la section Tag templates, cliquez sur New.

Cliquez ensuite sur les trois petits points en haut à droite, puis sélectionnez Import.

Sélectionnez ensuite le fichier template.tpl récemment téléchargé, puis cliquez sur Save.

Configurer la balise

Créez une nouvelle balise dans Google Tag Manager Server-Side et sélectionnez la balise OpenAI CAPI récemment importée. Pour configurer la balise, deux informations sont nécessaires :

• L’identifiant du pixel OpenAI sur lequel envoyer les données
• La clé de l’API de Conversions permettant de communiquer avec OpenAI

Ces deux informations se trouvent dans l’onglet Conversions de votre compte OpenAI Ads Manager. Une fois la clé et l’identifiant du pixel récupérés, configurez la balise OpenAI CAPI.

Déclencher la balise

Déclenchez enfin la balise OpenAI CAPI sur les événements GA4 pertinents en utilisant la table de correspondance de la balise.

Par exemple, pour un site e-commerce, les événements suivants sont généralement utilisés :

Pour un site de génération de leads ou d’abonnement : generate_lead, sign_up, subscribe, start_trial.

Pour une organisation optimale, créez une variable de type Lookup Table configurée comme suit :

Dans la balise OpenAI CAPI, créez un déclencheur personnalisé vérifiant que les événements proviennent de GA4 (Client Name = GA4) et que la Lookup Table précédemment configurée renvoie true.

Setup du pixel OpenAI (optionnel)

Le pixel OpenAI reste utile pour capter les identifiants oppref et obref dans le navigateur et compléter la mesure serveur. OpenAI ne propose pas de modèle de balise dans la galerie GTM : le pixel s’installe via des balises HTML personnalisé dans votre conteneur GTM Web. Si la déduplication des événements entre le pixel et OpenAI CAPI vous semble complexe, pas d’inquiétude, nous allons tout vous expliquer dans cette section.

Ce que fait le pixel dans le navigateur

Le script oaiq.min.js expose une fonction globale oaiq qui accepte notamment les commandes init et measure, ainsi que measureSingle pour cibler un pixel précis lorsque plusieurs sont initialisés. Au chargement, le pixel :

Créer la variable Event Id

Dans votre conteneur GTM Web, créez une nouvelle variable puis cliquez sur Discover more variable types in the Community Template Gallery. Sélectionnez la variable Event Id de mbaersch, puis cliquez sur Add to workspace.

Cette variable génère un identifiant unique par événement, que nous allons transmettre à la fois au pixel OpenAI et à GA4.

Installer le pixel OpenAI

Créez une balise HTML personnalisé déclenchée sur toutes les pages (Initialization - All Pages), avec le code d’initialisation fourni par OpenAI. Remplacez <YOUR-PIXEL-ID> par votre identifiant de pixel.

<script>
  (function (w, d, s, u) {
    if (w.oaiq) return;
    var q = function () { q.q.push(arguments); };
    q.q = [];
    w.oaiq = q;
    var js = d.createElement(s);
    js.async = true;
    js.src = u;
    var f = d.getElementsByTagName(s)[0];
    f.parentNode.insertBefore(js, f);
  })(window, document, "script", "https://bzrcdn.openai.com/sdk/oaiq.min.js");
 
  oaiq("init", { pixelId: "<YOUR-PIXEL-ID>" });
</script>

Pour déboguer, ajoutez debug: true à l’objet passé à init : le pixel écrit alors dans la console du navigateur chaque événement mis en file et chaque envoi, préfixés par [oaiq]. Les événements rejetés pour une erreur de format sont signalés par un avertissement validation failed; event dropped.

Gérer le consentement

Le pixel ne conditionne rien de lui-même : dès que la balise d’initialisation s’exécute, il pose ses cookies et envoie les événements. Il vous appartient donc de ne déclencher les balises du pixel que lorsque le consentement de l’utilisateur a été obtenu, conformément à la réglementation applicable à votre site.

Le pixel et la balise OpenAI CAPI côté serveur doivent respecter le même consentement : un utilisateur qui refuse ne doit être mesuré par aucune des deux méthodes.

Transmettre des données utilisateur au pixel (advanced matching)

Le pixel accepte un objet user dans init, avec les mêmes identifiants que l’API de Conversions. Les valeurs en clair sont normalisées puis hachées en SHA-256 dans le navigateur avant envoi ; une valeur déjà hachée (64 caractères hexadécimaux) est transmise telle quelle. Les données géographiques sont envoyées en clair.

Clé	Contenu attendu
email_sha256	Email en clair ou déjà haché (jusqu’à 3 valeurs)
phone_number_sha256	Téléphone avec indicatif pays, en clair ou déjà haché (jusqu’à 2 valeurs)
external_id_sha256	Identifiant client, en clair ou déjà haché
first_name_sha256, last_name_sha256	Prénom et nom, en clair ou déjà hachés
country, city, region, postal_code	Valeurs géographiques en clair

<script>
  oaiq("init", {
    pixelId: "<YOUR-PIXEL-ID>",
    user: {
      email_sha256: "{{User Email}}",
      phone_number_sha256: "{{User Phone}}"
    }
  });
</script>

OpenAI Ads Manager peut aussi activer l’automatic advanced matching : le pixel détecte alors lui-même les champs email, téléphone, nom et adresse dans vos formulaires et votre dataLayer. Cette option se pilote côté OpenAI, sans changement dans GTM.

Envoyer les événements au pixel avec l’event ID

Pour chaque événement commun avec ceux envoyés à OpenAI CAPI, créez une balise HTML personnalisé appelant oaiq("measure", nom, propriétés, options). Le pixel applique les mêmes règles de validation que l’API et rejette silencieusement tout événement non conforme :

• le troisième argument (propriétés) est obligatoire et doit contenir type avec la valeur attendue pour l’événement (contents, customer_action, plan_enrollment ou custom, voir la table de correspondance) ;
• amount doit être un entier en unité mineure de la devise (centimes) et currency est obligatoire dès qu’un montant est présent ;
• seuls les champs documentés sont acceptés : amount, currency, contents (avec id, name, content_type, quantity, amount, currency) et plan_id ;
• le quatrième argument (options) accepte event_id, custom_event_name et opt_out.

L’identifiant d’événement se transmet via la clé event_id, en y plaçant la variable Event Id créée précédemment. Sans cette clé, le pixel génère un UUID de son côté et la déduplication avec le serveur devient impossible.

Exemple pour une page vue :

<script>
  oaiq("measure", "page_viewed", { type: "contents" }, { event_id: "{{Event Id}}" });
</script>

Cette balise doit toujours s’exécuter après la balise d’initialisation du pixel. Déclenchez-la sur All Pages (et non sur Initialization) ou, plus sûr, configurez-la avec le séquençage de balises en indiquant la balise d’initialisation comme balise de configuration.

Exemple pour un achat, avec le montant en centimes et les variables de votre dataLayer :

<script>
  oaiq(
    "measure",
    "order_created",
    {
      type: "contents",
      amount: Math.round({{Ecommerce Value}} * 100),
      currency: "{{Ecommerce Currency}}"
    },
    { event_id: "{{Event Id}}" }
  );
</script>

Exemple pour un événement personnalisé, où custom_event_name doit être identique côté serveur :

<script>
  oaiq(
    "measure",
    "custom",
    { type: "custom" },
    { custom_event_name: "newsletter_opened", event_id: "{{Event Id}}" }
  );
</script>

Utilisez les mêmes noms d’événements standard qu’en server-side (page_viewed, order_created, etc.). Le pixel ne connaît pas app_installed ni app_opened, réservés à l’API de Conversions.

Ajouter l’event ID dans les événements GA4

Nous allons maintenant faire la même chose pour tous les événements GA4 qui sont communs avec ceux envoyés au pixel OpenAI.

Ajoutez le paramètre event_id avec la variable Event Id dans vos balises GA4. La balise OpenAI CAPI côté serveur réutilise automatiquement ce paramètre comme identifiant d’événement.

Pour la balise Google

Pour une balise d’événement GA4

Déclenchement des balises du pixel OpenAI

Pour que la déduplication fonctionne correctement côté OpenAI, il est nécessaire de déclencher vos balises pixel OpenAI à partir des mêmes déclencheurs que ceux utilisés pour GA4. La variable Event Id renvoie alors la même valeur pour les deux balises d’un même événement.

Vérifier les données reçues

Après avoir configuré votre balise OpenAI Conversions API, il est primordial de vérifier les éléments suivants :

• que votre conteneur serveur transmet bien les événements à OpenAI ;
• que le volume d’événements reçus par OpenAI est cohérent et que la déduplication est effective si vous utilisez aussi le pixel ;
• que la qualité des données est suffisante pour permettre à OpenAI de relier vos événements essentiels à un utilisateur ChatGPT.

Vérifier l’envoi des événements

Prévisualisation GTM Server-Side

La première étape consiste à vérifier que la balise OpenAI Conversions API s’active correctement pour les événements définis dans le déclencheur.

Dans la prévisualisation du conteneur serveur, assurez-vous que la balise se déclenche bien pour un événement spécifique (dans notre exemple, nous vérifions son activation sur l’événement purchase). Confirmez qu’elle apparaît dans la section Tags Fired et que son statut est indiqué comme Succeeded.

Dans la prévisualisation, cliquez sur la balise OpenAI Conversions API pour vérifier que la requête a bien été envoyée à bzr.openai.com. Vous pouvez y contrôler le contenu de l’événement : type d’événement, identifiant, montant en centimes, données utilisateur hachées et identifiants oppref et obref lorsqu’ils sont disponibles.

Vérifier le volume d’événements reçus

Côté OpenAI : événements reçus et déduplication

Accédez à l’onglet Conversions de votre compte OpenAI Ads Manager, puis cliquez sur Start polling events pour afficher en temps réel les événements qui arrivent chez OpenAI.

Les événements reçus par OpenAI y sont affichés par source de données : pixel et API de Conversions.

Si vous avez implémenté le double suivi de vos événements via le pixel et via OpenAI CAPI, assurez-vous que les événements :

• proviennent bien des deux sources de données, à la fois depuis le pixel et depuis l’API de Conversions ;
• sont bien dédupliqués : un même événement reçu par les deux sources contient les mêmes Event ID.

Le nombre d’événements reçus depuis le pixel devrait rester relativement stable après l’ajout d’OpenAI CAPI. En revanche, le nombre d’événements reçus depuis le serveur doit être supérieur à celui du pixel : un surplus de 5 à 20 % pour l’API de Conversions indique un bon set-up.

Côté Addingwell via Events Monitoring

Cliquez sur l’onglet Events Monitoring depuis votre container Addingwell. Sélectionnez la période de temps souhaitée, puis cliquez sur la carte du tag OpenAI Conversions API.

Cet écran vous fournit les détails des événements envoyés par votre serveur à l’API de Conversions OpenAI, ainsi que le pourcentage de réussite de chaque événement.

Si vos requêtes n’affichent pas un taux de succès de 100 %, analysez les erreurs en consultant les logs. Cliquez sur l’onglet Logs, puis sélectionnez les logs de l’API OpenAI.

Vous verrez alors les erreurs de requêtes, avec le détail du message d’erreur renvoyé par OpenAI. Les erreurs les plus fréquentes sont une devise absente alors qu’un montant est envoyé, un nom d’événement personnalisé invalide ou alors un problème d’authentification avec la clé API (ce qui est le cas ici).

Vérifier la qualité des données reçues

Envoyer vos événements de conversion à OpenAI est une première étape importante. Vous pouvez aller plus loin en ajoutant des données utilisateur (email, numéro de téléphone, nom et prénom, ville, code postal, pays) à ces événements. La balise les normalise et les hache selon les règles d’OpenAI avant envoi, ce qui permet à OpenAI d’associer les événements reçus à un utilisateur ChatGPT réel.

Cela permet à OpenAI de :

1. Mieux attribuer les conversions reçues, en identifiant celles qui n’auraient autrement pas été rattachées à vos campagnes ChatGPT Ads.
2. Optimiser les performances de vos campagnes, grâce à des signaux utilisateur de meilleure qualité.

Pour suivre notre méthodologie sur l’envoi fiable des données utilisateur côté serveur, consultez notre documentation dédiée.

Côté Addingwell via Events Monitoring

Cliquez sur le menu Events Monitoring depuis votre container Addingwell. Cet écran affiche toutes les données utilisateur traitées par votre client GA4 et mises à disposition pour vos événements côté serveur.

Prenons l’exemple de l’événement purchase : en cliquant sur le nom de l’événement, vous pouvez vérifier les paramètres disponibles pour cet événement spécifique.

Sur cet écran, vous pouvez voir le pourcentage de présence des données utilisateur, comme l’email, dans vos événements purchase, ainsi que le taux de couverture de chaque paramètre.

Les données envoyées sont de qualité lorsque les événements contiennent bien les informations utilisateur attendues et disponibles à cette étape du parcours client.

Félicitations

Vous avez terminé la configuration d’OpenAI Conversions API, et vous avez vérifié que vos événements sont bien transmis à OpenAI et correctement dédupliqués.

Si vous avez rencontré le moindre problème durant ces étapes, n’hésitez pas à contacter notre équipe support.