ChatGPT Ads
Publicité ChatGPT

Pixel de mesure JavaScript (Measurement Pixel)

Idée centrale

Le Measurement Pixel (« ChatGPT Ads Measurement Pixel ») est le SDK JavaScript côté navigateur d'OpenAI pour mesurer les événements de conversion sur un site web après qu'un utilisateur a cliqué sur une annonce ChatGPT. Il repose sur une seule primitive globale, la fonction oaiq(command, ...args), déclinée en plusieurs commandes : init (initialisation), consent (contrôle du consentement), measure (envoi d'un événement à tous les pixels initialisés) et measureSingle (envoi d'un événement à un seul pixel ciblé, quand plusieurs Pixel IDs sont utilisés sur le même site).

Définition

Le SDK JavaScript décrit par les pages « Measurement Pixel » et « Multiple Pixel IDs » de la documentation développeur Ads d'OpenAI, qui permet d'envoyer des événements de conversion depuis le navigateur d'un utilisateur, en s'appuyant sur un pixelId obtenu via Configuration de la mesure de conversion dans l'API Ads (Conversion Setup).

Contexte

Cette page fusionne deux sources : la page « Measurement Pixel », document central et le plus complet du sous-groupe « mesure de conversion côté navigateur » de la documentation développeur Ads, et la page « Multiple Pixel IDs », qui documente une extension fine de ce même SDK (la commande measureSingle) et recommandait explicitement, dans son propre contenu source, d'être absorbée dans une page canonique plus large consacrée au Measurement Pixel plutôt que de rester une page isolée.

Le pixel est un SDK navigateur, identifié par un pixelId, sans authentification par jeton porteur — à distinguer nettement de l'API REST développeur (api.ads.openai.com, authentifiée par Authorization: Bearer $OPENAI_ADS_API_KEY) documentée dans Authentification, compte publicitaire et fichiers dans l'API Ads et les pages associées : deux modèles techniques différents malgré un objectif final commun. Capturée le 2026-08-08.

Fonctionnement

Installation

Ajouter le snippet suivant en haut de la balise <head> de chaque page où des conversions doivent être mesurées (le placer tôt pour ne pas perdre les conversions précoces pendant le chargement du reste de la page) :

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

