Versions

Pour obtenir les informations les plus récentes sur les versions historiques de la X Ads API, veuillez consulter les informations ci-dessous.

Version	Path	Date d’introduction	Date de dépréciation	Date de fin de vie
12.0	/12/	27 octobre 2022	À déterminer	À déterminer
11.0	/11/	31 mars 2022	À déterminer	À déterminer
10.0	/10/	31 août 2021	31 mars 2022	27 octobre 2022
9.0	/9/	2 mars 2021	31 août 2021	31 mars 2022
8.0	/8/	8 septembre 2020	2 mars 2021	31 août 2021
7.0	/7/	3 mars 2020	1 septembre 2020	2 mars 2021
6.0	/6/	28 août 2019	3 mars 2020	1 septembre 2020
5.0	/5/	28 février 2019	28 août 2019	3 mars 2020
4.0	/4/	28 août 2018	28 février 2019	28 août 2019
3.0	/3/	1 février 2018	28 août 2018	28 février 2019
2.0	/2/	10 juillet 2017	1 février 2018	1 août 2018
1.0	/1/	31 mars 2016	7 juillet 2017	10 janvier 2018
0.0	/0/	21 février 2013	N/A	31 octobre 2016

​

Vue d’ensemble

Chaque mois, nous apportons des modifications et déployons plusieurs nouvelles fonctionnalités sur la X Ads API. Ces changements sont presque toujours rétrocompatibles ; toutefois, nous introduisons généralement quelques changements majeurs chaque année. Nous avons reçu des retours de développeurs sur les difficultés que la cadence rapide des évolutions de la X Ads API impose à leurs cycles de développement pour implémenter de nouvelles fonctionnalités, gérer les dépréciations et tester les modifications. Nous voulons améliorer l’expérience des développeurs avec notre plateforme publicitaire, c’est pourquoi nous avons introduit le concept de versionnage de nos endpoints.

Quelques définitions de concepts dont nous parlons :

Version : Il s’agit du numéro de version présent dans le chemin d’URL de toute requête X Ads API, par exemple : GET //accounts. Ce style de versionnage est connu sous le nom de versionnage URI.

Changements majeurs (Breaking Changes) : Les changements majeurs sont toutes les modifications nécessitant des ressources de développement pour maintenir la fonctionnalité existante. Cela inclut les ressources consacrées à l’analyse des modifications à effectuer, à l’identification des fonctionnalités/endpoints en voie de dépréciation et à la mise en œuvre finale de l’ensemble de ces changements. Une liste de changements majeurs comprend notamment :

• Suppression d’un paramètre de la requête/réponse de l’API

• Modification du nom de paramètres ou d’endpoints

• Changement dans la représentation des valeurs (preview_url → card_uri)

• Changement de comportement des endpoints (p. ex., statistiques asynchrones vs synchrones)

• Ajout/modification de paramètres optionnels ou requis (p. ex., rendre name un champ requis dans la requête)

Dépréciation : Les versions ou produits dépréciés ne seront plus pris en charge et il est recommandé que les développeurs cessent d’utiliser ces API.

Mise hors service (Sunset) : Une fois qu’un produit ou une API est mis hors service, l’ensemble des endpoints correspondants ne sera plus accessible via l’API.

​

Stratégie de gestion des versions

Les principes clés de cette stratégie sont :

1. Toutes les modifications disruptives seront regroupées dans une nouvelle version

2. La période de dépréciation des versions existantes lorsqu’une nouvelle version est annoncée est de 6 mois

3. À tout moment, l’API acceptera des requêtes provenant de deux versions simultanément ; toutefois, la plus ancienne des deux ne sera pas prise en charge

4. Afin de favoriser une adoption plus rapide des nouveaux produits, ceux-ci seront publiés de manière continue (en dehors du rythme de versionnage)

5. Toutes les réponses de l’API incluront un en-tête x-current-api-version correspondant à la version actuelle de l’API, ainsi qu’un en-tête x-api-warn lors de l’appel de tout endpoint d’API obsolète.

S’il devait y avoir des changements fondamentaux des exigences produit nécessitant une modification disruptive de l’API (par ex. la dépréciation du ciblage par tranches d’âge multiples), nous enverrons un préavis de 90 jours pour annoncer ce changement, puis au moins 90 jours après la publication de l’avis, le changement sera déployé

​

v9

