Versions

Pour obtenir les informations les plus récentes sur les anciennes versions de l’API X Ads, veuillez vous référer au tableau ci‑dessous.

Version	Chemin	Date d’introduction	Date d’obsolescence	Date de fin de vie
12.0	/12/	27 octobre 2022	TBD	TBD
11.0	/11/	31 mars 2022	TBD	TBD
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 l’API X Ads. Ces modifications sont presque toujours rétrocompatibles, mais nous introduisons tout de même chaque année un certain nombre de changements incompatibles. Nous avons reçu des retours de la part des développeurs sur les difficultés que la cadence rapide des changements dans l’API Ads entraîne pour leurs cycles de développement, qu’il s’agisse de l’implémentation de nouvelles fonctionnalités, de la gestion des dépréciations ou des tests de ces changements. Nous voulons améliorer l’expérience développeur sur notre plateforme Ads, c’est pourquoi nous avons introduit le concept de versionnement de nos endpoints.

Quelques définitions de certains des concepts dont nous parlons :

Version : fait référence au numéro de version présent dans le chemin d’URL de toute requête Ads API, par exemple : GET //accounts. Ce style de versionnement est connu sous le nom de versionnement URI.

Breaking Changes : les changements incompatibles (« breaking changes ») sont tous les changements qui nécessitent des ressources de développement pour maintenir la fonctionnalité existante. Cela inclut les ressources utilisées pour l’analyse des changements à effectuer, la détermination des fonctionnalités/endpoints dépréciés et la mise en œuvre finale de tous ces changements. Une liste de changements incompatibles inclut des éléments tels que :

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

• Modification du nom d’un paramètre ou d’un endpoint

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

• Changement de comportement des endpoints (par ex. stats async vs sync)

• Ajout/modification de paramètres optionnels ou obligatoires (par ex. rendre name obligatoire dans la requête)

Deprecation : les versions ou produits dépréciés ne seront plus pris en charge et il est recommandé aux développeurs de cesser d’utiliser ces API.

Sunset : une fois qu’un produit ou une API est en fin de vie (« sunset »), l’ensemble de endpoints correspondant ne sera plus accessible via l’API.

​

Stratégie de versionnage

Les principaux principes de la stratégie sont :

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

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

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

4. Afin de favoriser une adoption plus rapide des nouveaux produits, ceux-ci seront publiés en continu (en dehors de la cadence de versionnage)

5. Toutes les réponses d’API contiendront un en-tête x-current-api-version, défini sur 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.

En cas de modification fondamentale des exigences produit nécessitant un changement majeur de l’API (par exemple, la mise en obsolescence de la segmentation par tranches d’âge multiples), nous enverrons un préavis de 90 jours pour annoncer ce changement majeur et, au moins 90 jours après la publication de ce préavis, le changement majeur sera déployé.

​

v9

Aujourd’hui, le 3 mars 2021, la version 9 (v9) de l’API Ads de X est désormais disponible. Cette version est conçue pour renforcer la parité fonctionnelle, simplifier la création de campagnes et introduire des mises à jour clés pour nos points de terminaison (endpoints) Cards et Mobile App Promotion.

Comme pour nos 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) existante de l’API Ads ne sera plus disponible. Nous encourageons tous les développeurs à migrer vers la dernière version de l’API Ads dès que possible afin d’éviter toute interruption de service.

Remarque : À compter de cette version, la version 7 (v7) de l’API Ads a atteint sa fin de vie et n’est plus disponible.

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

​

v8

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

Comme pour les versions précédentes, une période de transition de six mois est prévue pour migrer vers la v8. Le 2 mars 2021, la version 7 de l’API Ads 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.

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

​

v7

Aujourd’hui, le 20 mars 2020, nous annonçons la version 7 de l’API X Ads, conçue pour améliorer la parité fonctionnelle avec ads.x.com.

Comme pour les versions précédentes, une période de transition de six mois est prévue pour la migration vers v7. À compter du 1er septembre 2020, la version 6 de l’API Ads 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 l’API Ads 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.

​

v6

Aujourd’hui, le 28 août 2019, X introduit 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 récupérer des Tweets, des statistiques pour les comptes sponsorisés (Promoted Accounts), la possibilité de rechercher des entités par nom, ainsi que des informations sur le nombre actuel de tâches d’analyse asynchrone en cours de traitement. De plus, nous avons apporté des mises à jour centrées sur la cohérence aux endpoints qui utilisent des médias et à nos endpoints de critères de ciblage. Enfin, nous avons effectué de légères mises à jour sur certains de nos noms de paramètres et attributs de réponse et nous déclarons l’endpoint Scoped Timeline obsolète.

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

​

v5

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

