Passer au contenu principal

​
Configuration de l’API de conversion

​
Prérequis 

​
Accès à l’Ads API - Nouvelles demandes

Étape 1 : Compte développeur
  • Lors de la demande d’un compte développeur, souscrivez à l’un de nos plans d’abonnement pour une approbation instantanée.
  • Remarque : Par bonne pratique, nous recommandons fortement d’utiliser le handle X officiel de votre entreprise pour créer un compte développeur et demander l’accès à l’Ads API. Si le compte développeur est associé à un handle de développeur, il n’existe aucun moyen de transférer ces identifiants le cas échéant. Il est préférable de l’héberger sous un compte d’entreprise pour une gestion continue et d’utiliser le Multi-user login si nécessaire. À défaut, au minimum, le compte doit être configuré avec des paramètres non par défaut (image d’en-tête, avatar, description de la bio et URL de la bio) et utiliser l’authentification à deux facteurs.
Étape 2 : Demande d’accès à l’Ads API
  • Assurez-vous d’avoir le bon App ID prêt pour votre demande d’accès à l’Ads API. L’App ID se trouve dans le developer portal, sous Projects & Apps. Exemple : 16489123
  • Demandez l’accès à l’Ads API en contactant votre représentant X.

​
Accès à la X Ads API - Applications existantes

  • Si vous disposez déjà d’une application X Ads API utilisée activement, l’application et les access tokens existants peuvent être utilisés avec la Conversion API.

​
Access Tokens

  • Des Access Tokens utilisateur pour le handle possédant l’application X Ads API peuvent être générés et récupérés directement depuis le developer portal. Il s’agit de votre « personal access token », car il est destiné à être utilisé avec votre propre handle X. Des informations générales sur l’authentification et le developer portal sont disponibles ici.
  • Des Access Tokens utilisateur pour des handles autres que celui possédant l’application X Ads API doivent être générés via un flux OAuth à 3 étapes. Les options pour générer l’Access Token avec un flux OAuth à 3 étapes incluent :
  • Tout jeton utilisateur utilisé avec la Conversion API doit concerner des utilisateurs ayant un niveau d’accès AD_MANAGER ou ACCOUNT_ADMIN, ce qui peut être vérifié via l’endpoint authenticated_user_access.
  • Remarque : les jetons eux-mêmes (après leur création comme indiqué ci-dessus) peuvent être partagés avec des utilisateurs sans niveau d’accès AD_MANAGER ou ACCOUNT_ADMIN pour utilisation.

​
Étapes

​
Création de l’événement Conversion API

Pour utiliser la Conversion API, vous devez créer un nouvel événement de conversion dans Ads Manager ou utiliser un événement existant déjà créé et utilisé avec le X Pixel. Si vous souhaitez dédupliquer entre les événements Pixel et Conversion API, vous devez utiliser l’événement existant que vous avez créé pour le Pixel. 
Option 1 : Utiliser un événement de conversion existant dans Ads Manager
Si vous souhaitez utiliser un événement que vous employez déjà avec le pixel X, c’est possible ; vous devrez alors récupérer l’id de l’événement correspondant. Si vous utilisez à la fois le pixel et la Conversion API pour le même événement, veillez à utiliser la clé de déduplication dans l’extrait de code du Pixel et dans la requête Conversion API (via conversion_id) afin de dédupliquer les événements entre le Pixel et la Conversion API pour ce même événement. Consultez la section d. Testing Events and Deduplication pour plus d’informations. 
Option 2 : créer un nouvel événement de conversion dans Ads Manager :
Il est important d’avoir une source d’événements créée dans Events Manager avant de créer un événement. Pour vérifier si vous avez une source d’événements (X Pixel) ajoutée à votre compte, rendez-vous dans Events Manager et vérifiez si X Pixel apparaît dans votre menu de gauche. Si vous n’avez pas encore ajouté de source d’événements, veuillez suivre les étapes ci-dessous pour en créer une.
  1. Allez sur ads.x.com
  2. Accédez à la section Tools en haut à gauche et cliquez sur Events Manager
  3. Sélectionnez Add event source en haut à droite pour Add an event source si vous n’avez pas encore de source d’événements X Pixel dans votre barre latérale gauche
    1. L’id de la source d’événements X Pixel est votre Pixel ID
Vous avez maintenant une source d’événements et un Pixel ID. Vous devez créer un événement dans la source d’événements pour les conversions que vous souhaitez suivre :
  1. Dans la source d’événements X Pixel, sélectionnez Add events sur le côté droit
  2. Sélectionnez Install with Conversion API
  3. Vous verrez le Pixel ID et l’Event ID de cet événement, qui seront utilisés dans l’API
    1. L’id de l’événement est votre Event ID
  4. Cliquez sur Save et votre événement de conversion sera créé et prêt à l’emploi

​
Préparation des identifiants pour les événements de conversion 

Nous avons actuellement besoin qu’au moins un identifiant soit transmis, comme un Click ID (twclid), une adresse e‑mail ou un numéro de téléphone. Si vous utilisez une adresse IP ou un user agent, un deuxième identifiant doit être envoyé pour un appariement de conversion correct. Transmettre davantage d’identifiants augmentera le taux d’appariement des conversions.
Champ d’appariement clientFormatHachage requis ?
X Click IDGénéré par X (En savoir plus)Non
Adresse e‑mailSupprimer les espaces de début et de finRequis (SHA256)
Numéro de téléphoneNorme E.164Requis (SHA256)
Adresse IPSupprimer les espaces de début et de finNon
User agentSupprimer les espaces de début et de finNon

