Passer au contenu principal

​
Mise en place de l’API de conversion

​
Prérequis

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

Étape 1 : compte développeur
  • Lors de votre demande de compte développeur, souscrivez à l’un de nos plans d’abonnement pour une approbation immédiate. 
  • Remarque : À titre de 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 développeur, il n’existe aucun moyen de transférer ces identifiants, le cas échéant. Il est préférable de l’associer à un compte d’entreprise pour une gestion continue et d’utiliser la connexion multi-utilisateur, selon les besoins. Sinon, au minimum, le compte doit être configuré avec des paramètres personnalisés (image d’en-tête, avatar, bio et URL de la bio) et utiliser l’authentification à deux facteurs.
Étape 2 : demande d’accès à l’Ads API
  • Assurez-vous de disposer du bon App ID pour votre demande d’accès à l’Ads API. L’App ID se trouve dans la Console de développement, sous Projects & Apps. Exemple : 16489123
  • Demandez l’accès à l’Ads API en contactant votre représentant X.

​
Accès à l’Ads API - Applications existantes

  • Si vous disposez déjà d’une application Ads API déjà utilisée activement, vous pouvez réutiliser cette application ainsi que les jetons d’accès existants pour la Conversion API.

​
Jetons d’accès

  • Les jetons d’accès utilisateur pour le handle utilisateur qui possède l’App Ads API peuvent être générés et récupérés directement à partir de la Console de développement. On parle de « jeton d’accès personnel » car il est destiné à être utilisé pour votre propre handle X. Des informations générales sur l’authentification et la Console de développement sont disponibles ici.
  • Les jetons d’accès utilisateur pour des handles autres que celui possédant l’App Ads API doivent être générés avec un flux OAuth à 3 étapes. Les options pour générer le jeton d’accès avec OAuth à 3 étapes incluent :
  • Tous les jetons d’accès utilisateur utilisés avec la Conversion API doivent appartenir à des utilisateurs ayant un niveau d’accès AD_MANAGER ou ACCOUNT_ADMIN, ce qui peut être vérifié via le point de terminaison 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 n’ayant pas le niveau d’accès AD_MANAGER ou ACCOUNT_ADMIN pour être utilisés.

​
É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 pixel X. Si vous souhaitez effectuer une déduplication entre les événements du pixel et ceux de la 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 existant que vous utilisez déjà avec le pixel X, vous pouvez le faire et devrez récupérer l’ID de l’événement à partir de cet événement. Si vous utilisez à la fois le pixel et 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 (en tant que conversion_id) afin d’éliminer les doublons d’événements entre le pixel et Conversion API pour ce même événement. Voir la section d. « Test des événements et déduplication » pour plus d’informations. 
Option 2 : création d’un nouvel événement de conversion dans Ads Manager :
Il est important de disposer d’une source d’événement créée dans Events Manager avant de créer un événement. Pour vérifier si vous avez une source d’événement (X Pixel) ajoutée à votre compte, allez 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énement, suivez 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 ajouter une source d’événement si vous n’avez pas encore de source d’événement X Pixel dans votre barre latérale gauche
    1. L’ID de la source d’événement X Pixel est votre Pixel ID
Vous avez maintenant une source d’événement et un Pixel ID. Vous devez créer un événement à l’intérieur de cette source d’événement pour les événements de conversion que vous souhaitez suivre :
  1. Dans la source d’événement 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 à être utilisé

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

Vous devez actuellement transmettre au moins un identifiant, par exemple Click ID (twclid), adresse e‑mail ou numéro de téléphone. Si vous utilisez l’adresse IP ou le user agent, un deuxième identifiant doit être envoyé pour assurer une correspondance correcte des conversions. Transmettre davantage d’identifiants permettra d’obtenir un taux de correspondance des conversions plus élevé.
Champ de correspondance clientFormatHachage requis ?
X Click IDGénéré par X (en savoir plus)Non
Adresse e‑mailSupprimez les espaces au début et à la finObligatoire (SHA256)
Numéro de téléphoneStandard E164Obligatoire (SHA256)
Adresse IPSupprimez les espaces au début et à la finNon
User agentSupprimez les espaces au début et à la finNon

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