Aujourd’hui, le 3 mars 2021, la version 9 (v9) de la X Ads API est désormais disponible. Cette version vise à améliorer la parité fonctionnelle, à simplifier la création de campagnes et à introduire des mises à jour majeures pour nos endpoints Cards et Mobile App Promotion.

Comme pour les versions précédentes, une période de transition de 6 mois est prévue pour migrer vers la v9. Le 31 août 2021, la version 8 (v8) de la X Ads API ne sera plus disponible. Nous encourageons tous les développeurs à migrer vers la dernière version de la X Ads API dès que possible afin d’éviter toute interruption de service.

Remarque : À compter de cette version, la version 7 (v7) de la X Ads API est arrivée en fin de vie et n’est plus disponible.

Pour plus de détails, veuillez consulter l’annonce sur le forum des développeurs.

​

v8

Aujourd’hui, 20 septembre 2020, nous présentons la version 8 de la X Ads API, conçue pour introduire de nouvelles fonctionnalités Tailored Audiences, renforcer la parité des fonctionnalités avec ads.x.com et améliorer l’expérience des développeurs.

Comme pour les versions précédentes, une période de transition de 6 mois est prévue pour migrer vers v8. À compter du 2021-03-02, la version 7 de la X Ads API ne sera plus disponible. Nous encourageons tous les développeurs à passer à la dernière version de l’API dès que possible afin d’éviter toute interruption de service.

Pour plus de détails, veuillez consulter l’annonce sur le forum des développeurs.

​

v7

Aujourd’hui, 20 mars 2020, nous présentons la version 7 de la X Ads API, conçue pour renforcer la parité des fonctionnalités avec ads.x.com.

Comme pour les versions précédentes, une période de transition de 6 mois est prévue pour migrer vers v7. À compter du 2020-09-01, la version 6 de la X Ads API ne sera plus disponible. Nous encourageons tous les développeurs à migrer vers la dernière version de l’API dès que possible afin d’éviter toute interruption de service. La version 5 de la X Ads API a atteint sa fin de vie et n’est plus disponible.

Pour plus de détails, veuillez consulter l’annonce sur le forum des développeurs.

​

v6

Aujourd’hui, 28 août 2019, X présente l’Ads API v6, avec des mises à jour axées sur la cohérence et l’amélioration de l’expérience des développeurs.

Cette version inclut un nouvel endpoint pour la récupération de Tweets, des statistiques pour les Comptes sponsorisés, la possibilité de rechercher des entités par nom, ainsi que des informations sur le nombre actuel de tâches d’analytique asynchrones en cours de traitement. Par ailleurs, nous avons apporté des mises à jour axées sur la cohérence aux endpoints qui utilisent des médias ainsi qu’à nos endpoints de critères de ciblage. Enfin, nous avons effectué de légères mises à jour de certains noms de paramètres et attributs de réponse et nous mettons en obsolescence l’endpoint Scoped Timeline.

Pour plus de détails, veuillez consulter l’annonce sur le forum des développeurs.

​

v5

Aujourd’hui, 28 février 2019, X présente Ads API v5, avec des mises à jour axées sur l’augmentation de l’échelle et l’efficacité.

Cette version inclut un nouvel endpoint pour déterminer quelles entités étaient actives sur une période donnée, des statistiques pour les Media Creatives (c.-à-d. des vidéos In-stream et des images sur la X Audience Platform), la possibilité de récupérer plusieurs cartes par URI de carte, ainsi qu’une plus grande flexibilité pour la récupération des critères de ciblage et d’autres entités. En outre, nous avons corrigé des bogues et mis à jour des noms de paramètres et des attributs de réponse. Enfin, les cartes d’app non multimédia et l’endpoint POST accounts/:account_id/account_media ont été déclarés obsolètes.

Comme pour les versions précédentes, une période de transition de 6 mois est prévue pour migrer vers la v5. Le 2019-08-28, la version 4 de la X Ads API ne sera plus disponible. Nous encourageons tous les partenaires à migrer vers la dernière version de l’API dès que possible afin d’éviter toute interruption de service. La version 3 de la X Ads API est arrivée en fin de vie et n’est plus disponible.

​

Nouveau

Détermination des entités actives

L’endpoint Active Entities indique si les métriques d’analytics des entités publicitaires ont changé. Conçu pour être utilisé avec les endpoints d’analytics, Active Entities fonctionne en spécifiant un type d’entité et une plage de dates — maximum 90 jours — et renvoie un tableau d’ID d’entité pour lesquels votre plateforme doit demander des analytics. Les ID autres que ceux renvoyés ne doivent pas être interrogés dans les requêtes d’analytics suivantes.