​
1. Préparer l’identifiant X Click ID

Il est recommandé d’inclure systématiquement le Click ID dans la requête de conversion. Le Click ID doit être extrait du paramètre de chaîne de requête query twclid lorsqu’il est disponible, après que l’utilisateur a accédé au site de destination. Exemple de code JavaScript simple : 
var queryString = document.location.search;
if (queryString.has('twclid') {
  twitterClickID = getParam(queryString, 'twclid');
  // Étapes recommandées suivantes : journalisation, insertion dans le stockage local
}
Il est recommandé de : 
  1. Toujours extraire la valeur twclid lorsqu’elle est présente dans les paramètres query de l’URL.
  2. Stocker les data avec les fields de formulaire pertinents ou les informations d’événement de conversion.
Associer le Click ID aux événements de conversion et aux informations de workflow permet des scénarios tels que le traitement par lots, la mise en œuvre d’algorithmes pour analyser et créer des événements de conversion à partir de multiples parcours de navigation sur le site web, ainsi que des importations en masse. L’URL de la source de l’événement doit être encodée en pourcentage (URL encoding) et doit représenter la page web qui a déclenché l’événement.

​
2. Préparer l’identifiant d’email 

Les champs de correspondance client pris en charge peuvent être envoyés, mais doivent être normalisés et, le cas échéant, hachés pour protéger la confidentialité. Les informations doivent être hachées avec SHA256, sans sel.  Par exemple, pour l’adresse email test@x.com, elle doit nous être envoyée sous forme hachée : d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62.

​
3. Préparer l’identifiant de téléphone 

Le numéro de téléphone doit être transmis au format E.164 et les données doivent être hachées avec SHA‑256, sans sel.  Par exemple, pour un numéro de téléphone américain : +11234567890, il doit nous être envoyé sous forme de hachage : 1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231.

​
4. Préparer l’identifiant d’adresse IP

L’adresse IP doit être transmise conjointement avec un autre identifiant (twclid, adresse e‑mail, numéro de téléphone ou agent utilisateur). Aucun hachage n’est requis pour cet identifiant. Cette valeur s’écrit en notation décimale pointée, avec quatre nombres séparés par des points. Par exemple, l’adresse IP d’un utilisateur peut être 8.25.197.25.

​
5. Préparer l’identifiant User Agent

Le User Agent doit être transmis conjointement avec un autre identifiant (twclid, adresse e-mail, numéro de téléphone ou adresse IP). Aucun hash n’est requis pour cet identifiant. Cet identifiant permet au serveur d’identifier l’application, le système d’exploitation, le fournisseur et/ou la version de l’agent utilisateur à l’origine de la requête. Par exemple, cette valeur peut être transmise sous la forme Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36.

​
Construction de la requête d’événement de conversion

POST: version/measurement/conversions/:pixel_id Envoyez des événements de conversion pour un compte publicitaire donné. Vérifiez le code de réponse pour confirmer la réussite (HTTP 200 OK). Il est recommandé de mettre en place un mécanisme de nouvelle tentative et une journalisation de base au cas où des codes d’erreur seraient renvoyés. Pour des informations détaillées sur l’URL de l’endpoint et les paramètres du corps de la requête POST, veuillez consulter la section Référence de l’API. 

​
Exemple de requête (mis en forme pour plus de lisibilité)


    twurl -H 'ads-api.x.com' -X POST '/12/measurement/conversions/oka17' --data '
    {
      "conversions":[
         {
            "conversion_time":"2022-02-18T01:14:00.603Z",
            "event_id":"ol288",
            "identifiers":[
               {
                  "twclid":"23opevjt88psuo13lu8d020qkn"
               },
               {
                  "hashed_email":"d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62"
               },
               {
                  "hashed_phone_number":"1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231"
               },
               {
                  "ip_address":"1.0.0.0",
                  "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36"
               }
            ],
            "value":"20.00",
            "number_items":3,
            "conversion_id":"23294827",
            "description":"Achats de fournitures pour animaux de compagnie",
            "contents":[
               {
                  "content_id":"1",
                  "content_name":"Couvertures",
                  "content_type":"Fournitures pour animaux de compagnie",
                  "content_price":100.99,
                  "num_items":1,
                  "content_group_id":"123"
               }
            ]
         }
      ]
    }' --header 'Content-Type: application/json'

​
Exemple de réponse

{"request": {
 "params": {
     "account_id":"18ce552mlaq"}
 },
 "data": {
    "conversions_processed":1,
     "debug_id":"ff02e052-36e4-47d6-bdf0-6d8986446562"}
}

​
Limite de taux

La limite de taux est de 60 000 événements par compte, par intervalle de 15 minutes. Notez que votre code serveur peut nécessiter d’implémenter une logique en dehors de cet appel, notamment :
  1. Instrumenter les actions des utilisateurs (journalisation) afin d’envoyer des données de conversion correctes pour chaque événement
  2. Toute logique nécessaire pour filtrer les événements de conversion des utilisateurs ayant exercé des choix de confidentialité pertinents — par exemple, s’ils ont refusé le suivi ou la vente de leurs informations personnelles sur le site de l’annonceur
  3. L’intégration avec les déclencheurs d’événements et les pages afin de capturer les événements et d’envoyer les conversions

​
Test des événements et déduplication

​
Test des événements

Lorsque votre événement commence à recevoir des conversions, le statut de la « Single event web tag » devrait indiquer TRACKING sur la page Conversion Tracking de l’Ads Manager dans un délai de 12 à 24 heures. L’envoi de conversions via la Conversion API n’affectera pas les campagnes en cours. Vous pouvez également consulter les résultats d’analyse de votre événement de conversion par id de tag en :

​
Déduplication entre Pixel et Conversion API

Si vous souhaitez dédupliquer les conversions entre les requêtes Pixel et Conversion API, nous utilisons conversion_id comme clé de déduplication. La déduplication s’effectue uniquement au niveau de l’événement. En d’autres termes, pour dédupliquer entre les requêtes Pixel et CAPI, un annonceur doit utiliser le même événement dans les requêtes Pixel et CAPI, en plus d’utiliser le même conversion_id. La déduplication ne peut s’appliquer qu’aux événements reçus dans une fenêtre de 48 h.

​
Suivi des conversions (Vue d’ensemble)

​
Résumé

Le suivi des conversions vous permet de mesurer le nombre d’utilisateurs X qui effectuent une action souhaitée après avoir vu vos publicités sur X et interagi avec elles. Il vous permet d’identifier quelles campagnes génèrent des actions telles que des visites de site, des inscriptions et des achats. Les annonceurs disposent ainsi de capacités de mesure hors X pour évaluer les performances de leurs campagnes à réponse directe et acquérir des clients de manière rentable. À l’aide d’une balise de conversion, les annonceurs peuvent suivre les conversions des utilisateurs et les associer à des campagnes publicitaires sur X. Cela leur donne la visibilité nécessaire pour optimiser leurs campagnes et atteindre leurs objectifs de coût par acquisition (CPA). Il existe une variété d’actions sur un site web qu’un annonceur peut mesurer avec le suivi des conversions. Il peut en sélectionner une ou plusieurs, en fonction des actions qu’il souhaite susciter avec sa campagne publicitaire :
  • Visite du site : l’utilisateur consulte une page d’atterrissage sur le site de l’annonceur
  • Achat : l’utilisateur finalise l’achat d’un produit ou d’un service sur le site de l’annonceur
  • Téléchargement : l’utilisateur télécharge un fichier, tel qu’un livre blanc ou un paquet logiciel, depuis le site de l’annonceur
  • Inscription : l’utilisateur s’inscrit au service, à la newsletter ou aux communications par e‑mail de l’annonceur
  • Personnalisée : catégorie générique pour une action personnalisée qui n’entre dans aucune des catégories ci‑dessus
Le suivi des conversions de X offre aux annonceurs une vision complète de l’attribution des conversions. Comparée aux solutions de mesure tierces que certains clients ont pu utiliser à la place de la solution native de X (par exemple, des URL de clic uniques associées à des balises de suivi tierces), la balise de conversion de X permet aux annonceurs de suivre les conversions attribuées à des interactions de milieu et haut de funnel, telles que l’extension de Tweet, les Retweets, les mises en favori, les réponses et les abonnements, ainsi qu’aux impressions.

​
FAQ

Tout d’abord, un annonceur crée une balise de conversion, c’est‑à‑dire un extrait de code fourni par X, et l’intègre à son site web. La balise est alors prête à mesurer la conversion lorsqu’un utilisateur réalise l’action définie.Les utilisateurs sont ensuite exposés à la publicité de l’annonceur sur le client X, ce qui les renvoie vers le site web de l’annonceur et l’action qui a été balisée. Si l’utilisateur réalise cette action pendant la ou les fenêtres d’attribution spécifiées par les annonceurs lors de la configuration de la balise, celle‑ci reconnaît que l’utilisateur a déjà interagi avec une publicité X. La balise se « déclenche », puis envoie une notification aux serveurs de X afin que la conversion puisse être attribuée à la publicité qui l’a générée.
Non, notre produit n’est pas conçu pour associer des balises de conversion spécifiques à des campagnes spécifiques. En revanche, une fois une balise configurée, le système identifie automatiquement quelle publicité a généré des conversions sur cette balise.
Fenêtre d’attribution post‑vue par défaut : 1 jourFenêtre d’attribution post‑engagement par défaut : 14 joursCes valeurs par défaut peuvent être modifiées lors de la configuration de la balise de conversion ou à tout moment après la création de la balise. Les options pour les fenêtres d’attribution post‑engagement sont 1, 7, 14, 30, 60 et 90 jours. Les options pour les fenêtres d’attribution post‑vue sont aucune, 1, 7, 14, 30, 60 et 90 jours.
Bien que les objectifs, la situation et les stratégies varient selon les clients, voici quelques idées qui ont fonctionné pour des clients ayant participé aux phases alpha ou bêta du suivi des conversions :Création :
  • Offres : Associer une remise, une promotion ou la livraison gratuite au Tweet sponsorisé pour susciter davantage d’intérêt pour l’action
  • Jeux‑concours : En particulier pour les marques connues, les jeux‑concours ont généré des conversions
  • Expérimentation sur le texte du Tweet : Tester les majuscules vs minuscules (FREE vs free ou NOW vs now)
  • Dates limites : Proposer une échéance pour encourager les personnes à agir immédiatement (Offre valable jusqu’au 12 décembre !)
  • Ajout de photos percutantes : Il est pertinent de tester si des visuels percutants dans la création du Tweet favorisent les conversions ; les résultats peuvent varier ou dépendre de l’offre du client.
Ciblage :
  • Ciblage par @handle et par catégorie d’intérêt : Un alignement étroit entre le texte du Tweet, les @handles et l’audience visée du Tweet a généré des conversions
  • Utilisation de mots‑clés de niche mais à fort volume : Dans l’univers des concerts, l’utilisation de mots‑clés liés à l’artiste/musicien (p. ex. leur nom) s’est avérée efficace.
  • Audiences personnalisées : Les clients utilisant TA web et le suivi des conversions conjointement ont obtenu des CPA plus bas que les groupes témoins utilisant d’autres ciblages
Plus votre segmentation de campagne est fine, plus vos résultats de conversion seront exploitables. Par exemple, il est beaucoup plus facile d’optimiser une campagne avec 4 mots‑clés que d’optimiser une campagne avec 50.

​
Dépannage et assistance pour la Conversion API

Pour toute question concernant les codes d’erreur après un appel à l’API, veuillez consulter la section ci-dessous. Pour toute autre question, n’hésitez pas à contacter votre représentant Twitter ; nous nous efforcerons de les résoudre dans les plus brefs délais. 

​
Gestion et explication des erreurs

Une requête ne sera considérée comme réussie que s’il n’y a aucune erreur pour l’ensemble des conversions qu’elle contient. En cas d’erreur dans une conversion donnée, l’endpoint renverra la liste de toutes les erreurs pertinentes.

​
Aperçu des codes d’erreur de la X Ads API

Voici une liste complète des codes d’erreur de la X Ads API : https://developer.x.com/en/docs/twitter-ads-api/response-codes Les réponses réussies de la Conversion API sont indiquées par un code HTTP de la série 200 et un payload au format JSON contenant l’objet demandé.

​
Lorsqu’un code HTTP de la série 500 apparaît, il s’agit d’un problème côté serveur et non de votre requête ou de la configuration de votre compte. Veuillez consulter la page d’état de X API ou le forum de la communauté des développeurs pour vérifier si d’autres rencontrent des problèmes similaires.

​
Lorsqu’un code HTTP de la série 400 est renvoyé, les cas les plus fréquents sont :

  • 400 Bad Request (la requête ne respecte pas les normes)
  • 401 Unauthorized (problèmes d’authentification)
  • 403 Forbidden (problèmes d’accès à l’API associés à ce compte développeur)
  • 404 Not Found (l’URL ou les paramètres peuvent être incorrects pour l’endpoint)

​
Codes d’erreur de l’API Conversion

​
Scénarios 400 Bad Request

RaisonTypeMessage d’erreur
Identifiant manquant (actuellement e-mail haché ou X click ID — twclid)400 Bad RequestAu moins un identifiant utilisateur doit être fourni
E-mail haché invalide400 Bad RequestHashed_email n’est pas un hash SHA-256 valide
Le type de event_id n’est pas une balise d’événement unique (SET)400 Bad RequestEvent_id (<event_id>) n’est pas une balise d’événement unique (SET)
Les événements de conversion demandés dépassent la limite (actuellement 500 événements par requête)400 Bad RequestLa limite du nombre de conversions est de 500
Event ID manquant400 Bad RequestEvent ID introuvable

​
Exemple de code d’erreur JSON

Requête :
POST '/11/measurement/conversions/o6dkt' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event_id":"o6dkt", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}]}]}' --header 'Content-Type: application/json

​
Message d’erreur :

{"errors":[{"code":"INVALID_PARAMETER","message":"event_id (o6dkt) n’est pas un Single Event Tag (SET)","parameter":"event_id"}],"request":{"params":{"account_id":"18ce552mlaq"}}}

​
Requête :

twurl_ads -X POST '/11/measurement/conversions/o6dkt' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event_id":"o6dl3", "identifiers": [{"twclid": ""}]}]}' --header 'Content-Type: application/json'

​
Message d’erreur :

{"errors":[{"code":"INVALID_PARAMETER","message":"Au moins un identifiant d’utilisateur doit être fourni","parameter":""}],"request":{"params":{"account_id":"18ce552mlaq"}}}

​
Requête :

twurl_ads -X POST '/11/measurement/conversions/o6dkt' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event_id":"o6dl3", "identifiers": [{"hashed_email": "abc"}]}]}' --header 'Content-Type: application/json'

​
Message d’erreur :

{"errors":[{"code":"INVALID_PARAMETER","message":"hashed_email (abc) n’est pas un hash SHA-256 valide","parameter":"hashed_email"}],"request":{"params":{"account_id":"18ce552mlaq"}}}

​
Requête :

twurl_ads -X POST '/11/measurement/conversions/o6dkt' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603", "event_id":"o6dl3", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}]}]}' --header 'Content-Type: application/json'

​
Message d’erreur :

{"errors":[{"code":"INVALID_PARAMETER","message":"Heure attendue au format yyyy-MM-ddTHH:mm:ss.SSSZ, valeur reçue \"2022-06-16T01:14:00.603\" pour conversion_time","parameter":"conversion_time"}],"request":{"params":{"account_id":"18ce552mlaq"}}}

​
401 Non autorisé

Raison : Identifiants d’authentification manquants ou incorrects Solution : Suivez les étapes d’authentification dans la documentation de configuration en utilisant l’une des 3 méthodes d’authentification : Les Access Tokens utilisateur pour des comptes autres que celui qui possède l’application X Ads API doivent être générés au moyen d’un flux OAuth à 3 étapes. Les options pour générer l’Access Token avec un flux OAuth à 3 étapes incluent : Tout access token utilisateur utilisé avec la Conversion API doit appartenir à des utilisateurs ayant un niveau d’accès AD_MANAGER ou ACCOUNT_ADMIN*, ce qui peut être vérifié via l’endpoint authenticated_user_access.

​
403 Accès interdit 

RaisonTypeMessage d’erreur
Le compte développeur que vous utilisez n’a pas accès à X Ads API. Demandez l’accès ici.403 Client non autoriséL’application cliente avec l’id <> qui effectue cette requête n’a pas accès à X Ads API. Assurez-vous que votre application dispose de l’accès advertiser-api. Utilisez ‘twurl accounts’ et ‘twurl set default <username> <key>’ pour changer l’application utilisée.

​
404 Introuvable 

RaisonTypeMessage d’erreur
L’URL ou les paramètres de la requête ne correspondent pas à l’endpoint404 Route introuvableLa ressource demandée est introuvable
Vous n’avez pas accès au compte propriétaire du pixel_id/Universal website tag404 IntrouvableUser <user_id> does not have access to account <account_id>. Type ‘sn <user_id>’ to get the handle of the user. Use ‘twurl accounts’ and ‘twurl set default \u003Cusername\u003E’ to change the user you’re using.
L’id de l’événement n’appartient pas au compte fourni associé à l’ID de pixel (UWT ID)404 Introuvableevent_id <event_id> does not belong to provided account

​
Exemple de code d’erreur JSON

​
Requête :

twurl_ads -X POST '/11/measurement/conversions/o8z6j' --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event_id":"abc", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}]}]}' --header 'Content-Type: application/json' Message d’erreur : {"errors":[{"code":"NOT_FOUND","message":"event_id (abc) does not belong to provided account","parameter":"event_id"},{"code":"INVALID_PARAMETER","message":"event_id (abc) is not a single event tag (SET)","parameter":"event_id"}],"request":{"params":{"account_id":"18ce55gze09"}}}

​
Index de référence de l’API

Pour consulter la référence complète de l’API, sélectionnez un endpoint dans la liste :

​
Conversions sur le Web

API de conversionsmeasurement/conversions/:pixel_id
Balise d’événement webaccounts/:account_id/web_event_tags

​
Conversions Web

POST version/measurement/conversions/:pixel_id Envoyez des événements de conversion sur site pour un seul ID de balise d’événement. Le code de réponse doit être vérifié pour confirmer la réussite (HTTP 200 OK). Il est recommandé de mettre en place un mécanisme de nouvelle tentative et une journalisation de base au cas où des codes d’erreur seraient renvoyés. La limite de taux est de 100 000 requêtes par intervalle de 15 minutes et par compte (chaque requête autorise 500 événements).
URL de ressource
https://ads-api.x.com/12/measurement/conversions/:pixel_id
Paramètres d’URL de la requête
NomDescription
pixel_id
requis		L’ID de Base Tag d’un compte publicitaire. Il s’agit de la valeur encodée en base36 de l’ID de Base Tag du compte publicitaire.

Type : string

Exemple : o8z6j
conversions
requis		L’objet dans le corps de la requête API (méthode POST). Liste des événements de conversion. Jusqu’à 500 événements de conversion peuvent être fournis. Voir le tableau ci-dessous pour les fields pris en charge.

Type : array

Exemple : "conversions":[{"conversion_time": "2022-02-18T01:14:00.603Z", "event_id":"o87ne", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}], "conversion_id": "23294827"}]
objet conversions
NomDescription
conversion_time
obligatoire		L’horodatage, exprimé au format ISO 8601.