Il est recommandé d’inclure systématiquement le Click ID dans chaque requête de conversion. Le Click ID doit être extrait du paramètre de chaîne de requête twclid lorsqu’il est disponible, après que l’utilisateur a accédé au site web de destination.  Exemple de code JavaScript simple : 
var queryString = document.location.search;
if (queryString.has('twclid') {
  twitterClickID = getParam(queryString, 'twclid');
  // Étapes suivantes recommandées : journalisation, insertion dans le stockage local
}
Il est recommandé de : 
  1. Toujours analyser la valeur twclid lorsqu’elle est présente dans les paramètres de requête de l’URL.
  2. Stocker les données avec les champs de formulaire pertinents ou les informations relatives à l’événement de conversion.
Associer le Click ID (identifiant de clic) aux événements de conversion et aux informations de workflow permet des scénarios tels que le traitement par lots, l’utilisation d’algorithmes pour analyser et créer des événements de conversion à partir de plusieurs 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 URL et est censée représenter la page web qui a déclenché l’événement.

​
2. Préparer l’identifiant d’e-mail

Les champs de mise en correspondance client pris en charge peuvent être envoyés, mais doivent être normalisés et, lorsque cela est requis, hachés pour protéger la confidentialité. Les informations doivent être hachées avec SHA-256, sans sel.  Par exemple, pour l’adresse e-mail test@x.com, elle doit être envoyée au format haché : 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 informations doivent être hachées à l’aide de SHA-256, sans sel.  Par exemple, pour un numéro de téléphone américain : +11234567890, il doit nous être envoyé sous forme hachée : 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 user agent). Aucun hachage n’est requis pour cet identifiant. Cette valeur est écrite 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 hachage n’est nécessaire pour cet identifiant. Cet identifiant permet au serveur de reconnaître l’application, le système d’exploitation, le fournisseur et/ou la version du User Agent à 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é. 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 réessai et une journalisation simple au cas où des codes d’erreur seraient renvoyés. Pour des informations détaillées sur l’URL du point de terminaison 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 (formaté 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",
            "contents":[
               {
                  "content_id":"1",
                  "content_name":"Blankets",
                  "content_type":"Pet supplies",
                  "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 débit

La limite de débit sera de 60 000 événements par compte, par intervalle de 15 minutes. Notez que le code de votre serveur peut être amené à implémenter une logique en dehors de cet appel, notamment :
  1. Instrumenter les actions des utilisateurs (journalisation) afin de pouvoir 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 qui ont 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

Une fois que votre événement a commencé à recevoir des conversions, dans un délai de 12 à 24 heures, le statut de la « Single event web tag » doit afficher TRACKING sur la page Conversion Tracking d’Ads Manager. L’envoi de conversions via la Conversion API n’aura aucun impact sur les campagnes en cours. Vous pouvez également consulter les résultats d’analyse de votre événement de conversion par ID de balise en :

​
Déduplication entre Pixel et Conversion API

Si vous souhaitez dédupliquer les conversions entre les requêtes Pixel et Conversion API, le champ conversion_id sert de clé de déduplication. La déduplication a uniquement lieu 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 un délai de 48 heures.

​
Suivi des conversions (Vue d’ensemble)

​
Résumé

Le suivi des conversions vous permet de mesurer le nombre d’utilisateurs de X qui effectuent une action souhaitée après avoir vu et interagi avec vos publicités sur X. Il vous donne la possibilité de mesurer quelles campagnes génèrent des actions telles que des visites de site web, des inscriptions et des achats. Cela fournit aux annonceurs des capacités de mesure en dehors de X pour comprendre la performance de leurs publicités à réponse directe, afin qu’ils puissent acquérir des clients de manière rentable. En utilisant une balise de conversion, les annonceurs peuvent suivre les conversions des utilisateurs et les relier à des campagnes publicitaires sur X. Cela leur donne la visibilité nécessaire pour optimiser leurs campagnes afin d’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 de l’action ou des actions qu’il souhaite générer avec sa campagne publicitaire :
  • Visite de site : l’utilisateur visite une page de destination 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, comme un livre blanc ou un package 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é : 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 vue complète de l’attribution des conversions. Comparée aux systèmes de mesure tiers que les clients pouvaient utiliser à la place de la fonctionnalité de suivi des conversions propre à X, tels que des URL de clic uniques associées à des balises de suivi tierces, la balise de conversion de X permet à l’annonceur de suivre les conversions attribuées aux interactions de milieu et de haut de l’entonnoir de conversion, comme les développements de Tweets, les Retweets, les favoris, les réponses et les abonnements, ainsi que les impressions.

​
FAQ

Tout d’abord, un annonceur crée une balise de conversion, qui est un extrait de code fourni par X, et la place sur 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 conduit vers le site web de l’annonceur et vers 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, la balise reconnaît que l’utilisateur a déjà interagi avec une publicité X. La balise se « déclenche » alors, c’est‑à‑dire qu’elle envoie une notification aux serveurs de X afin que la conversion puisse être attribuée à la publicité qui a généré la conversion.
Non, notre produit n’est pas conçu pour associer des balises de conversion spécifiques à des campagnes spécifiques. Une fois qu’une balise est configurée, le système suit automatiquement quelles publicités ont généré des conversions sur une balise donnée.
Fenêtre d’attribution par défaut post‑vue : 1 jourAttribution par défaut post‑engagement : 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 de fenêtres d’attribution post‑engagement sont 1, 7, 14, 30, 60 et 90 jours. Les options de 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 de chaque client soient différents, voici quelques idées qui ont fonctionné pour des clients ayant participé aux programmes alpha ou bêta de suivi des conversions :Création :
  • Offres : Associer une remise, une promotion ou une offre de livraison gratuite au Tweet sponsorisé pour susciter davantage d’intérêt pour l’action
  • Jeux‑concours et concours : En particulier pour les marques bien connues, les jeux‑concours et concours ont généré des conversions
  • Expérimentation sur le texte du Tweet : Tester les majuscules par rapport aux minuscules (FREE vs free ou NOW vs now)
  • Dates limites : Proposer une date limite pour encourager les personnes à agir immédiatement (Offre valable jusqu’au 12 décembre !)
  • Ajout de photos percutantes : Il est utile de tester si des photos visuellement percutantes ajoutées à la création du Tweet sont efficaces pour générer des conversions ; les résultats peuvent varier ou être propres à l’offre du client.
Ciblage :
  • Ciblage par @handle et par catégorie d’intérêt : Un alignement étroit entre le texte du Tweet et les @handles et le public visé par le Tweet a généré des conversions
  • Utilisation de mots‑clés de niche mais à fort volume : Dans le domaine des concerts, l’utilisation de mots‑clés liés à l’artiste/musicien (par exemple son nom) s’est révélée efficace.
  • Audiences personnalisées : Les clients utilisant TA web et le suivi des conversions ensemble ont obtenu des CPA plus bas que les groupes de contrôle utilisant d’autres ciblages
Plus votre segmentation de campagne est fine, plus les résultats de conversion que vous rapportez seront exploitables. Par exemple, il est beaucoup plus facile d’optimiser une campagne avec 4 mots‑clés qu’une campagne avec 50.

​
Dépannage et assistance pour l’API Conversion

Pour toute question concernant les codes d’erreur suite à l’appel de l’API, veuillez consulter la section ci‑dessous. Pour toutes les autres questions, n’hésitez pas à contacter votre représentant Twitter et nous ferons le nécessaire pour les résoudre dans les meilleurs délais. 

​
Gestion des erreurs et explications

Une requête n’est considérée comme réussie que si aucune des conversions qu’elle contient ne comporte d’erreur. Si une conversion donnée comporte une erreur, le point de terminaison renverra la liste de toutes les erreurs applicables.

​
Vue d’ensemble des codes d’erreur de l’API X Ads

Voici une liste exhaustive des codes d’erreur de l’API X Ads : https://developer.x.com/en/docs/twitter-ads-api/response-codes Les réponses réussies de 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’il y a un code HTTP de type 500, cela est lié à un problème côté serveur plutôt qu’à votre requête ou à la configuration de votre compte. Veuillez consulter la X API status page ou le developer community forum pour vérifier si d’autres rencontrent des problèmes similaires.

​
Lorsqu’il y a un code HTTP de la série 400, les cas les plus courants 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 cet endpoint)

​
Codes d’erreur de l’API Conversion

​
Scénarios d’erreur 400 Bad Request

ReasonTypeError Message
Erreur d’identifiant manquant (actuellement e-mail haché ou ID de clic X - twclid)400 Bad RequestAu moins un identifiant utilisateur doit être fourni
E-mail haché non valide400 Bad RequestHashed_email n’est pas un hachage 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 d’événements de conversion est de 500
ID d’événement manquant400 Bad RequestL’ID d’événement est 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) is not a 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":"At least one user identifier must be provided","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) is not a valid SHA-256 hash","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":"Expected Time in yyyy-MM-ddTHH:mm:ss.SSSZ, got \"2022-06-16T01:14:00.603\" for conversion_time","parameter":"conversion_time"}],"request":{"params":{"account_id":"18ce552mlaq"}}}