Cette version inclut un nouvel endpoint permettant de déterminer quelles entités étaient actives sur une période donnée, des statistiques pour les Media Creatives (c.-à-d. les vidéos In-stream et les images sur la X Audience Platform), la possibilité de récupérer plusieurs cards par URI de card, ainsi qu’une plus grande flexibilité pour récupérer les critères de ciblage et d’autres entités. De plus, nous avons corrigé certains bugs et mis à jour des noms de paramètres et des attributs de réponse. Enfin, les app cards 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. À partir du 2019-08-28, la version 4 de l’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 l’Ads API a atteint sa fin de vie et n’est plus disponible.

​

Nouveautés

Déterminer quelles entités étaient actives

L’endpoint Active Entities indique si les métriques d’analytics pour les entités d’annonces ont changé. Conçu pour être utilisé conjointement avec les endpoints d’analytics, Active Entities fonctionne en spécifiant un type d’entité et une plage de dates — un maximum de 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 l’API Ads fournissent désormais des métriques pour les entités Media Creative. Les Media Creatives correspondent à la façon dont les annonces in-stream ou les images sur la X Audience Platform sont promues. L’interface X Ads affiche 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

En améliorant 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 à l’aide de l’endpoint GET accounts/:account_id/cards/all. Désormais, plutôt que d’effectuer une requête pour chaque card, vous pouvez récupérer jusqu’à 200 cards dans 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 (au 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 items. Le paramètre line_item_ids, qui accepte jusqu’à 200 ID, est requis. Auparavant, un seul line item était accepté, ce qui rendait la synchronisation difficile. Avec ce changement, il est désormais possible de récupérer davantage de ciblage en moins de temps.

Les endpoints suivants prennent également désormais en charge plusieurs ID de line items, 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 line items brouillon

La manière dont les campagnes et line items brouillon sont récupérés a été mise à jour. Désormais, le paramètre with_draft(boolean), lorsqu’il est défini sur true, renvoie à la fois les entités en brouillon et non brouillon. Cela est cohérent avec la manière dont les entités supprimées sont récupérées (c’est‑à‑dire en utilisant with_deleted). Auparavant, récupérer à la fois les entités brouillon et non brouillon nécessitait au minimum deux requêtes. Il est désormais possible de le faire en un seul appel à l’API.

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

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

L’Ads API a résolu un problème d’affichage où, après avoir ajouté un ciblage Network Activation Duration, le type de ciblage dans la réponse incluait le suffixe _IN_SEC. La référence aux secondes était déroutante, car Network Activation Duration est toujours représenté en mois. Cette correction rend la représentation cohérente et réduit la confusion.

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

Totaux et curseurs

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

​

Supprimé

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

• Dans la 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’ID 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 ID parents doivent être présents dans les objets de réponse, lorsque c’est possible, et les ID de compte sont les entités parentes des instruments de financement.)
  • Médias de compte
  • Fournisseurs d’événements d’App
  • Tags d’événements d’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 champ parent_ids, car il s’agissait toujours d’un tableau vide.

App cards sans média

Dans la v5, les app cards sans média ne sont plus prises en charge. Auparavant, la possibilité de créer ou de modifier des app cards sans média avait été supprimée. À présent, les endpoints restants pour cette ressource sont en cours de mise hors service.

• Remarque : cela n’affecte pas les app download cards d’images et de vidéos.

Création de médias de compte

L’endpoint POST accounts/:account_id/account_media n’est plus disponible dans la v5. Les autres endpoints pour cette ressource ne sont pas affectés. Ce changement s’explique par le fait que, lors de l’ajout de médias à la Media Library, il existe des cas où ces éléments sont automatiquement ajoutés en tant qu’entités Account Media, et tenter d’ajouter un élément 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 de 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 de créatif (par exemple, INTERSTITIAL) dépend des dimensions de l’image. (Pour les dimensions, consultez notre page Énumérations.)

​

v4

La version 4 de l’Ads API est mise en service aujourd’hui, le 28 août 2018.

Cette version inclut des améliorations de notre produit Audiences, notamment une nouvelle interface d’API reposant sur un backend de traitement d’audiences plus robuste. La version 4 inclut également un ensemble d’endpoints pour gérer les paramètres utilisateur, de compte et fiscaux. De plus, les endpoints accounts/:account_id/videos sont dépréciés. Cette version inclut également quelques légères modifications des noms de paramètres et de réponses.

Comme pour la version 3, nous proposons une période de transition de 6 mois. À compter du 2019-02-28, la version 3 de l’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

Audiences API