Type : string

Exemple : 2017-10-05T00:00:00Z
event_id
obligatoire		L’ID en base 36 d’un événement spécifique. Il correspond à un événement préconfiguré associé à ce compte publicitaire. Cet identifiant est appelé ID dans l’événement correspondant dans Events Manager.

Type : string

Exemple : o87ne ou tw-o8z6j-o87ne (tw-pixel_id-event-id), tous deux acceptés
identifiers
obligatoire		Une liste d’objets identifiants permettant d’associer l’événement de conversion. Les fields pris en charge sont listés dans un tableau ci-dessous. Au moins un objet identifiant est requis.

Si vous utilisez une adresse IP ou un user agent, un second identifiant doit être envoyé pour un appariement de conversion correct.

Type : array

Exemple : "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"},{"hashed_email": "e586883b2b4faf78d48300a79e0e15138d664cdf796ffb86e533170a9893eda8"}]
number_items
optionnel		Le nombre d’articles achetés lors de l’événement. Doit être un nombre positif supérieur à zéro.

Type : integer

Exemple : 4
price_currency
optionnel		La devise des articles achetés lors de l’événement, exprimée en ISO-4217. Voir Currency pour plus d’informations.

Type : string

Par défaut : USD

Exemple : JPY
value
optionnel		La valeur des articles achetés lors de l’événement, exprimée dans la devise price_currency.