pixelId est obligatoire, créé dans l'onglet « conversions » d'Ads Manager (ou via Configuration de la mesure de conversion dans l'API Ads (Conversion Setup) côté API). debug est optionnel et journalise l'activité du SDK dans la console du navigateur pendant les tests.

Contrôle du consentement de mesure

oaiq("consent", false);
oaiq("init", { pixelId: "<YOUR-PIXEL-ID>" });

// Appeler ceci après que l'utilisateur a donné son consentement de mesure.
oaiq("consent", true);

Le pixel initialise le consentement à true par défaut, sauf s'il est explicitement mis à false ou si le pixel trouve un refus déjà stocké. Quand le consentement est false, le pixel n'envoie pas les pings d'événement de mesure. Le repasser à true autorise les événements futurs ; les événements bloqués pendant le refus ne sont pas rejoués rétroactivement.

Politique de sécurité de contenu (CSP)

DirectiveSourceObjet
script-srchttps://bzrcdn.openai.comCharger le SDK du Measurement Pixel.
connect-srchttps://bzr.openai.comEnvoyer les événements via fetch ou sendBeacon.
connect-srchttps://bzrcdn.openai.comRécupérer la configuration propre à chaque pixel.
img-srchttps://bzr.openai.comEnvoyer les événements via le repli en requête image.

Exemple de politique restreinte au même-origine avec nonce :

Content-Security-Policy: default-src 'self'; script-src 'self' 'nonce-<NONCE>' https://bzrcdn.openai.com; connect-src 'self' https://bzr.openai.com https://bzrcdn.openai.com; img-src 'self' https://bzr.openai.com;

Remplacer <NONCE> par un nonce frais à chaque réponse et ajouter la même valeur à la balise d'ouverture du snippet (<script nonce="<NONCE>">). Un mécanisme CSP existant basé sur des hash peut être utilisé à la place. Ne pas ajouter 'unsafe-inline' uniquement pour le Measurement Pixel. Si la politique définit script-src-elem, y ajouter aussi la source CDN et le nonce/hash.

Envoi de données utilisateur (matching manuel)

Objet user optionnel passé à oaiq("init", ...), à portée requête (pas à répéter dans chaque measure) :

oaiq("init", {
  user: {
    email_sha256: "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514",
    external_id_sha256: "73d83a078369bb4f0971b317aa7797a91cf5c0df1b62161c2e47d75c33ab5b6e",
    country: "US",
    city: "San Francisco",
    zip_code: "94107",
  },
});
ChampDescription
email_sha256Hash SHA-256 de l'adresse e-mail, après suppression des espaces et conversion en minuscules.
external_id_sha256Hash SHA-256 d'un identifiant client pseudonyme stable propre au système de l'annonceur.
countryCode pays ISO 3166-1 à deux lettres.
cityNom de ville, 128 caractères maximum ; OpenAI supprime les espaces et convertit en minuscules.
zip_codeCode postal ; lettres, chiffres, espaces ou tirets, 32 caractères maximum.

Tous les champs sont optionnels ; n'inclure que ceux disponibles. Envoyer les hashs en chaînes hexadécimales minuscules de 64 caractères. Ne jamais envoyer d'adresses e-mail brutes, d'identifiants externes bruts, de numéros de téléphone, ni de hashs de numéros de téléphone. Si les données ne sont disponibles qu'après coup, rappeler init avec l'objet user complet ; pixelId peut être omis lors de ce rappel si une seule page n'initialise qu'un seul pixel, mais doit toujours être inclus si plusieurs pixels sont initialisés sur la page.

Appariement avancé automatique (Automatic advanced matching)

Le pixel détecte automatiquement les informations client saisies dans les formulaires du site, les normalise et les hache en SHA-256 dans le navigateur avant de les joindre aux événements de conversion. Les informations client brutes ne sont pas envoyées à OpenAI par ce mécanisme. Aucune configuration manuelle ni modification de l'implémentation du pixel n'est nécessaire.

Envoi d'un événement standard — measure

oaiq("measure", "order_created", {
  type: "contents",
  amount: 2599,
  currency: "USD",
});

Un appel measure accepte jusqu'à quatre arguments :

ArgumentObligatoireContenu attendu
CommandeOui"measure".
Nom d'événementOuiUn nom d'événement pris en charge — voir Événements de conversion pris en charge par l'API Ads (Supported Events) — ou "custom".
Données d'événementOuiObjet dont type correspond à la forme de données de l'événement.
OptionsSelon casOptionnel pour un événement standard ; obligatoire pour un événement personnalisé.

Options prises en charge :

ChampQuand l'utiliser
event_idFixer un identifiant unique, pour dédupliquer le même événement envoyé par le navigateur et par le serveur.
custom_event_nameNommer un événement personnalisé ; obligatoire pour un événement personnalisé.
opt_outtrue pour exclure l'événement de la personnalisation future au niveau utilisateur ; false par défaut.

Le Measurement Pixel ne prend pas en charge app_installed ni app_opened : ces deux événements s'envoient uniquement côté serveur via la Conversions API (mesure de conversion côté serveur).

Événement personnalisé

oaiq(
  "measure",
  "custom",
  { type: "custom" },
  { custom_event_name: "quote_requested" }
);

"custom" en deuxième position identifie l'événement comme personnalisé ; { type: "custom" } sélectionne la forme de données « custom » ; custom_event_name donne son nom descriptif. Des champs plan_id, amount, currency ou contents peuvent s'ajouter à l'objet de données.

Règles de nommage : 1 à 64 caractères ; uniquement lettres, chiffres, tirets bas ou tirets ; doit commencer et finir par une lettre ou un chiffre ; ne doit pas correspondre à un nom d'événement standard.

Exemples d'événements standards

// Vue de page (forme "contents")
oaiq("measure", "page_viewed", {
  type: "contents",
  contents: [{ id: "pricing", name: "Pricing page", content_type: "page" }],
});

// Achat finalisé (forme "contents")
oaiq("measure", "order_created", {
  type: "contents",
  amount: 2599,
  currency: "USD",
  contents: [{ id: "sku_123", name: "Starter bundle", content_type: "product", quantity: 1 }],
});

// Génération de lead (forme "customer_action")
oaiq("measure", "lead_created", { type: "customer_action" });

// Abonnement (forme "plan_enrollment")
oaiq("measure", "subscription_created", {
  type: "plan_enrollment",
  plan_id: "pro_monthly",
  amount: 2000,
  currency: "USD",
});

Voir Événements de conversion pris en charge par l'API Ads (Supported Events) pour la liste complète des noms d'événements et la définition formelle des formes de données (contents, customer_action, plan_enrollment, custom).

Plusieurs Pixel IDs sur un même site

Cas d'usage : mesurer des conversions pour plus d'un annonceur, marque ou partenaire d'intégration depuis le même site. Le SDK se charge une seule fois ; chaque Pixel ID s'initialise séparément.

Initialiser plusieurs pixels :

oaiq("init", { pixelId: "<PIXEL-ID-A>" });
oaiq("init", { pixelId: "<PIXEL-ID-B>" });

Envoyer un événement à tous les pixels initialisés — measure diffuse à tous les Pixel IDs déjà initialisés au moment de l'appel. Un pixel initialisé après l'appel ne reçoit pas les événements envoyés avant son initialisation (pas de rétroactivité).

Envoyer un événement à un seul pixel ciblé — measureSingle :

oaiq("measureSingle", "<PIXEL-ID-A>", "order_created", {
  type: "contents",
  amount: 2599,
  currency: "USD",
});

Signature complète : oaiq("measureSingle", pixelId, eventName, eventData, eventOptions) — mêmes données et options que measure, avec le Pixel ID inséré avant le nom de l'événement. Le Pixel ID cible doit être initialisé avant l'appel. Le SDK n'envoie pas un événement destiné à un Pixel ID inconnu vers un autre pixel (pas de repli silencieux).

Déduplication des événements navigateur et serveur

oaiq(
  "measure",
  "order_created",
  { type: "contents", amount: 2599, currency: "USD" },
  { event_id: "order_12345" }
);

L'event_id doit être généré par l'annonceur et réutilisé côté pixel et côté serveur (voir Conversions API (mesure de conversion côté serveur)). Pour un événement personnalisé, garder également le même custom_event_name des deux côtés. La déduplication se fait sur la combinaison Pixel ID + nom d'événement + event_id (custom_event_name remplaçant le nom d'événement standard pour un événement personnalisé).