La nouvelle Audiences API est construite sur notre nouveau backend de traitement d’audiences, qui offre 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 signifie que nous sommes en mesure d’utiliser des signaux supplémentaires pour la mise en correspondance. La documentation de référence pour le nouvel endpoint Audience est disponible ici. Nous prévoyons de continuer à publier des mises à jour et des améliorations de ce produit pour le reste 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 entièrement supprimé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/:accounti_d/tailored_audiences/global_opt_out
• Real Time Audiences :
  • POST tailored_audience_memberships

Enfin, le paramètre list_type sera supprimé de la requête et de la réponse sur tous les endpoints Tailored Audiences dans la version 4.

Endpoints de paramètres

Nous offrons désormais la possibilité pour les administrateurs de compte 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é. En utilisant l’endpoint PUT accounts/:account_id, les annonceurs peuvent maintenant mettre à jour le nom de leur compte et leur secteur d’activité. Enfin, les endpoints tax settings permettent aux annonceurs dans les pays où une taxe sur la valeur ajoutée (TVA) est facturée de mettre à jour des informations telles que le nom de l’entreprise, l’adresse, le numéro de TVA et de préciser si le compte appartient à l’annonceur ou à une agence faisant de la publicité pour le compte d’un annonceur.

​

Modifications

Renommages universels des audiences similaires

Nous mettons à jour les valeurs de l’énumération pour le 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 autour de la cohérence dans l’Ads API, nous renommons les paramètres sur les endpoints suivants, de 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 ou les valeurs acceptées pour ces paramètres et constitue uniquement un changement de nommage.

preview_url toujours null

Comme promis dans l’annonce de la v3, toutes les cartes existantes ont désormais 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. Ces endpoints ont été rendus obsolètes par l’introduction des endpoints Media Library. Voir la comparaison d’utilisation suivante.

• 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 offrent une parité complète avec les endpoints vidéos et prennent également en charge des fonctionnalités supplémentaires, comme la possibilité de gérer les images et les GIF. Il est demandé aux partenaires d’utiliser exclusivement Media Library pour toute gestion de 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 affiché comme s’il provenait de l’auteur du Tweet.

​

v3

La version 3 de l’Ads API a été lancée le 1er février 2018. La version 2 de l’Ads API arrivera en 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 de taille de lot plus faible.

Comme pour la version 2, nous donnons aux partenaires 6 mois pour effectuer la transition. Le 2018-08-01, la v2 de l’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 informations en temps réel sur les principaux 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 parmi les tendances au sein de cette audience.

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

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

Media Library

La Media Library offre la possibilité de gérer des images, des GIF et des vidéos pour les comptes publicitaires. Ces objets médias peuvent être utilisés dans des Tweets et pour créer des cartes. Ils peuvent également être réutilisés dans plusieurs créatifs, ce qui évite d’avoir à téléverser plusieurs fois la même ressource.

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

Workflow de carte 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 la récupération des détails de 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 la 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, le preview_url sera null. Lorsqu’une carte ne possède pas de card_uri, seul le 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 aux formats d’image offrant de meilleures performances, 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é, y compris la possibilité d’ajouter et de supprimer des critères de ciblage dans une seule requête.
• L’attribut de réponse paused n’est plus renvoyé pour les instruments de financement. À la place, reportez-vous à 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.
• Comme il n’est pas possible de récupérer des Tweets programmés 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 dans un é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 Tweets programmés sont désormais sortis de la phase bêta. Consultez ce fil pour connaître les changements que nous avons apportés aux Tweets programmés depuis leur lancement. Cela inclut la possibilité de générer des aperçus HTML pour les Tweets programmés.

​

v2

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

Modifications majeures/Obsolescences¶

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

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

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

• Les énumérations location_type de l’endpoint GET targeting_criteria/locations sont désormais au pluriel. COUNTRY est maintenant COUNTRIES, REGION est maintenant REGIONS, etc. La seule exception est que, en v2, CITY est maintenant METROS, afin de refléter correctement le fait que ce type de lieu se réfère aux Designated Market Areas (DMA) ou « metros ».

• Le paramètre display_properties sur les endpoints PUT accounts/:account_id/promoted_tweets est supprimé. Cette valeur ne sera plus non 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 via 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 brouillon
3. Tweets programmés
4. Récapitulatifs 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 nativement disponibles 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_webiste/:card_id

Campagnes brouillon¶

Les campagnes brouillon pouvaient déjà être consultées via l’endpoint GET accounts/:account_id/camapaigns. Avec la 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 nouveaux éléments de ligne à l’état de brouillon.
• L’ensemble des paramètres obligatoires pour un brouillon nouvellement créé :

Campagne brouillon	Élément de ligne brouillon
funding_instrument_id	campaign_id
name	objective
start_time	product_type
	placements

Notes¶