Type : double

Exemple : 100.00
conversion_id
optionnel		Pour la déduplication entre les conversions Pixel et Conversion API. Identifiant d’un événement de conversion pouvant être utilisé pour la déduplication entre les conversions Web Pixel et Conversion API dans la même balise d’événement. Voir la section Testing Events and Deduplication du Conversions Guide pour plus d’informations.

Type : string

Exemple : 23294827
description
optionnel		Description avec toute information supplémentaire sur les conversions.

Type : string

Exemple : test conversion
contents
optionnel		Liste de détails relatifs à un produit/contenu spécifique afin de fournir des informations plus granulaires. Voir le tableau ci-dessous pour les fields pris en charge.

Type : array

Exemple : "contents": [{"content_id": "1", "content_name": "Blankets", "content_type": "home improvement", "content_price": 100.99, "num_items": 1, "content_group_id": "123"}, {"content_id": "2"}]
objet identifiers
NameDescription
twclid
parfois requis		Identifiant de clic extrait de l’URL de redirection après clic. Il est requis si aucun autre identifiant n’est fourni.

Type : string

Exemple : 26l6412g5p4iyj65a2oic2ayg2
hashed_email
parfois requis		Adresse e‑mail hachée avec SHA256. Le texte doit être en minuscules et les espaces en début ou fin supprimés avant le hachage. Requis si aucun autre identifiant n’est fourni.