Cet endpoint prend en charge les types d’entités suivants : CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE et PROMOTED_TWEET.

Statistiques MEDIA_CREATIVE

Les endpoints d’analytics de la X Ads API fournissent désormais des métriques pour les entités Media Creative. Les Media Creatives correspondent à la façon dont les publicités in-stream ou les images sur la X Audience Platform sont promues. L’interface X Ads présente les métriques Media Creative sous les onglets « In-stream videos » et « Display creatives ». Les endpoints d’analytics synchrones et asynchrones prennent désormais en charge l’énumération d’entité MEDIA_CREATIVE.

Récupérer plusieurs cards

Dans le prolongement de la version v3 de l’endpoint conçu pour récupérer une seule card par sa valeur d’URI de card, il est désormais possible de récupérer plusieurs cards via l’endpoint GET accounts/:account_id/cards/all. Désormais, plutôt que d’effectuer une requête pour chaque card, vous pouvez en récupérer jusqu’à 200 en une seule requête.

Deux points à noter :

1. Le chemin d’URL est désormais accounts/:account_id/cards/all. (L’ancien chemin n’est plus disponible.) Cela nous permet d’être cohérents avec l’endpoint conçu pour récupérer une card par ID.
2. Le paramètre de requête requis s’appelle désormais card_uris (pluriel).

Plus de flexibilité pour la récupération

L’endpoint GET accounts/:account_id/targeting_criteria prend désormais en charge plusieurs ID de line item. Le paramètre line_item_ids, qui accepte jusqu’à 200 ID, est requis. Auparavant, un seul line item était accepté, ce qui compliquait la synchronisation. Avec ce changement, il est désormais possible de récupérer davantage de ciblages en moins de temps.

Les endpoints suivants prennent désormais également en charge plusieurs ID de line item, bien que le paramètre line_item_ids soit facultatif pour ceux-ci.

• GET accounts/:account_id/line_item_apps
• GET accounts/:account_id/media_creatives
• GET accounts/:account_id/promoted_accounts
• GET accounts/:account_id/preroll_call_to_actions

​

Modifié

Récupération des campagnes et des éléments de campagne en brouillon

La méthode de récupération des campagnes et des éléments de campagne en brouillon a été mise à jour. Désormais, lorsque le paramètre with_draft(boolean) est défini sur true, il renvoie à la fois les entités en brouillon et celles qui ne le sont pas. Cela est cohérent avec la manière dont les entités supprimées sont récupérées (à savoir via with_deleted). Auparavant, obtenir à la fois les entités en brouillon et non brouillon nécessitait au moins deux requêtes. Désormais, cela peut se faire en un seul appel à l’API.

| v4 | v5 | | :--- | :--- | :--- | | draft_only | with_draft | |

Ciblage par durée d’activation du réseau

La X Ads API a corrigé un problème d’affichage où, après avoir ajouté le ciblage Network Activation Duration, le type de ciblage dans la réponse incluait le suffixe _IN_SEC. La mention des secondes prêtait à confusion, car Network Activation Duration est toujours exprimé en mois. Cette correction harmonise la représentation et réduit la confusion.

| v4 | v5 | | :--- | :--- | :--- | | NETWORK_ACTIVATION_DURATION_IN_SEC | NETWORK_ACTIVATION_DURATION | |

Décomptes totaux et curseurs

Dans v5, with_total_count et cursor sont exclusifs. Spécifier les deux dans une requête renvoie le code d’erreur EXCLUSIVE_PARAMETERS. Avant v5, with_total_count était ignoré lorsque cursor était spécifié. Ce changement rend la relation explicite.

​

Supprimé

Trois fields sont supprimés des réponses de la X Ads API : preview_url, account_id et parent_ids. L’effort d’ingénierie requis pour ces trois éléments est minimal.

• En v4, il a été annoncé que le paramètre de réponse preview_url pour les cards était toujours null. L’étape finale de cette migration consiste à supprimer preview_url de toutes les réponses de cards.
• L’attribut de réponse account_id est supprimé pour les ressources suivantes, étant donné que l’identifiant du compte publicitaire est déjà présent dans l’URL ainsi que dans request.params. (Il est intentionnel d’exclure les instruments de financement de cette liste, car les ids parents doivent être présents dans les objets de réponse lorsque cela est possible, et les ids de compte sont des entités parentes des instruments de financement.)
  • Médias de compte
  • Fournisseurs d’événements App
  • Tags d’événements App
  • Campagnes
  • Cards
  • Line items
  • Utilisateurs promouvables
  • Critères de ciblage