​
401 Non autorisé

Raison : informations d’authentification manquantes ou incorrectes  Solution : suivez les étapes d’authentification dans la documentation de configuration en utilisant l’une des 3 méthodes d’authentification : Les User Access Tokens pour des handles autres que le handle propriétaire de l’App Ads API doivent être générés avec un flux OAuth à 3 volets (3-legged OAuth). Les options pour générer un Access Token avec un OAuth à 3 volets incluent : Tous les jetons utilisateur utilisés avec la Conversion API doivent être associés à des utilisateurs disposant d’un niveau d’accès AD_MANAGER ou ACCOUNT_ADMIN*, 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 à l’API X Ads. Faites une demande d’accès ici.403 Client non autoriséL’application cliente ayant l’id <> qui effectue cette requête n’a pas accès à l’API X Ads. Assurez-vous que votre application dispose de l’accès advertiser-api. Utilisez twurl accounts et twurl set default \<username> \<key> pour modifier l’application que vous utilisez.

​
404 Not Found

RaisonTypeMessage d’erreur
L’URL ou les paramètres de la requête ne sont pas corrects pour le endpoint404 Route Not FoundLa ressource demandée est introuvable
Vous n’avez pas accès au compte qui possède le pixel_id/balise de site web universelle404 Not FoundUser <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’identifiant d’événement n’appartient pas au compte fourni associé à l’ID de pixel (ID UWT)404 Not Foundevent_id <event_id> n’appartient pas au compte fourni