Type : string

Exemple : pour test-email@test.com = e586883b2b4faf78d48300a79e0e15138d664cdf796ffb86e533170a9893eda8
hashed_phone_number
parfois requis		Numéro de téléphone au format E164 et haché avec SHA256. Le numéro doit être au format E164 avant le hachage. Requis si aucun autre identifiant n’est fourni.

Type : string

Exemple : pour +11234567890 = 1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231
ip_address
parfois requis		Valeur en notation décimale pointée, avec quatre nombres séparés par des points.

L’adresse IP doit être transmise conjointement avec un autre identifiant (twclid, adresse e‑mail, numéro de téléphone ou agent utilisateur).

Type : string

Exemple : 8.25.197.25
user_agent
parfois requis		Cet identifiant permet au serveur de déterminer l’application, le système d’exploitation, le fournisseur et/ou la version de l’agent utilisateur à l’origine de la requête.

L’agent utilisateur doit être transmis conjointement avec un autre identifiant (twclid, adresse e‑mail, numéro de téléphone ou adresse IP).

Type : string

Exemple : Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36.
objet contents
NameDescription
content_id
optional		SKU ou GTIN ; identifiant représentant le contenu.

Type : string

Exemple : jhp
content_group_id
optional		ID associé à un groupe de variantes de produit