• Pour les requêtes GET accounts/:account_id/targeting_criteria, nous ne renvoyons plus le field parent_ids car il a toujours été un tableau vide.

Cartes d’app sans média

En v5, les cartes d’app sans média ne sont plus prises en charge. Auparavant, la possibilité de créer ou de modifier des cartes d’app sans média avait été supprimée. Désormais, les endpoints restants pour cette ressource sont en cours de dépréciation.

• Remarque : Cela n’affecte pas les cartes de téléchargement d’app avec image ou vidéo.

Création de médias de compte

L’endpoint POST accounts/:account_id/account_media n’est plus disponible en v5. Les autres endpoints pour cette ressource ne sont pas affectés. Cette modification s’explique par le fait que, lors de l’ajout de médias à la Media Library, certains assets sont automatiquement ajoutés en tant qu’entités Account Media, et tenter d’ajouter un asset déjà existant à la ressource Account Media entraîne une erreur. Cela se produit dans les cas suivants.

• Les assets AMPLIFY_VIDEO ajoutés à la Media Library sont automatiquement ajoutés en tant qu’asset Account Media avec le type créatif PREROLL.
• Les images avec des dimensions spécifiques ajoutées à la Media Library sont automatiquement ajoutées en tant qu’assets Account Media. Le type créatif (par ex. INTERSTITIAL) dépend des dimensions de l’image. (Pour les dimensions, voir notre page Enumerations.)

​

v4

La version 4 de la X Ads API est lancée aujourd’hui, 28 août 2018.

Cette version apporte des améliorations à notre produit Audiences, notamment une nouvelle interface d’API reposant sur un backend de traitement des audiences plus robuste. La version 4 inclut également un ensemble d’endpoints pour gérer les paramètres utilisateur, de compte et fiscaux. Par ailleurs, les endpoints accounts/:account_id/videos sont en cours d’abandon. Cette version comprend aussi quelques modifications mineures des noms de paramètres et de champs de réponse.

Comme pour la version 3, nous offrons une période de transition de 6 mois. À compter du 2019-02-28, la version 3 de la X Ads API ne sera plus disponible. Nous encourageons tous les partenaires à migrer vers la dernière version de l’API dès que possible afin d’éviter toute interruption de service. Consultez notre page Versions pour plus de détails sur notre stratégie de gestion des versions.

​

Nouveautés

Audience API

La nouvelle Audiences API repose sur notre nouveau backend de traitement des audiences, offrant une robustesse et une fiabilité accrues. Ce nouvel endpoint permettra aux partenaires de fournir plusieurs types d’identifiants pour un même utilisateur, ce qui nous permet d’exploiter des signaux supplémentaires pour l’appariement. La documentation de référence pour le nouvel endpoint Audience est disponible ici. Nous continuerons de publier des mises à jour et des améliorations de ce produit tout au long de l’année.

Les endpoints suivants ne seront plus disponibles en v4 en raison de fonctionnalités redondantes (ils continueront de fonctionner en v3 et seront complètement retirés lorsque la v3 ne sera plus disponible) :

• TON Upload :
  • GET accounts/:account_id/tailored_audience_changes
  • GET accounts/:account_id/tailored_audience_changes/:tailored_audience_change_id
  • POST accounts/:account_id/tailored_audience_changes
  • PUT accounts/:account_id/tailored_audiences/global_opt_out
• Real Time Audiences :
  • POST tailored_audience_memberships

Enfin, le paramètre list_type sera supprimé des requêtes et des réponses sur tous les endpoints Tailored Audiences en version 4.

Settings Endpoints

Nous offrons désormais aux administrateurs de compte la possibilité de définir et de mettre à jour les paramètres utilisateur, de compte et fiscaux. Les paramètres utilisateur correspondent aux préférences de contact propres à l’utilisateur pour un compte publicitaire donné. À l’aide de l’endpoint PUT accounts/:account_id, les annonceurs peuvent désormais mettre à jour le nom de leur compte et leur secteur d’activité. Enfin, les endpoints des paramètres fiscaux permettent aux annonceurs dans les pays où une taxe sur la valeur ajoutée (TVA) est appliquée de mettre à jour des informations telles que le nom de l’entreprise, l’adresse, l’identifiant de TVA et d’indiquer si le compte appartient à l’annonceur ou à une agence faisant de la publicité pour son compte.

