ChatGPT Ads
Publicité ChatGPT

Configuration de la mesure de conversion dans l'API Ads (Conversion Setup)

Idée centrale

Avant de pouvoir envoyer des événements de conversion — que ce soit via le Pixel de mesure JavaScript (Measurement Pixel) ou la Conversions API (mesure de conversion côté serveur) — trois ressources doivent être créées par programmation pour le compte publicitaire courant : un pixel (source de conversion web), une clé Conversions API (pour l'envoi côté serveur), et une définition d'événement (« event setting », qui relie un type d'événement à une source de conversion). Ces trois ressources se créent via l'API REST Ads standard, authentifiée par jeton porteur — la même que celle documentée dans Authentification, compte publicitaire et fichiers dans l'API Ads — et non par un mécanisme distinct.

Définition

Les quatre points de terminaison de la page de référence API « Conversion Setup » (api-reference/conversion-setup), qui permettent de provisionner par programmation les ressources de mesure de conversion (pixel, clé Conversions API, définitions d'événements) consommées ensuite par le pixel JavaScript et la Conversions API.

Contexte

Cette page fait partie des huit pages de la référence API Ads (« api-reference »), au même titre que Authentification, compte publicitaire et fichiers dans l'API Ads, Campagnes et annonces dans l'API Ads et Insights et reporting dans l'API Ads — même authentification par jeton porteur, même URL de base https://api.ads.openai.com/v1, mêmes conventions JSON. Elle est traitée séparément de ces trois autres pages, car son contenu (provisionnement de ressources de mesure) est fortement couplé aux pages consommatrices Pixel de mesure JavaScript (Measurement Pixel) et Conversions API (mesure de conversion côté serveur), avec lesquelles elle forme un même parcours fonctionnel (« que dois-je créer avant d'envoyer un événement de conversion ? »).

La gestion des pixels et la création de clés Conversions API doivent être activées pour le compte publicitaire : une réponse 404 avec Not found sur /conversions/pixels ou /conversions/api_keys signale une fonctionnalité non activée, à résoudre en contactant son représentant partenaire OpenAI. Une réponse Client data source not found lors de la création d'une définition d'événement signifie que source_ids référence une source inexistante dans le compte courant. Capturée le 2026-08-08.

Fonctionnement

1. Créer un pixel — POST /conversions/pixels

Crée une source de conversion web et son identifiant de pixel.

ChampTypeRequisNotes
namestringOuiNom descriptif, 3 à 1 000 caractères.
client_typestringOuiUtiliser web.
automatic_advanced_matching_enabledbooleanNontrue pour activer l'appariement avancé automatique, false pour le désactiver — voir « changement de comportement par défaut » ci-dessous.
 
curl -X POST "https://api.ads.openai.com/v1/conversions/pixels" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme website",
    "client_type": "web",
    "automatic_advanced_matching_enabled": true
  }'

Réponse :

{
  "id": "clidsrc_123",
  "client_type": "web",
  "name": "Acme website",
  "pixel_id": "134534...",
  "automatic_advanced_matching_enabled": true
}

Deux identifiants homonymes à distinguer : id (préfixe clidsrc_) sert de valeur source_ids lors de la création d'une définition d'événement, ci-dessous ; pixel_id sert à initialiser le pixel JavaScript et à envoyer des événements via la Conversions API (voir Pixel de mesure JavaScript (Measurement Pixel) et Conversions API (mesure de conversion côté serveur)).

Changement de comportement annoncé au 17 août 2026 : jusqu'à cette date, automatic_advanced_matching_enabled vaut false par défaut quand il est omis. À partir du 17 août 2026, les nouveaux pixels web créés via l'API Ads auront ce champ activé (true) par défaut lorsqu'il est omis ; il faut passer explicitement false pour le désactiver. À la même date, OpenAI activera aussi l'appariement avancé automatique pour tous les pixels web existants créés via l'API Ads, sauf désactivation explicite préalable ou opt-out du compte publicitaire.

2. Créer une clé Conversions API — POST /conversions/api_keys

ChampTypeRequisNotes
namestringOuiNom descriptif, 3 à 1 000 caractères.
 
curl -X POST "https://api.ads.openai.com/v1/conversions/api_keys" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme production conversions"
  }'