Type : integer

Exemple : group 1
content_name
optional		Nom du produit ou du service.

Type : string

Exemple : radio flyer
content_price
optional		Prix du produit ou du service.

Type : double

Exemple : 5.00
content_type
optional		Catégorie du produit acheté.

Type : string

Exemple : clothes
num_items
optional		Nombre de produits achetés

Type : integer

Exemple : 1
Paramètres de réponse
NomDescription
conversions_processedNombre de conversions traitées avec succès

Type : integer

Exemple : 1
debug_idUUID de débogage pouvant être utilisé pour des analyses ultérieures

Type : string

Exemple : ff02e052-36e4-47d6-bdf0-6d8986446562
Exemple de requête
    twurl -H 'ads-api.x.com' -X POST '/12/measurement/conversions/oka17' --data '
    {
      "conversions":[
         {
            "conversion_time":"2022-02-18T01:14:00.603Z",
            "event_id":"ol288",
            "identifiers":[
               {
                  "twclid":"23opevjt88psuo13lu8d020qkn"
               },
               {
                  "hashed_email":"d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62"
               },
               {
                  "hashed_phone_number":"1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231"
               },
               {
                  "ip_address":"1.0.0.0",
                  "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36"
               }
            ],
            "value":"20.00",
            "number_items":3,
            "conversion_id":"23294827",
            "description":"Achats de fournitures pour animaux de compagnie",
            "contents":[
               {
                  "content_id":"1",
                  "content_name":"Couvertures",
                  "content_type":"Fournitures pour animaux de compagnie",
                  "content_price":100.99,
                  "num_items":1,
                  "content_group_id":"123"
               }
            ]
         }
      ]
    }' --header 'Content-Type: application/json'
Exemple de requête
    {
       "request":{
          "params":{
             "account_id":"18ce552mlaq"
          }
       },
       "data":{
          "conversions_processed":1,
          "debug_id":"ff02e052-36e4-47d6-bdf0-6d8986446562"
       }
    }