​

Modifié

Renommages universels de Lookalike

Nous mettons à jour les valeurs d’énumération du paramètre lookalike_expansion sur les endpoints POST accounts/:account_id/line_items et PUT accounts/:accountit/line_items/:line_item_id.

v3	v4
NARROW	DEFINED
BALANCED	EXPANDED

Utilisation de country_code partout

Dans le cadre d’un effort plus large de cohérence sur la X Ads API, nous renommons, sur les endpoints suivants, le paramètre app_country_code en country_code.

• POST accounts/:account_id/cards/image_app_download
• PUT accounts/:account_id/cards/image_app_download/:card_id
• POST accounts/:account_id/cards/video_app_download
• PUT accounts/:account_id/cards/video_app_download/:card_id

Cela n’a aucun impact sur le comportement ni sur les valeurs acceptées pour ces paramètres et constitue uniquement un changement d’appellation.

preview_url toujours null

Comme annoncé pour la v3, toutes les cartes existantes disposent désormais d’un card_uri. Par conséquent, la valeur de preview_url sera toujours null.

Pour rappel, associez une carte à un Tweet en utilisant sa valeur card_uri. Consultez l’exemple de requête suivant.

$ twurl -X POST -H ads-api.x.com “/4/accounts/18ce54d4x5t/tweet?text=Version 4&card_uri=card://958225772740714496”

​

Supprimé

Endpoints vidéo

Les endpoints accounts/:account_id/videos ne seront plus disponibles en v4. Cet endpoint est rendu obsolète par l’introduction des endpoints Media Library. Voir la comparaison d’utilisation ci-dessous.

• endpoint vidéos v3 : twurl -H ads-api.x.com "/3/accounts/18ce54d4x5t/videos"

• endpoint Media Library v4 pour les vidéos : twurl -H ads-api.x.com "/4/accounts/18ce54d4x5t/media_library?media_type=VIDEO"

Les endpoints Media Library sont entièrement équivalents aux endpoints vidéos et prennent également en charge des fonctionnalités supplémentaires, comme la gestion des images et des GIF. Il est demandé aux partenaires d’utiliser exclusivement la Media Library pour toute gestion des médias.

as_user_id dans l’affichage du Tweet

Le paramètre as_user_id disponible sur l’endpoint GET accounts/:account_id/tweet/preview/:tweet_id ne sera plus accepté. L’aperçu sera toujours rendu en tant qu’auteur du Tweet.

​

v3

La version 3 de la X Ads API a été lancée le 1er février 2018. La version 2 de la X Ads API atteindra sa fin de vie le 1er août 2018.

Cette version inclut notre nouveau produit Audience Intelligence, l’accès à la Media Library et des workflows de cartes améliorés. Nous annonçons également la mise hors service de l’endpoint PUT accounts/:account_id/targeting_criteria. Enfin, la version 3 inclut quelques modifications mineures des paramètres et des réponses ainsi qu’une limite inférieure de taille de lot.

Comme pour la version 2, nous accordons aux partenaires 6 mois pour la transition. Le 2018-08-01, la v2 de la X Ads API sera désactivée. Nous encourageons tous les partenaires et développeurs à migrer vers la v3 dès que possible.

Audience Intelligence

Audience Intelligence fournit des insights en temps réel sur les hashtags, @handles et événements les plus pertinents pour une audience X donnée. Par exemple, saisissez Homme 18–34 aux États-Unis et vous verrez #nintendoswitch, #cardinal et @ricegum en tendance au sein de cette audience.

Les endpoints d’Audience Intelligence offriront les fonctionnalités suivantes :

• Étant donnée une audience en entrée, récupérer les principaux hashtags, @handles et événements pertinents.
• Étant donnée une audience en entrée, récupérer des informations démographiques clés (telles que l’âge, le sexe et le revenu du foyer).
• Étant donné un mot-clé, récupérer la série temporelle du volume de Tweets.

Media Library

La Media Library permet de gérer des images, des GIF et des vidéos pour les comptes publicitaires. Ces objets média peuvent être utilisés dans des Tweets et pour créer des cartes. Ils peuvent également être réutilisés dans plusieurs créations, évitant ainsi de téléverser le même élément plusieurs fois.

Les objets de la bibliothèque sont identifiés par un media_key. Les media keys sont des valeurs de chaîne au format suivant : 13_875943225764098048, par exemple. Dans la X Ads API, nous évoluons vers l’utilisation de media keys pour tous les médias.

Workflow de cartes amélioré

