Événements de conversion pris en charge par l'API Ads (Supported Events)

Idée centrale

Cette page documente le vocabulaire standardisé des événements de conversion de l'API Ads d'OpenAI : treize noms d'événements standard, chacun associé à un type de données (« data shape »), et la structure exacte de chaque type de données. Ce vocabulaire est transverse : il est consommé à l'identique par les trois canaux d'envoi d'événements — Pixel de mesure JavaScript (Measurement Pixel), Conversions API (mesure de conversion côté serveur) et Image Tag (suivi de conversion sans JavaScript) — ainsi que par la définition d'événement créée via Configuration de la mesure de conversion dans l'API Ads (Conversion Setup).

Définition

La page de référence « Supported Events » de la documentation développeur Ads, qui énumère les noms d'événements de conversion pris en charge et les schémas de champs des quatre formes de données possibles.

Contexte

Cette page ne documente pas elle-même de point de terminaison REST authentifié : c'est un vocabulaire consommé par plusieurs mécanismes d'envoi. Elle est donc distincte du noyau des pages api-reference/* et traitée comme une référence transverse indépendante. Capturée le 2026-08-08.

Fonctionnement

Les treize noms d'événements standard

Nom d'événement	Type de données	Usage
`app_installed`	`customer_action`	Un utilisateur installe une application.
`app_opened`	`customer_action`	Un utilisateur ouvre une application.
`appointment_scheduled`	`customer_action`	Un utilisateur réserve un rendez-vous, une démo ou une consultation.
`checkout_started`	`contents`	Un utilisateur démarre un paiement (checkout).
`contents_viewed`	`contents`	Un utilisateur consulte un produit, une fiche, un article ou un autre contenu.
`custom`	`custom`	Un événement défini par l'annonceur, non couvert par la taxonomie standard.
`items_added`	`contents`	Un utilisateur ajoute un ou plusieurs articles à un panier, un lot ou une sélection.
`lead_created`	`customer_action`	Un utilisateur soumet un formulaire de prospect ou demande à être contacté.
`order_created`	`contents`	Un achat est finalisé.
`page_viewed`	`contents`	Un utilisateur arrive sur une page importante ou la consulte.
`registration_completed`	`customer_action`	Un utilisateur termine un parcours de création de compte ou d'inscription à un événement.
`subscription_created`	`plan_enrollment`	Un abonnement payant démarre.
`trial_started`	`plan_enrollment`	Un essai gratuit démarre.

Précisions explicites de la source :

app_installed et app_opened ne sont disponibles que via la Conversions API (pas via le pixel JavaScript actuellement), et doivent être envoyés avec action_source: "mobile_app".
page_viewed s'utilise pour les chargements de page ; contents_viewed s'utilise quand un utilisateur consulte un produit ou contenu spécifique, y compris pour des interactions survenant après le chargement de la page.
Tout objet de données d'événement doit inclure un champ type correspondant à l'événement envoyé. Si amount est inclus, currency doit aussi l'être. Les valeurs monétaires sont des entiers, dans l'unité mineure standard ISO 4217 de la devise fournie (exemple : 12999 pour 129,99 $ avec currency: "USD").

Schémas des quatre formes de données

contents

Champ	Requis	Type	Notes
`type`	Oui	string	Doit valoir `contents`.
`amount`	Non	integer	Valeur monétaire au niveau de l'événement.
`currency`	Selon	string	Requis si `amount` est présent.
`contents`	Non	array de `Content`	Items associés à l'événement.

customer_action

Champ	Requis	Type	Notes
`type`	Oui	string	Doit valoir `customer_action`.
`amount`	Non	integer	Valeur monétaire au niveau de l'événement.
`currency`	Selon	string	Requis si `amount` est présent.

plan_enrollment

Champ	Requis	Type	Notes
`type`	Oui	string	Doit valoir `plan_enrollment`.
`plan_id`	Non	string	Identifiant interne du plan (côté annonceur).
`amount`	Non	integer	Valeur monétaire au niveau de l'événement.
`currency`	Selon	string	Requis si `amount` est présent.
`contents`	Non	array de `Content`	Items optionnels liés au plan.

custom

Champ	Requis	Type	Notes
`type`	Oui	string	Doit valoir `custom`.
`plan_id`	Non	string	Identifiant de plan optionnel.
`amount`	Non	integer	Valeur monétaire au niveau de l'événement.
`currency`	Selon	string	Requis si `amount` est présent.
`contents`	Non	array de `Content`	Items optionnels associés à l'événement personnalisé.

Content (items de la liste contents[] — seuls ces champs doivent être utilisés) :

Champ	Requis	Type	Notes
`id`	Non	string	Identifiant interne de l'item (côté annonceur).
`name`	Non	string	Nom lisible de l'item.
`content_type`	Non	string	Catégorie optionnelle non vide, ex. `product`, `plan`, ou `page`.
`quantity`	Non	integer	Quantité de l'item ; entiers, pas des chaînes.
`amount`	Non	integer	Valeur monétaire au niveau de l'item.
`currency`	Non	string	À inclure si un `amount` au niveau item est envoyé ; sinon la `currency` au niveau événement s'applique si une seule devise couvre tout l'événement.

Règle de nommage pour les événements personnalisés : custom_event_name en lettres minuscules, chiffres, underscores ou tirets, 1 à 64 caractères, ne réutilisant pas un nom d'événement standard listé ci-dessus.

Éléments essentiels

Les treize événements standard se répartissent en quatre familles de forme de données : customer_action (actions sans notion de panier), contents (parcours e-commerce/contenu), plan_enrollment (abonnements et essais), custom (événement libre défini par l'annonceur).
Les mêmes noms d'événements et les mêmes formes de données sont réutilisés à l'identique par le Pixel, la Conversions API, l'Image Tag et la définition d'événement de Conversion Setup : cette page en constitue le vocabulaire canonique unique.

Distinctions importantes

Ne pas confondre page_viewed (chargement de page) et contents_viewed (consultation d'un contenu ou produit spécifique, y compris après chargement de la page) : les deux utilisent la forme contents mais couvrent des moments distincts du parcours utilisateur.

Ne pas oublier que app_installed et app_opened, bien que documentés ici au même titre que les onze autres événements, ne sont disponibles que via la Conversions API (mesure de conversion côté serveur) — pas via le pixel navigateur ni l'Image Tag.

Cas pratiques

Aucun cas pratique disponible : cette page est une référence de vocabulaire, sans exemple d'intégration réelle.

Erreurs fréquentes

Ne pas omettre currency quand amount est fourni : c'est une règle systématique sur les quatre formes de données.

Ne pas envoyer de valeurs monétaires en unité majeure (ex. 129.99) : les montants doivent être des entiers exprimés dans l'unité mineure ISO 4217 de la devise (ex. 12999 pour 129,99 $).

Ne pas réutiliser un nom d'événement standard comme custom_event_name d'un événement personnalisé.

Limites et nuances

Source unique, page de documentation développeur officielle récupérée par le web (dérogation ponctuelle autorisée), sans SHA-256 de fichier local.
La page ne précise pas si la liste de treize événements standard est exhaustive et figée, ou si OpenAI peut l'étendre sans préavis.
Aucune liste exhaustive de valeurs pour content_type n'est donnée — seuls des exemples (product, plan, page).
Détail complet des champs d'enveloppe d'événement au-delà de la forme de données (action_source, horodatage, identifiants utilisateur) non couvert ici — voir Conversions API (mesure de conversion côté serveur) et Pixel de mesure JavaScript (Measurement Pixel).

Relations

Pixel de mesure JavaScript (Measurement Pixel) — consomme ce vocabulaire pour oaiq("measure", ...).
Conversions API (mesure de conversion côté serveur) — consomme ce vocabulaire pour events[].type et events[].data.
Image Tag (suivi de conversion sans JavaScript) — consomme ce vocabulaire pour event et data[type].
Configuration de la mesure de conversion dans l'API Ads (Conversion Setup) — consomme ce vocabulaire pour event_type d'une définition d'événement.

Points à vérifier

Existence éventuelle d'une liste fermée de valeurs pour content_type.
Statut de figeage de la liste des treize noms d'événements standard (évolutivité future de la taxonomie).
Détail complet des champs d'enveloppe d'événement au-delà du data shape.

Sources

SRC-2026-034 — « Supported Events », developers.openai.com/ads/supported-events, capturée le 2026-08-08.