​
Exemple de code d’erreur au format 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 la 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 Web

Conversion APImeasurement/conversions/:pixel_id
Balise d’événement Webaccounts/:account_id/web_event_tags

​
Conversions web

POST version/measurement/conversions/:pixel_id Envoyer des événements de conversion de site web 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 réessai et une journalisation minimale au cas où des codes d’erreur seraient renvoyés. La limite de débit est de 100 000 requêtes par intervalle de 15 minutes et par compte (chaque requête peut contenir jusqu’à 500 événements).
URL de la ressource
https://ads-api.x.com/12/measurement/conversions/:pixel_id
Paramètres d’URL de requête
NomDescription
pixel_id
required		L’ID de balise de base pour un compte publicitaire. Il s’agit de la valeur encodée en base36 de l’ID de balise de base d’un compte publicitaire.

Type : string

Exemple : o8z6j
conversions
required		L’objet inclus dans le corps de la requête POST de l’API. Liste d’événements de conversion. Jusqu’à 500 événements de conversion peuvent être fournis. Voir le tableau ci‑dessous pour les champs 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
NameDescription
conversion_time
required		L’heure, exprimée au format ISO 8601.

Type : string

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

Type : string

Exemple : o87ne ou tw-o8z6j-o87ne (tw-pixel_id-event-id) sont tous les deux acceptés
identifiers
required		Une liste d’objets identifiants permettant de faire correspondre l’événement de conversion. Les champs pris en charge sont listés dans un tableau ci‑dessous. Au moins un des objets identifiants est requis.

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

Type : array

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

Type : integer

Exemple : 4
price_currency
optional		La devise des articles achetés dans l’événement, exprimée au format ISO-4217. Voir Currency pour plus d’informations.

Type : string

Valeur par défaut : USD

Exemple : JPY
value
optional		Le montant des articles achetés dans l’événement, exprimé dans la devise price_currency.

Type : double