Ce que le SDK gère automatiquement

Capture de oppref depuis l'URL de la page d'atterrissage ; stockage dans un cookie first-party __oppref pour réutilisation lors de vues de page ultérieures ; ajout de l'origine de la page courante comme source_url ; horodatage de chaque événement et regroupement en lot des appels measure rapprochés ; quand l'appariement avancé automatique est actif, détection des informations client dans les formulaires et inclusion de leur hash SHA-256.

Dépannage

Garder debug: true pendant les tests pour inspecter l'activité du pixel dans la console du navigateur ; utiliser des valeurs entières pour amount et quantity ; n'utiliser que les champs documentés dans contents[] ; toujours utiliser le pixel côté navigateur — ne jamais appeler directement l'API de conversions serveur depuis le code de page.

Éléments essentiels

Distinctions importantes

Ne pas confondre measure (diffusion à tous les Pixel IDs initialisés) et measureSingle (ciblage d'un seul Pixel ID, inséré en deuxième position de l'appel).

Ne pas confondre advanced matching manuel (objet user explicitement envoyé à init) et appariement avancé automatique (détection et hachage transparents des formulaires du site, sans configuration).

Ne pas confondre ce SDK navigateur (identifié par pixelId, sans jeton porteur) avec l'API REST développeur (identifiée par $OPENAI_ADS_API_KEY) documentée dans Authentification, compte publicitaire et fichiers dans l'API Ads : deux modèles d'authentification distincts pour deux composants distincts de l'écosystème Ads.

Cas pratiques

Aucun cas pratique disponible : les exemples de code sont des modèles génériques fournis par la documentation, pas des intégrations réelles observées.

Erreurs fréquentes

Ne pas croire que les événements bloqués pendant un refus de consentement seront rejoués une fois le consentement accordé : ils sont définitivement perdus pour la mesure via le pixel, sauf renvoi par un autre canal.

Ne pas appeler l'API de conversions serveur directement depuis le code de page : toujours passer par le pixel côté navigateur pour la mesure client.

Ne pas ajouter 'unsafe-inline' à la politique CSP uniquement pour faire fonctionner le pixel : utiliser un nonce ou un hash.

Ne pas envoyer d'adresses e-mail, d'identifiants externes ou de numéros de téléphone bruts (non hachés) dans l'objet user.

Limites et nuances

Relations

Points à vérifier

Sources