Réponse : {"name": "Acme production conversions", "api_key": "<CONVERSIONS_API_KEY>"}.

Avertissement explicite : stocker la clé retournée dans un gestionnaire de secrets côté serveur ; ne jamais la placer dans du code navigateur, des variables d'environnement visibles côté client, des journaux ou un dépôt de code source.

3. Créer une définition d'événement — POST /conversions/event_settings

Relie un type d'événement à exactement une source de conversion.

ChampTypeRequisNotes
namestringOuiNom d'affichage de la conversion.
event_typestringOuiUn événement pris en charge — voir Événements de conversion pris en charge par l'API Ads (Supported Events) — ou custom.
custom_event_namestringSelon casRequis quand event_type vaut custom.
attribution_window_daysintegerOuiUtiliser 30.
source_idsstring[]OuiExactement un identifiant de source de conversion (l'id retourné par la création du pixel, ci-dessus).
 
curl -X POST "https://api.ads.openai.com/v1/conversions/event_settings" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Purchases",
    "event_type": "order_created",
    "attribution_window_days": 30,
    "source_ids": ["clidsrc_123"]
  }'

Réponse :

{
  "id": "ces_123",
  "name": "Purchases",
  "event_type": "order_created",
  "custom_event_name": null,
  "attribution_window_days": 30,
  "ad_account_id": "adacct_123",
  "source_ids": ["clidsrc_123"],
  "sources": [{ "id": "clidsrc_123", "name": "Acme website" }],
  "campaigns": [],
  "archived": false,
  "version": 1
}

L'id retourné (préfixe ces_) est le conversion_event_setting_ids consommé par une campagne oCPC — voir Campagnes optimisées pour la conversion via l'API Ads (oCPC).

4. Lister les définitions d'événements — GET /conversions/event_settings

ParamètreTypeRequisNotes
limitintegerNonEntre 1 et 500.
afterstringNonCurseur pour la page suivante.
beforestringNonCurseur pour la page précédente.
orderstringNonasc ou desc.

La page source ne fournit pas d'exemple de réponse JSON pour cet endpoint — uniquement l'exemple de requête.

5. Envoyer des événements

Une fois le pixel, la clé Conversions API et la définition d'événement créés, deux mécanismes consomment ces identifiants pour l'envoi effectif des événements : le Pixel de mesure JavaScript (Measurement Pixel) (côté navigateur, pixel_id) et la Conversions API (mesure de conversion côté serveur) (côté serveur, pixel_id + clé). Si les deux sources envoient le même événement, il est recommandé d'utiliser un identifiant d'événement partagé pour permettre la déduplication.

Éléments essentiels

Distinctions importantes

Ne pas confondre id (préfixe clidsrc_, identifiant API de la source de conversion, utilisé dans source_ids) et pixel_id (identifiant utilisé côté implémentation, pixel JavaScript et Conversions API) : ce sont deux identifiants distincts issus de la même réponse de création de pixel.

Ne pas confondre la clé API Ads ($OPENAI_ADS_API_KEY, utilisée pour authentifier tous les appels de cette page, y compris la création de la clé Conversions API elle-même) et la clé Conversions API (api_key retournée par POST /conversions/api_keys, utilisée uniquement pour authentifier l'envoi d'événements serveur documenté dans Conversions API (mesure de conversion côté serveur)).

Cas pratiques

Aucun cas pratique disponible : identifiants et valeurs d'exemple (Acme website, clidsrc_123, ces_123) manifestement fictifs et illustratifs.

Erreurs fréquentes

Ne pas placer la clé Conversions API retournée par POST /conversions/api_keys dans du code navigateur : elle doit rester côté serveur, dans un gestionnaire de secrets.

Ne pas confondre id et pixel_id lors de l'implémentation du pixel JavaScript ou de la Conversions API : c'est pixel_id qui est requis à ces deux étapes, pas l'id de la source de conversion.

Limites et nuances

Relations

Points à vérifier

Sources