Exemple : 100.00
conversion_id
optional		Pour la déduplication entre les conversions Pixel et celles de l’API de conversion. Un identifiant pour un événement de conversion qui peut ê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
optional		Description contenant toute information complémentaire sur les conversions.

Type : string

Exemple : test conversion
contents
optional		Liste de détails relatifs à un produit ou contenu spécifique, afin de fournir des informations détaillées. Voir le tableau ci‑dessous pour les champs 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"}]
identifiers object
NameDescription
twclid
sometimes required		ID de clic tel qu’il est extrait à partir de l’URL de redirection post‑clic. Il est requis si aucun autre identifiant n’est ajouté.

Type : string

Exemple : 26l6412g5p4iyj65a2oic2ayg2
hashed_email
sometimes required		Une adresse e‑mail hachée avec SHA256. Le texte doit être en minuscules et il faut supprimer tous les espaces de début ou de fin avant le hachage. Il est requis si aucun autre identifiant n’est ajouté.

Type : string

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

Type : string

Exemple : pour +11234567890 = 1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231 
ip_address
sometimes required		Cette valeur est écrite en notation décimale pointée, avec quatre nombres séparés par des points.

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

Type : string

Exemple : 8.25.197.25
**user_agent **
sometimes required		Cet identifiant permet au serveur d’identifier l’application, le système d’exploitation, le fournisseur et/ou la version de l’user agent effectuant la requête.

L’user agent doit être fourni 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_idUn UUID de débogage qui peut ê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",
            "contents":[
               {
                  "content_id":"1",
                  "content_name":"Blankets",
                  "content_type":"Pet supplies",
                  "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érer les détails de certaines balises d’événement web ou de toutes celles associées au compte actuel.

​
URL de la ressource

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

​
Paramètres

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

Type: string

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

Type: int

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

Type: string

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

Type: string

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

Type: string

Exemple : o3bk1
with_deleted
optionnel		Inclut les résultats supprimés dans votre requête.

Type: boolean

Valeur par défaut : false
Valeurs possibles : true, false
with_total_count
optionnel		Inclut 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 basses, actuellement définies à 200 par tranche de 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": "web event tag",
          "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 en cours.
URL de la ressource
https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_id
Paramètres
NameDescription
account_id
required		L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est généralement un paramètre requis pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié.

Type : string

Exemple : 18ce54d4x5t
web_event_tag_id
required		Une référence à la balise d’événement web que vous utilisez dans la requête.

Type : string

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

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": "web event tag",
        "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ée une nouvelle balise d’événement web associée au compte actuel.

​
URL de la ressource

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

​
Paramètres

NameDescription
account_id
required		L’identifiant du compte utilisé. Apparaît dans le chemin d’accès de la ressource et est généralement un paramètre requis 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
required		La fenêtre de clic pour cette balise Web.

Remarque : seules les valeurs possibles indiquées ci-dessous sont acceptées.

Type : int

Valeurs possibles : 1, 7, 14, 30
name
required		Le nom de la balise Web.

Type : string

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

Type : boolean

Valeurs possibles : true, false
type
required		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 utilisateur, SITE_VISIT est affiché comme « Page view » et SIGN_UP est affiché comme « Lead ».)
view_through_window
required		La fenêtre d’affichage pour cette balise Web. Cette valeur doit toujours être inférieure ou égale à la valeur click_window.

Remarque : seules les valeurs possibles indiqué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": "web event tag",
        "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": "web event tag",
          "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 actuel.
URL de la ressource
https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_id

​
Paramètres

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

Type : string

Exemple : 18ce54d4x5t
web_event_tag_id
required		L’identifiant d’une balise web du compte actuel.

Type : string

Exemple : o3bk1
click_window
optional		La fenêtre de clic pour cette balise web.

Remarque : seules les valeurs possibles répertoriées ci-dessous sont acceptées.

Type : int

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

Type : string

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

Type : boolean

Valeurs possibles : true, false
type
optional		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 utilisateur, SITE_VISIT est affiché comme « Page view » et SIGN_UP est affiché comme « Lead »)
view_through_window
optional		La fenêtre de vue 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 répertorié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": "web event tag",
        "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 la ressource

https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_id
Parameters
NameDescription
account_id
required		L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et est 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
required		L’identifiant d’une balise web pour 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"
        }
      }
    }