Tous nos endpoints de cartes prennent désormais en charge les media keys. Cela permet d’utiliser les objets de la Media Library pour créer ou mettre à jour des cartes.

De plus, nous introduisons deux nouveaux endpoints pour récupérer les détails d’une carte. Ces endpoints peuvent être utilisés pour rechercher des cartes utilisées dans des Tweets ou des Tweets programmés, par exemple, en spécifiant soit le card_uri, soit l’id. Auparavant, cela n’était pas possible.

​

Autres changements

En plus de ces nouvelles fonctionnalités, nous incluons les changements suivants dans la version 3.

Nouveau

• La réponse de l’endpoint GET insights/keywords/search inclut désormais un attribut related_keywords avec 30 termes liés aux mots-clés fournis en entrée.

Modifié

• La taille maximale d’un lot de critères de ciblage est désormais de 500.
• Les attributs de réponse card_uri et preview_url sont désormais mutuellement exclusifs. Lorsqu’une carte possède un card_uri, preview_url sera null. Lorsqu’une carte n’a pas de card_uri, seul preview_url sera renvoyé.
  • Toutes les cartes créées à partir du 2018-01-29 auront un card_uri.
  • D’ici la version 4, toutes les cartes existantes auront un card_uri.
• Il n’est plus possible de créer des cartes avec des images au format 5:2. Bien que les cartes existantes basées sur des images 5:2 continuent de fonctionner, nous encourageons les partenaires à passer à des rapports d’aspect plus performants, 1,91:1 ou 1:1 (là où ils sont pris en charge).

Supprimé

• L’endpoint PUT accounts/:account_id/targeting_criteria n’est plus disponible. Nous avons décidé d’effectuer ce changement car le comportement de remplacement de cet endpoint entraînait une confusion chez les annonceurs et n’était pas cohérent avec nos autres endpoints PUT qui mettent à jour une seule ressource à la fois. À la place, les partenaires doivent utiliser l’endpoint POST batch/accounts/:account_id/targeting_criteria, qui offre une plus grande flexibilité, notamment la possibilité d’ajouter et de supprimer du ciblage dans une seule requête.
• L’attribut de réponse paused n’est plus renvoyé pour les instruments de financement. À la place, consultez l’attribut de réponse entity_status pour déterminer si un instrument de financement est en pause ou non. De plus, comme paused et cancelled correspondent à la même valeur, cancelled n’est plus renvoyé non plus dans la réponse.
• Nous avons supprimé le paramètre card_id de l’endpoint GET accounts/:account_id/tweet/preview.
• Étant donné qu’il n’est pas possible de récupérer des Scheduled Tweets supprimés, le paramètre with_deleted n’est plus pris en charge.
• Le paramètre draft_only a été supprimé des endpoints suivants, car ces entités ne peuvent jamais être à l’état de brouillon :
  • GET accounts/:account_id/targeting_criteria
  • GET accounts/:account_id/promoted_tweets
  • GET accounts/:account_id/promoted_accounts
  • GET accounts/:account_id/media_creatives
  • GET accounts/:account_id/preroll_call_to_actions

Remarque

Les Video Website Cards et les Scheduled Tweets ne sont plus en bêta. Consultez ce fil pour les changements que nous avons apportés aux Scheduled Tweets depuis le lancement. Cela inclut la possibilité de générer des aperçus HTML pour les Scheduled Tweets.

​

v2

La version 2 de la X Ads API a été lancée le 10 juillet 2017. La version 1 de la X Ads API arrivera en fin de vie le 10 janvier 2018.

Modifications majeures/Abandons¶

• total_count est désormais un attribut de réponse facultatif. Il ne sera disponible que si with_total_count est défini sur true

• Les champs paused et draft_only dans les objets de requête et de réponse line_items et campaigns sont remplacés par un seul paramètre entity_status

• Le paramètre status a été renommé text sur les endpoints POST accounts/:account_id/tweet et GET accounts/:account_id/tweet/preview

• Les valeurs énumérées location_type de l’endpoint GET targeting_criteria/locations sont désormais au pluriel. COUNTRY devient COUNTRIES, REGION devient REGIONS, etc. La seule exception est que, dans v2, CITY devient METROS, pour refléter correctement que le type d’emplacement fait référence aux Designated Market Areas (DMA) ou « metros ».

• display_properties sur les endpoints PUT accounts/:account_id/promoted_tweets. Cette valeur ne sera plus renvoyée dans la réponse

