Conversions web

​

Mise en place de l’API de conversion

​

Prérequis

​

Accès à l’Ads API - Nouvelles applications

• La principale condition préalable pour utiliser Conversion API est de disposer d’un compte développeur et de l’Ads API Access. Le processus est décrit dans le guide Ads API Getting Started. Veuillez noter les points suivants :

É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 :
  • Ligne de commande avec autorisation via le Web à l’aide de l’utilitaire twurl
  • Ligne de commande avec autorisation basée sur un code PIN
  • Flux web personnalisé implémentant le modèle OAuth à 3 étapes
• 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 client	Format	Hachage requis ?
X Click ID	Généré par X (en savoir plus)	Non
Adresse e‑mail	Supprimez les espaces au début et à la fin	Obligatoire (SHA256)
Numéro de téléphone	Standard E164	Obligatoire (SHA256)

Adresse IP	Supprimez les espaces au début et à la fin	Non
User agent	Supprimez les espaces au début et à la fin	Non

​

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 [e-mail], 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 : [phone], 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 :

• exportant les données depuis Ads Manager (page d’aide Analytics for Website Conversion Tracking) ;

• exportant les données via l’Ads API (segmentation_type=CONVERSION_TAGS). 

​

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

Comment fonctionne la balise de suivi des conversions ?

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.

Existe‑t‑il, dans le processus de configuration de la campagne, un moyen permettant à l’utilisateur de sélectionner quels pixels de suivi sont pertinents pour cette campagne ?

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.

Quels sont nos paramètres de fenêtre d’attribution par défaut pour les balises de conversion ?

Fenêtre d’attribution par défaut post‑vue : 1 jour

Attribution par défaut post‑engagement : 14 jours

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

Quelles sont quelques idées de créations DR efficaces et de stratégies qui favoriseront réellement les conversions ?

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

Reason	Type	Error Message
Erreur d’identifiant manquant (actuellement e-mail haché ou ID de clic X - twclid)	400 Bad Request	Au moins un identifiant utilisateur doit être fourni
E-mail haché non valide	400 Bad Request	Hashed_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 Request	Event_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 Request	La limite du nombre d’événements de conversion est de 500
ID d’événement manquant	400 Bad Request	L’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 :

• Ligne de commande avec autorisation web via l’utilitaire twurl

• Ligne de commande avec autorisation basée sur un code PIN

• Flux web personnalisé implémentant le modèle OAuth à 3 volets

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

Raison	Type	Message 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

Raison	Type	Message d’erreur
L’URL ou les paramètres de la requête ne sont pas corrects pour le endpoint	404 Route Not Found	La ressource demandée est introuvable
Vous n’avez pas accès au compte qui possède le pixel_id/balise de site web universelle	404 Not Found	User <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 Found	event_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 API	measurement/conversions/:pixel_id
Balise d’événement Web	accounts/: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

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

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

Name	Description
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 [e-mail] = 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 [phone] = 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

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

Nom	Description
conversions_processed	Nombre de conversions traitées avec succès Type : integer Exemple : 1
debug_id	Un 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

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

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

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

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

Name	Description
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"
        }
      }
    }