• Les éléments de ligne ou campagnes à l’état de brouillon ne peuvent être convertis que d’un entity_status de DRAFT en PAUSED ou ACTIVE.
• Pour activer une campagne entière (avec plusieurs éléments de ligne), chaque élément de 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 d’une campagne ou d’un élément de ligne, utilisez l’endpoint PUT correspondant.

Tweets programmés¶

• Les Tweets programmés introduisent les nouveaux 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

• Les nouveaux Tweets programmés peuvent être planifiés à n’importe quelle date dans le futur.

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

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

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

​

v1

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

Modifications dans 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 généralement disponibles
• Modifications de l’estimation de la portée:
• Afin de fournir une meilleure estimation de la couverture, l’endpoint prend désormais en compte le budget. Les paramètres suivants sont désormais requis :
  • [nouveau] campaign_daily_budget_amount_local_micro
  • currency
  • bid
  • objective
• L’objet de réponse a été modifié et renvoie désormais des intervalles pour les valeurs de réponse.
• infinite_count a été renommé infinite_bid_count afin d’éviter toute confusion sur sa finalité
• En plus de count et infinite_bid_count, les nouvelles données suivantes seront désormais renvoyées :
  • impressions
  • engagements
  • estimated_daily_spend_local_micro
• Changement du type de données pour les audiences personnalisées
• Le champ data_type pour les Tailored Audiences a été modifié de tailored_audiences à tailored_audience dans toutes nos réponses.
• Les Shared Tailored Audiences sont désormais disponibles en version bêta réservée à l’API. Les Shared Tailored Audiences permettent d’utiliser une seule audience sur plusieurs comptes publicitaires. Utilisez le point de terminaison POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions (et les points de terminaison associés) pour gérer les autorisations d’une Shared Tailored Audience que vous souhaitez partager entre plusieurs comptes publicitaires.
• Importantes améliororations dans la façon dont vous collectez les données analytics sur les performances des comptes annonceurs :
• Afin de nous aligner sur nos bonnes pratiques, nous n’autoriserons désormais l’extraction que pour un maximum de 7 jours de données 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. Il suffit désormais que les développeurs indiquent quels groupes de métriques ils souhaitent obtenir pour une requête donnée.
  • Toute requête 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 prises en compte dans le calcul de votre limite de coûts d’analytics.
• La réponse a été nettement simplifiée et correspond désormais davantage à la manière dont les métriques sont présentées dans notre interface utilisateur.
  • Auparavant, nous exposions une métrique distincte pour chaque emplacement (Tweets sponsorisés dans la recherche, Tweets sponsorisés dans les fils, Tweets sponsorisés dans les profils et détails de Tweet, X Audience Platform). Nous allons désormais renvoyer 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) ; celles‑ci seront maintenant exposées, lorsqu’elles sont demandées dans l’une des catégories suivantes, sous la forme d’une métrique unique, impressions (cela s’applique à toutes les métriques) :
  • ALL_ON_TWITTER
  • PUBLISHER_NETWORK
  • Lorsque vous effectuez une requête, vous obtenez une seule métrique impressions, ce qui simplifie la correspondance des valeurs avec notre interface utilisateur.
  • Vous devez effectuer deux requêtes pour obtenir à la fois les données ALL_ON_TWITTER et PUBLISHER_NETWORK, car celles‑ci ne peuvent pas être combinées.
• Les endpoints de statistiques asynchrones sont désormais disponibles, grâce aux retours de nos développeurs !
  • Un nouvel ensemble d’endpoints pour demander des statistiques de manière asynchrone, pour les données dont vous n’avez pas besoin immédiatement ou pour des extractions de données historiques.
  • Mettez en file d’attente une tâche de statistiques à l’aide d’un nouvel endpoint unique. Nous récupérerons les données que vous avez demandées en fonction des ressources disponibles.
  • Vous pouvez interroger un endpoint d’état de tâche pour déterminer si les données sont disponibles.
  • Une fois les données disponibles, nous fournirons un ID de récupération pour vous permettre de télécharger la réponse JSON, qui reflétera la réponse de l’endpoint synchrone.
  • Interrogez jusqu’à 90 jours de données pour jusqu’à 20 entités dans une seule tâche.
• Consultez notre guide de migration vers Analytics v1, qui propose un 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 dans l’environnement Sandbox uniquement. Cela vous permet de tester tous les types d’instruments de financement que nous proposons. 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 l’API Ads a été officiellement lancée le 21 février 2013 et a été prise en charge jusqu’au 31 octobre 2016.

Tous les endpoints analytics de la version 0 sont obsolètes et ne seront plus disponibles après le 31 octobre 2016. Ces endpoints ont été remplacés par trois endpoints analytics dans la version 1.

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