• En conséquence du point précédent, il n’est plus possible de mettre à jour (PUT) les entités promoted_tweets

• Le paramètre line_item_id sur l’endpoint GET accounts/:account_id/promoted_tweets a été supprimé

• Il ne sera plus possible de créer des Website Cards 5:2 sur les endpoints v2

• L’attribut de réponse data_type n’est plus renvoyé

Nouvelles fonctionnalités¶

1. Cards v2
2. Création et activation de campagnes/line items en brouillon
3. Tweets programmés
4. Résumés de tâches asynchrones

Cards v2¶

• Le paramètre de requête card_uri doit être utilisé plutôt que d’ajouter preview_url au texte du Tweet lors de l’association d’une card à un Tweet
• Si le paramètre card_uri n’est pas renvoyé dans la réponse (lors de l’étape de création de la card), utilisez alors preview_url
• Tous les nouveaux formats de card seront disponibles nativement via l’API, en tirant parti du paramètre card_uri.

Nouveaux formats de Card :¶

• Video Website Cards :

  • GET accounts/:account_id/cards/video_website
  • GET accounts/:account_id/cards/video_website/:card_id
  • POST accounts/:account_id/cards/video_website
  • PUT accounts/:account_id/cards/video_website/:card_id
  • DELETE accounts/:account_id/cards/video_website/:card_id

Campagnes brouillon¶

Les campagnes brouillon étaient consultables via l’endpoint GET accounts/:account_id/campaigns. Avec v2, il est désormais possible de créer/activer des campagnes brouillon via l’API.

• La valeur du paramètre entity_status sur les endpoints POST accounts/:account_id/line_items et POST accounts/:account_id/campaigns peut être définie sur DRAFT afin de créer de nouvelles campagnes ou de nouvelles lignes en brouillon.
• Ensemble des paramètres requis pour un brouillon nouvellement créé :

Campagne en brouillon	Ligne en brouillon
funding_instrument_id	campaign_id
name	objective
start_time	product_type
	placements

Notes¶

• Les lignes ou campagnes en brouillon ne peuvent être converties que d’un entity_status de DRAFT vers PAUSED ou ACTIVE.
• Pour activer une campagne entière (avec plusieurs lignes), chaque ligne de la campagne, ainsi que la campagne elle-même, doit avoir un entity_status défini sur ACTIVE.
• Pour modifier le entity_status de toute campagne ou ligne, utilisez l’endpoint PUT correspondant.

Tweets programmés¶

• Les Tweets programmés comprennent les endpoints suivants :

• Tweets programmés :

  • GET accounts/:account_id/scheduled_tweets
  • GET accounts/:account_id/scheduled_tweets/:scheduled_tweet_id
  • POST accounts/:account_id/scheduled_tweets
  • PUT accounts/:account_id/scheduled_tweets/:scheduled_tweet_id
  • DELETE accounts/:account_id/scheduled_tweets/:scheduled_tweet_id

• Gestion des campagnes :

  • GET accounts/:account_id/scheduled_promoted_tweets
  • GET accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id
  • POST accounts/:account_id/scheduled_promoted_tweets
  • DELETE accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id

• De nouveaux Tweets peuvent être programmés pour n’importe quelle date future.

• Actuellement, il n’est pas possible d’afficher un aperçu d’un Tweet programmé.

• Seuls les Tweets programmés avec l’état SCHEDULED peuvent être modifiés/supprimés.

• Les Tweets programmés ne sont pas propagés vers le Firehose Enterprise ni vers aucune autre API de données avant la date/heure scheduled_at.

​

v1

La version 1 de la X Ads API a été lancée le 31 mars 2016 et arrivera en fin de vie le 10 janvier 2018.

Modifications de la version 1 :¶

• Prise en charge de la gestion des versions
• L’objectif CUSTOM n’est plus pris en charge
• Les endpoints de traitement par lots sont désormais disponibles en disponibilité générale
• Modifications de l’estimation de la portée:
• Pour améliorer l’estimation de la portée, l’endpoint prend désormais en compte le budget. Les paramètres suivants sont désormais obligatoires :
  • [nouveau] campaign_daily_budget_amount_local_micro
  • currency
  • bid
  • objective
• L’objet de réponse a été modifié et renvoie désormais des plages pour les valeurs de réponse.
• infinite_count a été renommé infinite_bid_count pour éviter toute confusion quant à sa finalité
• Outre count et infinite_bid_count, les nouvelles données suivantes seront désormais renvoyées :
  • impressions
  • engagements
  • estimated_daily_spend_local_micro