​
Balises d’événement web

GET accounts/:account_id/web_event_tags Récupère les détails de certaines ou de l’ensemble des balises d’événement web associées au compte actuel.

​
URL de ressource

https://ads-api.x.com/12/accounts/:account_id/web_event_tags

​
Paramètres

NomDescription
account_id
obligatoire		L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Ads, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié.

Type : string

Exemple : 18ce54d4x5t
count
facultatif		Spécifie le nombre d’enregistrements à tenter de récupérer par requête distincte.

Type : int

Valeur par défaut : 200
Min, Max : 1, 1000
cursor
facultatif		Spécifie un curseur pour obtenir la page suivante de résultats. Voir Pagination pour plus d’informations.

Type : string

Exemple : 8x7v00oow
sort_by
facultatif		Trie selon un attribut pris en charge, par ordre croissant ou décroissant. Voir Sorting pour plus d’informations.

Type : string

Exemple : created_at-asc
web_event_tag_ids
facultatif		Limite la réponse aux balises d’événements web souhaitées en spécifiant une liste d’identifiants séparés par des virgules. Jusqu’à 200 id peuvent être fournis.

Type : string

Exemple : o3bk1
with_deleted
facultatif		Inclure les résultats supprimés dans la requête.

Type : boolean

Valeur par défaut : false
Valeurs possibles : true, false
with_total_count
facultatif		Inclure l’attribut de réponse total_count.

Remarque : Ce paramètre et cursor sont exclusifs.

Remarque : Les requêtes qui incluent total_count auront des limites de taux plus faibles, actuellement fixées à 200 par 15 minutes.

Type : boolean

Valeur par défaut : false
Valeurs possibles : true, false

​
Exemple de requête

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags?web_event_tag_ids=o3bk1