• Changement de type de données pour les audiences personnalisées
• Le data_type des Tailored Audiences a été modifié de tailored_audiences à tailored_audience dans toutes nos réponses.
• Les audiences personnalisées partagées sont désormais disponibles en version bêta, uniquement via l’API. Elles permettent d’utiliser une même audience sur plusieurs comptes publicitaires. Utilisez l’endpoint POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions (et les endpoints associés) pour gérer les autorisations d’une audience personnalisée que vous souhaitez partager entre plusieurs comptes publicitaires.
• Des améliorations majeures dans la manière de collecter les analyses de performance pour les comptes annonceurs :
• Pour respecter nos meilleures pratiques, nous n’autoriserons désormais l’extraction de données que pour une période maximale de 7 jours via les endpoints de statistiques synchrones.
• Pour simplifier la récupération des métriques, nous avons remplacé le paramètre metrics par un nouveau paramètre metric_groups. Les développeurs doivent simplement indiquer quels groupes de métriques ils souhaitent recevoir pour une requête donnée.
  • Toute demande de métriques qui ne sont pas appropriées pour une entité donnée sera exclue de la réponse et représentée par des valeurs null. Ces métriques ne seront pas décomptées de votre limite de coût d’analytics.
• La réponse a été considérablement simplifiée et s’alignera désormais plus étroitement sur la manière dont les métriques sont présentées dans notre interface.
  • Auparavant, nous exposions une métrique distincte pour chaque emplacement (Promoted Tweets in Search, Promoted Tweets in Timelines, Promoted Tweets in Profiles & Tweet Details, X Audience Platform). Nous renvoyons désormais un ensemble standardisé de métriques pour chacun (au lieu de promoted_tweet_timeline_impressions, promoted_tweet_search_impressions, promoted_tweets_profile_impressions, promoted_tweets_tpn_impressions) : elles seront exposées, lorsqu’elles sont demandées dans l’une des catégories suivantes, sous la forme d’une unique métrique, impressions (cela s’applique à toutes les métriques) :
  • ALL_ON_TWITTER
  • PUBLISHER_NETWORK
  • Lorsque vous effectuez une requête, vous recevrez une unique métrique impressions, afin de faciliter l’alignement des valeurs avec notre interface.
  • Vous devez effectuer deux requêtes pour obtenir à la fois les données ALL_ON_TWITTER et PUBLISHER_NETWORK, car elles ne peuvent pas être combinées.
• Les endpoints de statistiques asynchrones sont désormais disponibles, suite aux retours de nos développeurs !
  • Un nouvel ensemble d’endpoints pour demander des statistiques de manière asynchrone, pour des données dont vous n’avez pas besoin immédiatement ou pour des extractions historiques.
  • Placez un job de statistiques en file d’attente à l’aide d’un nouvel endpoint unique. Nous récupérerons les données demandées en fonction des ressources disponibles.
  • Vous pouvez interroger un endpoint d’état du job pour déterminer si les données sont disponibles.
  • Une fois les données disponibles, nous fournirons un id de retrait afin que vous puissiez télécharger la réponse JSON, qui reflétera la réponse de l’endpoint synchrone.
  • Interrogez jusqu’à 90 jours de données sur jusqu’à 20 entités dans un seul job.
• Consultez notre guide de migration Analytics v1, qui inclut le mapping des métriques v0 vers les métriques v1
• Améliorations du Sandbox * Vous pouvez désormais créer plusieurs comptes publicitaires de test dans l’environnement Sandbox. * Vous pouvez désormais créer plusieurs instruments de financement pour un compte publicitaire de test, uniquement dans l’environnement Sandbox. Cela vous permet de tester tous nos types d’instruments de financement. Auparavant, seule une source de financement CREDIT_CARD était disponible pour les tests. * Vous souhaitez tester une fonctionnalité bêta ? Vous pouvez désormais activer ou désactiver des fonctionnalités pour un compte dans l’environnement Sandbox afin de répondre à vos besoins de test.

​

v0

La version 0 de la X Ads API a été officiellement lancée le 21 février 2013 et a été prise en charge jusqu’au 31 octobre 2016.

Tous les endpoints d’analytics de la version 0 sont dépréciés et ne seront plus disponibles après le 31 octobre 2016. Ils ont été remplacés par trois endpoints d’analytics dans la version 1.

L’endpoint d’estimation de la portée présente un nouveau comportement dans la version 1.