​
Exemple de réponse

    {
      "request": {
        "params": {
          "web_event_tag_ids": [
            "o3bk1"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "name": "balise d'événement web",
          "view_through_window": 7,
          "click_window": 7,
          "embed_code": "<script src="//platform.x.com/oct.js" type="text/javascript"></script><script type="text/javascript">twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img height="1" width="1" style="display:none;" alt=""  src="https://analytics.x.com/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0" /><img height="1" width="1" style="display:none;" alt=""  src="//t.co/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0" /></noscript>",
          "id": "o3bk1",
          "retargeting_enabled": false,
          "last_tracked_at": "2021-05-22T17:00:04Z",
          "status": "TRACKING",
          "type": "DOWNLOAD",
          "website_tag_id": "ny3od",
          "deleted": false
        }
      ]
    }

​
GET accounts/:account_id/web_event_tags/:web_event_tag_id

Récupère une balise d’événement web spécifique associée au compte actuel.
URL de ressource
https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_id
Paramètres
NomDescription
account_id
obligatoire		L’identifiant du compte utilisé. Il apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API des annonceurs, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié.

Type : string

Exemple : 18ce54d4x5t
web_event_tag_id
obligatoire		Référence à la balise d’événement web utilisée dans la requête.

Type : string

Exemple : o3bk1
with_deleted
optionnel		Inclure les éléments supprimés dans la réponse.

Type : boolean

Valeur par défaut : false
Valeurs possibles : true, false
Exemple de requête
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags/o3bk1
Exemple de réponse
    {
      "request": {
        "params": {
          "web_event_tag_id": "o3bk1",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "balise d'événement web",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src="//platform.x.com/oct.js" type="text/javascript"></script><script type="text/javascript">twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img height="1" width="1" style="display:none;" alt=""  src="https://analytics.x.com/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0" /><img height="1" width="1" style="display:none;" alt=""  src="//t.co/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0" /></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": "2021-05-22T17:00:04Z",
        "status": "TRACKING",
        "type": "DOWNLOAD",
        "website_tag_id": "ny3od",
        "deleted": false
      }
    }

​
POST accounts/:account_id/web_event_tags

Créer une nouvelle balise d’événement web associée au compte en cours.

​
URL de ressource

https://ads-api.x.com/12/accounts/:account_id/web_event_tags

​
Paramètres

NomDescription
account_id
obligatoire		L’identifiant du compte exploité. Figure dans le chemin de la ressource et constitue généralement un paramètre obligatoire pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte indiqué doit être associé à l’utilisateur authentifié.

Type : string

Exemple : 18ce54d4x5t
click_window
obligatoire		La fenêtre de clic pour cette balise web.

Remarque : seules les valeurs possibles listées ci‑dessous sont acceptées.

Type : int

Valeurs possibles : 1, 7, 14, 30
name
obligatoire		Le nom de la balise web.

Type : string

Exemple : Sample single conversion event
retargeting_enabled
obligatoire		Indique si le reciblage doit être activé pour cette balise web.

Type : boolean

Valeurs possibles : true, false
type
obligatoire		Le type de balise web.

Type : enum

Valeurs possibles : ADDED_PAYMENT_INFO, ADD_TO_CART, ADD_TO_WISHLIST, CHECKOUT_INITIATED, CONTENT_VIEW, CUSTOM, DOWNLOAD, PRODUCT_CUSTOMIZATION, PURCHASE, SEARCH, SIGN_UP, SITE_VISIT, START_TRIAL, SUBSCRIBE

(Dans l’interface, SITE_VISIT apparaît comme “Page view” et SIGN_UP comme “Lead”.)
view_through_window
obligatoire		La fenêtre d’attribution post‑impression pour cette balise web. Cette valeur doit toujours être inférieure ou égale à la valeur de click_window.

Remarque : seules les valeurs possibles listées ci‑dessous sont acceptées.

Type : int

Valeurs possibles : 0, 1, 7, 14, 30
Exemple de requête
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags?click_window=7&name=web event tag&retargeting_enabled=false&type=SITE_VISIT&view_through_window=7

​
Exemple de réponse

    {
      "data": {
        "name": "balise d'événement web",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src='"//platform.x.com/oct.js"' type='"text/javascript"'></script><script type='"text/javascript"'>twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img alt='""' height='"1"' src='"https://analytics.x.com/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/><img alt='""' height='"1"' src='"//t.co/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": null,
        "status": "UNVERIFIED",
        "type": "SITE_VISIT",
        "website_tag_id": "ny3od",
        "deleted": false
      },
      "request": {
        "params": {
          "name": "balise d'événement web",
          "view_through_window": 7,
          "click_window": 7,
          "retargeting_enabled": false,
          "account_id": "18ce54d4x5t",
          "type": "SITE_VISIT"
        }
      }
    }

​
PUT accounts/:account_id/web_event_tags/:web_event_tag_id

Met à jour une balise d’événement web associée au compte en cours.
URL de ressource
https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_id

​
Paramètres

NomDescription
account_id
requis		L’identifiant du compte exploité. Apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’Advertiser API, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié.

Type : string

Exemple : 18ce54d4x5t
web_event_tag_id
requis		L’identifiant d’une balise web sur le compte actuel.

Type : string

Exemple : o3bk1
click_window
optionnel		La fenêtre d’attribution au clic pour cette balise web.

Remarque : Seules les valeurs possibles listées ci‑dessous sont acceptées.

Type : int

Valeurs possibles : 1, 7, 14, 30
name
optionnel		Le nom de la balise web.

Type : string

Exemple : Sample single conversion event
retargeting_enabled
optionnel		Indique si le reciblage doit être activé pour cette balise web.

Type : boolean

Valeurs possibles : true, false
type
optionnel		Le type de balise web.

Type : enum

Valeurs possibles : ADDED_PAYMENT_INFO, ADD_TO_CART, ADD_TO_WISHLIST, CHECKOUT_INITIATED, CONTENT_VIEW, CUSTOM, DOWNLOAD, PRODUCT_CUSTOMIZATION, PURCHASE, SEARCH, SIGN_UP, SITE_VISIT, START_TRIAL, SUBSCRIBE

(Dans l’interface, SITE_VISIT apparaît comme “Page view” et SIGN_UP comme “Lead”.)
view_through_window
optionnel		La fenêtre d’attribution post‑impression pour cette balise web. Cette valeur doit toujours être inférieure ou égale à la valeur de click_window.

Remarque : Seules les valeurs possibles listées ci‑dessous sont acceptées.

Type : int

Valeurs possibles : 0, 1, 7, 14, 30

​
Exemple de requête

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags/o3bk1?type=DOWNLOAD

​
Exemple de réponse

    {
      "data": {
        "name": "balise d'événement web",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src='"//platform.x.com/oct.js"' type='"text/javascript"'></script><script type='"text/javascript"'>twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img alt='""' height='"1"' src='"https://analytics.x.com/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/><img alt='""' height='"1"' src='"//t.co/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": "2021-05-22T17:00:04Z",
        "status": "UNVERIFIED",
        "type": "DOWNLOAD",
        "website_tag_id": "ny3od",
        "deleted": false
      },
      "request": {
        "params": {
          "web_event_tag_id": "o3bk1",
          "type": "DOWNLOAD",
          "account_id": "18ce54d4x5t"
        }
      }
    }

​
DELETE accounts/:account_id/web_event_tags/:web_event_tag_id

Supprime une balise d’événement web spécifique associée au compte en cours.

​
URL de ressource

https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_id
Paramètres
NomDescription
account_id
obligatoire		L’identifiant du compte exploité. Figure dans le chemin de la ressource et est généralement un paramètre obligatoire pour toutes les requêtes de l’API Ads, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié.

Type : string

Exemple : 18ce54d4x5t
web_event_tag_id
obligatoire		L’identifiant d’une balise web sur le compte actuel.

Type : string

Exemple : o3bk1
Exemple de requête
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags/o3bk1
Exemple de réponse
    {
      "data": {
        "name": "balise d'événement web",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src='"//platform.x.com/oct.js"' type='"text/javascript"'></script><script type='"text/javascript"'>twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img alt='""' height='"1"' src='"https://analytics.x.com/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/><img alt='""' height='"1"' src='"//t.co/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": "2021-05-22T17:00:04Z",
        "status": "UNVERIFIED",
        "type": "DOWNLOAD",
        "website_tag_id": "ny3od",
        "deleted": true
      },
      "request": {
        "params": {
          "web_event_tag_id": "o3bk1",
          "account_id": "18ce54d4x5t"
        }
      }
    }
⌘I