Analyses

​

Introduction

Les métriques d’analytics aident les partenaires et les annonceurs à comprendre les performances du contenu qu’ils promeuvent sur X. Elles incluent des informations telles que les impressions, les clics, les vues vidéo et les dépenses. En outre, les partenaires et les annonceurs peuvent obtenir des métriques détaillées pour divers segments des audiences qu’ils touchent.

La X Ads API prend en charge deux méthodes pour récupérer des métriques détaillées de performance de campagne : de manière synchrone et asynchrone. Avec les appels d’analytics synchrones, les métriques demandées sont renvoyées dans la réponse. Avec les endpoints d’analytics asynchrones, les métriques demandées sont disponibles dans un fichier de résultats téléchargeable une fois le « job » associé terminé. L’endpoint synchrone prend en charge de courtes plages temporelles et est idéal pour des optimisations de campagne en temps réel. Les endpoints asynchrones prennent en charge des plages temporelles beaucoup plus longues et sont donc destinés à récupérer un volume de données nettement supérieur, idéal pour générer des rapports ou effectuer des reconstitutions historiques.

​

Détails

​

Synchrone vs asynchrone

Les différences entre les endpoints d’analytics synchrones et asynchrones sont résumées dans le tableau suivant. Ces informations visent à aider les développeurs à choisir quel ensemble d’endpoints utiliser.

Fonctionnalité	Synchrone	Asynchrone
Limite de taux	Niveau utilisateur : 250 requêtes/15 minutes	Niveau compte : 100 tâches concurrentes*
Plage temporelle	7 jours	90 jours (non segmentée) 45 jours (segmentée)
Segmentation	Non	Oui
Contenu de la réponse	Données de métriques	État de traitement de la tâche**
Cas d’utilisation recommandé	Optimisation en temps réel Requêtes de l’interface utilisateur	Synchronisations planifiées à intervalles réguliers Rétro-remplissage des données historiques

• Il s’agit du nombre maximal de tâches pouvant être en cours de traitement à un moment donné.

** Une fois la tâche traitée avec succès, une URL est renvoyée. C’est à cette adresse que le fichier de résultats compressé (gzip) peut être téléchargé.

En dehors de cela, les endpoints offrent la même fonctionnalité.

​

Cas d’usage

Il existe trois principaux cas d’usage pour l’analytique.

1. Optimisation en temps réel : utiliser des métriques de performance pour mettre à jour des campagnes actives
2. Synchronisation : synchronisations planifiées en arrière-plan
3. Intégration d’un nouveau compte : reconstitution des données historiques

L’endpoint d’analytique synchrone peut être utilisé pour l’optimisation en temps réel afin de mettre à jour des campagnes en fonction des variations de métriques survenues au cours des 5 à 15 dernières minutes. L’un ou l’autre endpoint peut être utilisé pour la synchronisation analytique. Gardez à l’esprit que l’intervalle de temps souhaité et le besoin éventuel de segmentation détermineront quel endpoint utiliser. L’intégration d’un nouveau compte doit uniquement être effectuée à l’aide des endpoints d’analytique asynchrones. (L’endpoint d’analytique synchrone ne doit jamais être utilisé pour récupérer de grands volumes de data.)

Les endpoints d’analytique asynchrones peuvent alimenter des tableaux de bord et d’autres éléments d’interface utilisateur si les métriques sont synchronisées via un processus backend. Votre implémentation doit éviter d’appeler les endpoints d’analytique asynchrones pour répondre à des requêtes d’interface utilisateur.

​

Options de requête

Les requêtes d’analytics sont limitées aux comptes publicitaires et exigent donc l’id du compte dans le chemin de ressource. Les options de requête ci-dessous sont spécifiées en tant que paramètres de query. Les types de valeurs suivants sont requis.

• Entities: le type d’entité ainsi que jusqu’à 20 id d’entité pour lesquels vous souhaitez demander des analytics
• Plage temporelle: les heures de début et de fin, exprimées en ISO 8601
  • Remarque : doivent être exprimées en heures pleines
• Groupes de métriques: un ou plusieurs ensembles de métriques connexes (voir Metrics and Segmentation pour la liste des métriques de chaque groupe)
• Granularité: indique le niveau d’agrégation auquel les métriques doivent être renvoyées
• Placement: détermine si les métriques sont extraites pour des publicités diffusées sur X ou en dehors de X
  • Remarque : une seule valeur de placement peut être spécifiée par requête

Utilisez les paramètres de requête start_time et end_time pour définir une plage temporelle. Ces valeurs doivent être alignées avec la granularité spécifiée de la manière suivante.

1. TOTAL : spécifiez n’importe quelle plage temporelle (dans les limites de l’endpoint)
2. DAY : les valeurs d’heure de début et d’heure de fin doivent être alignées sur minuit dans le fuseau horaire du compte
3. HOUR : spécifiez n’importe quelle plage temporelle (dans les limites de l’endpoint)

L’heure de fin est exclusive. Par exemple, une requête avec start_time=2019-01-01T00:00:00Z et end_time=2019-01-02T00:00:00Z renverra une seule journée de métriques d’analytics (et non deux), car cette plage ne couvre qu’une période de 24 heures.

Segmentation

Disponible uniquement via nos endpoints d’analytics asynchrones, la segmentation permet aux partenaires et aux annonceurs de récupérer des métriques ventilées par certaines valeurs de ciblage. Pour demander des métriques segmentées, utilisez le paramètre de requête segmentation_type. Pour plus de détails sur les options de segmentation, voir Metrics and Segmentation.

​

FAQ

Pourquoi les chiffres de la X Ads API ne correspondent-ils pas à ceux affichés dans l’interface X Ads ?

• Assurez-vous d’avoir demandé des données pour tous les emplacements suivants : ALL_ON_TWITTER, PUBLISHER_NETWORK, SPOTLIGHT et TREND.
• N’oubliez pas que les heures de fin dans la X Ads API sont exclusives ; elles sont inclusives dans l’interface Ads.

Pourquoi les chiffres changent-ils selon le moment où je demande des données ?

• Dès que les métriques de reporting sont disponibles, vous pouvez les récupérer. Elles sont disponibles quasi en temps réel. Ces premiers résultats sont toutefois des estimations et sont donc susceptibles d’évoluer. Les métriques sont finalisées après 24 heures, à l’exception des données de dépenses.
• Les métriques de dépenses sont généralement définitives dans les 3 jours suivant l’événement. Toutefois, nous traitons les données de facturation jusqu’à 14 jours après la date de l’événement (par exemple, pour le filtrage du spam).

Comment puis-je déterminer quels id d’entité demander pour une période spécifique ?

• Utilisez l’endpoint Active Entities

Pourquoi toutes les valeurs dans la réponse analytics sont-elles null ?

• Il est probable que la campagne n’ait pas diffusé pendant la période demandée
• Utilisez l’endpoint Active Entities pour déterminer quelles entités récupérer et pour quelle période

Pourquoi l’API affiche-t-elle des valeurs null alors que l’interface affiche des 0 ?

• L’interface choisit d’afficher ces valeurs sous forme de 0, mais les valeurs sont équivalentes.

Comment puis-je demander des métriques associées à un emplacement granulaire, comme la timeline X ?

• Nous prenons en charge les valeurs d’emplacement suivantes dans analytics : ALL_ON_TWITTER, PUBLISHER_NETWORK, SPOTLIGHT et TREND (c.-à-d. la X Audience Platform)

Est-il possible de récupérer des métriques pour des entités supprimées ou mises en pause ?

• Oui. Le statut de l’entité n’a pas d’impact sur la disponibilité des métriques d’analytics.

Pourquoi les valeurs segmentées ne correspondent-elles pas aux valeurs non segmentées ?

• Les données segmentées ne sont pas censées totaliser 100 % des données non segmentées, en raison de la manière dont ces informations sont dérivées.

Est-il possible de demander des données segmentées selon plusieurs dimensions ?

• Nous ne prenons pas en charge la multi-segmentation.

​

Bonnes pratiques

Quelques bonnes pratiques pour collecter des données analytics avec la X Ads API.

​

Limites de taux et nouvelles tentatives

• Pour les requêtes soumises à une limite de taux (celles qui renvoient un code d’état HTTP 429), vous devez consulter l’en-tête x-rate-limit-reset et ne réessayer qu’à l’heure indiquée ou après.
• Pour les requêtes qui renvoient un code d’état HTTP 503 Service Unavailable, vous devez consulter l’en-tête retry-after et ne réessayer qu’après l’heure indiquée.
• Les applications qui ne respectent pas les délais indiqués pour les nouvelles tentatives peuvent voir leur accès à la X Ads API révoqué ou limité sans préavis.

​

Les métriques Analytics en bref

• Toutes les métriques Analytics sont figées et ne changent plus après 24 heures, à l’exception de billed_charge_local_micro.
• La métrique billed_charge_local_micro reste une estimation pendant jusqu’à 3 jours après le renvoi des data.
• Après 24 heures, cette métrique peut diminuer en raison de crédits pour dépassement de dépenses (annonces diffusées après le end_time indiqué) et d’événements facturables identifiés comme indésirables. Cette métrique évolue très peu après 24 heures.
• Veuillez consulter Analytics pour plus d’informations.

​

Récupération de données non segmentées en temps réel

• Indiquez toujours à la fois un start_time et un end_time.
• Ne récupérez pas de données pour des entités âgées de plus de 7 jours.
• Demandez (idéalement) des données avec une granularité HOUR, car vous pouvez toujours agréger et remonter les métriques pour obtenir une granularité DAY et TOTAL.
• Demandez (idéalement) des données aux niveaux line_items et promoted_tweets, car vous pouvez toujours agréger et remonter ces métriques pour obtenir des totaux sur l’ensemble de la hiérarchie des entités publicitaires (c.-à-d. aux niveaux de la campagne, de l’instrument de financement ou du compte).
• Enregistrez et conservez localement les valeurs des métriques d’analytics de votre côté.
• N’interrogez pas de manière répétée des données âgées de plus de 30 jours. Ces données ne changeront pas et doivent être stockées localement.
• Toutes les données non segmentées sont en temps réel et devraient être disponibles quelques secondes après la survenue d’un événement.
• Regroupez les métriques de conversion et les métriques non liées à la conversion dans des requêtes distinctes.

​

Récupération de données segmentées

• Reportez-vous aux lignes directrices ci-dessus pour « Récupération de données en temps réel, non segmentées ». Des recommandations supplémentaires sont fournies ci-dessous.
• Pour la plupart des types de données segmentées, il est possible que les données ne soient pas complètes pendant une période allant jusqu’à 1 heure. Les données segmentées par INTERESTS peuvent être retardées jusqu’à 12 heures.
• Les données segmentées ne devraient pas correspondre à 100 % aux données non segmentées, en raison de la manière dont ces informations sont calculées.

​

Récupération des données historiques

• Lors du backfill des données (c.-à-d. l’ajout d’un nouveau compte annonceur), vous devrez peut-être effectuer plusieurs requêtes par petits segments start_time et end_time.
• Limitez vos récupérations à des fenêtres de 30 jours.
• Répartissez et ralentissez ces requêtes dans le temps afin de ne pas épuiser vos limites de taux pour ces récupérations.

​

Exemple

Vous trouverez un script d’exemple illustrant certaines de ces bonnes pratiques (fetch_stats) dans notre dépôt ads-platform-tools GitHub.

​

Métriques par objectif

Les métriques applicables à une entité dépendent de l’objectif de campagne. Utilisez ce guide pour déterminer quels groupes de métriques récupérer pour chaque type d’objectif, ainsi que la façon de calculer des métriques dérivées supplémentaires.

​

ENGAGEMENTS

Groupes de métriques pertinents : ENGAGEMENT et BILLING. MEDIA s’applique également si des médias sont utilisés dans les créations.

Métrique dérivée	Calcul de la métrique exposée
Taux d’engagement	engagements/impressions
CPE	billed_charge_local_micro/engagements
Taux de vue des médias	media_views/impressions

​

WEBSITE_CLICKS et WEBSITE_CONVERSIONS

Groupes de métriques pertinents : ENGAGEMENT, BILLING et WEB_CONVERSION. MEDIA s’applique également si des médias sont utilisés dans les créations.

Métrique dérivée	Calcul de la métrique exposée
CPM	billed_charge_local_micro/impressions/1000
Taux de clic	clicks/impressions
CPLC	billed_charge_local_micro/clicks
Conversions totales	conversion_custom + conversion_site_visits + conversion_sign_ups + conversion_downloads + conversion_purchases
Taux de conversion	Conversions totales / impressions
CPA	billed_charge_local_micro / Conversions totales

​

APP_INSTALLS et APP_ENGAGEMENTS

Groupes de métriques pertinents :ENGAGEMENT, BILLING, MOBILE_CONVERSION et LIFE_TIME_VALUE_MOBILE_CONVERSION. MEDIA et VIDEO s’appliquent également si une App Card média ou vidéo est utilisée dans les créations.

Métrique dérivée	Calcul de la métrique exposée
CPM	billed_charge_local_micro/impressions/1000
Taux de clics sur l’App	app_clicks/impressions
CPAC	billed_charge_local_micro/app_clicks
CPI	billed_charge_local_micro/mobile_conversion_installs

​

FOLLOWERS

Groupes de métriques pertinents : ENGAGEMENT et BILLING. MEDIA s’applique également si des médias sont utilisés dans les créations.

Métrique dérivée	Calcul de la métrique exposée
CPM	billed_charge_local_micro/impressions/1000
Taux d’abonnés	follows/impressions
CPF	billed_charge_local_micro/follows
Taux de vues des médias	media_views/impressions

​

LEAD_GENERATION

Groupes de métriques pertinents : ENGAGEMENT et BILLING. MEDIA s’applique également si des médias sont utilisés dans les créations.

Métrique dérivée	Calcul de la métrique exposée
CPM	billed_charge_local_micro/impressions/1000
Prospects	card_engagements
Taux de prospects	card_engagements/impressions
Coût par prospect	billed_charge_local_micro/card_engagements

​

VIDEO_VIEWS

Groupes de métriques pertinents : ENGAGEMENT, BILLING et VIDEO.

Métrique dérivée	Calcul de la métrique exposée
CPM	billed_charge_local_micro/impressions/1000
Taux de vidéo	video_total_views/impressions
Coût par vue	billed_charge_local_micro/video_total_views

​

VIDEO_VIEWS_PREROLL

Groupes de mesures pertinents : ENGAGEMENT, BILLING et VIDEO.

Mesure dérivée	Calcul de la mesure exposée
CPM	billed_charge_local_micro/impressions/1000
Taux de lecture vidéo	video_total_views/impressions
Coût par vue	billed_charge_local_micro/video_total_views

​

Métriques et segmentation

Ce document présente un aperçu des métriques disponibles dans nos Analytics pour chaque type d’entité, ainsi que des segmentations disponibles pour chaque métrique.

	Groupes de métriques
Entité	ENGAGEMENT	BILLING	VIDEO	MEDIA	WEB_CONVERSION	MOBILE_CONVERSION	LIFE_TIME_VALUE_MOBILE_CONVERSION
ACCOUNT	✔*
FUNDING_INSTRUMENT	✔*	✔
CAMPAIGN	✔	✔	✔	✔	✔	✔	✔
LINE_ITEM	✔	✔	✔	✔	✔	✔	✔
PROMOTED_TWEET	✔	✔	✔	✔	✔	✔	✔
MEDIA_CREATIVE	✔	✔	✔	✔	✔	✔	✔
ORGANIC_TWEET	✔		✔

*Certaines métriques de la famille ENGAGEMENT ne sont pas disponibles au niveau du compte et de l’instrument de financement. Voir la section ENGAGEMENT pour plus de détails.

​

Métriques disponibles par groupe de métriques

​

ENGAGEMENT

Metric	Description	Segmentation disponible	Type de données	Disponible pour Compte / Instrument de financement
engagements	Nombre total d’engagements	✔	Tableau d’entiers	✔
impressions	Nombre total d’impressions	✔	Tableau d’entiers	✔
retweets	Nombre total de Retweets	✔	Tableau d’entiers	✔
replies	Nombre total de réponses	✔	Tableau d’entiers	✔
likes	Nombre total de likes	✔	Tableau d’entiers	✔
follows	Nombre total d’abonnements	✔	Tableau d’entiers	✔
card_engagements	Nombre total d’engagements sur la carte	✔	Tableau d’entiers
clicks	Nombre total de clics, y compris les likes et autres engagements	✔	Tableau d’entiers
app_clicks	Nombre de tentatives d’installation ou d’ouverture de l’App	✔	Tableau d’entiers
url_clicks	Nombre total de clics sur le lien ou la Website Card dans une annonce, y compris les clics gagnés	✔	Tableau d’entiers
qualified_impressions	Nombre total d’impressions qualifiées	✔	Tableau d’entiers
carousel_swipes	Nombre total de balayages sur les images ou vidéos du carrousel	✔	Tableau d’entiers

​

BILLING

Mesure	Description	Segmentation disponible	Type de données
billed_engagements	Nombre total d’engagements facturés	✔	Tableau d’entiers
billed_charge_local_micro	Dépense totale en micros	✔	Tableau d’entiers

​

VIDEO

Avis concernant les changements de définition des métriques vidéo :

La métrique video_total_views au sein du groupe de métriques VIDEO comptabilisera toute vue avec au moins 50 % du player à l’écran pendant 2 secondes, conformément au standard MRC.

Notre définition initiale d’une vue vidéo, à savoir 100 % à l’écran pendant au moins 3 secondes, restera disponible en tant que nouvelle métrique video_3s100pct_views dans le groupe de métriques VIDEO. Pour continuer à enchérir et être facturé sur la base de la définition d’origine, utilisez l’unité d’enchère nouvellement disponible VIEW_3S_100PCT.

Metric	Description	Segmentation disponible	Type de données
video_total_views	Nombre total de vues vidéo	✔	Tableau d’entiers
video_views_25	Nombre total de vues où au moins 25 % de la vidéo a été visionné	✔	Tableau d’entiers
video_views_50	Nombre total de vues où au moins 50 % de la vidéo a été visionné	✔	Tableau d’entiers
video_views_75	Nombre total de vues où au moins 75 % de la vidéo a été visionné	✔	Tableau d’entiers
video_views_100	Nombre total de vues où 100 % de la vidéo a été visionné	✔	Tableau d’entiers
video_cta_clicks	Nombre total de clics sur l’appel à l’action	✔	Tableau d’entiers
video_content_starts	Nombre total de démarrages de lecture vidéo	✔	Tableau d’entiers
video_3s100pct_views	Nombre total de vues avec au moins 3 secondes lues tout en étant 100 % à l’écran (ancienne video_total_views)	✔	Tableau d’entiers
video_6s_views	Nombre total de vues où au moins 6 secondes de la vidéo ont été visionnées	✔	Tableau d’entiers
video_15s_views	Nombre total de vues où au moins 15 secondes de la vidéo, ou 95 % de la durée totale, ont été visionnées	✔	Tableau d’entiers

​

MEDIA

Mesure	Description	Segmentation disponible	Type de données
media_views	Nombre total de vues (lecture automatique et clic) des médias sur les vidéos, Vines, GIF et images.	✔	Tableau d’entiers
media_engagements	Nombre total de clics sur les médias sur les vidéos, Vines, GIF et images.	✔	Tableau d’entiers

​

WEB_CONVERSION

Indicateur	Description	Segmentation disponible	Type de données
conversion_purchases	Nombre de conversions de type PURCHASE, ainsi que le montant des ventes et la quantité de commandes correspondants	PLATFORMS uniquement	Objet JSON
conversion_sign_ups	Nombre de conversions de type SIGN_UP, ainsi que le montant des ventes et la quantité de commandes correspondants	PLATFORMS uniquement	Objet JSON
conversion_site_visits	Nombre de conversions de type SITE_VISIT, ainsi que le montant des ventes et la quantité de commandes correspondants	PLATFORMS uniquement	Objet JSON
conversion_downloads	Nombre de conversions de type DOWNLOAD, ainsi que le montant des ventes et la quantité de commandes correspondants	PLATFORMS uniquement	Objet JSON
conversion_custom	Nombre de conversions de type CUSTOM, ainsi que le montant des ventes et la quantité de commandes correspondants	PLATFORMS uniquement	Objet JSON

​

MOBILE_CONVERSION

Les statistiques de conversion mobile sont disponibles uniquement pour les comptes annonceurs activés pour MACT.

Métrique	Description	Segmentation disponible	Type de données
mobile_conversion_spent_credits	Répartition des conversions mobiles de type SPENT_CREDIT par post_view, post_engagement, assisted, order_quantity et sale_amount	✔	Objet JSON
mobile_conversion_installs	Répartition des conversions mobiles de type INSTALL par post_view, post_engagement, assisted, order_quantity et sale_amount	✔	Objet JSON
mobile_conversion_content_views	Répartition des conversions mobiles de type CONTENT_VIEW par post_view, post_engagement, assisted, order_quantity et sale_amount	✔	Objet JSON
mobile_conversion_add_to_wishlists	Répartition des conversions mobiles de type ADD_TO_WISHLIST par post_view, post_engagement, assisted, order_quantity et sale_amount	✔	Objet JSON
mobile_conversion_checkouts_initiated	Répartition des conversions mobiles de type CHECKOUT_INITIATED par post_view, post_engagement, assisted, order_quantity et sale_amount	✔	Objet JSON
mobile_conversion_reservations	Répartition des conversions mobiles de type RESERVATION par post_view, post_engagement, assisted, order_quantity et sale_amount	✔	Objet JSON
mobile_conversion_tutorials_completed	Répartition des conversions mobiles de type TUTORIAL_COMPLETED par post_view, post_engagement, assisted, order_quantity et sale_amount	✔	Objet JSON
mobile_conversion_achievements_unlocked	Répartition des conversions mobiles de type ACHIEVEMENT_UNLOCKED par post_view, post_engagement, assisted, order_quantity et sale_amount	✔	Objet JSON
mobile_conversion_searches	Répartition des conversions mobiles de type SEARCH par post_view, post_engagement, assisted, order_quantity et sale_amount	✔	Objet JSON
mobile_conversion_add_to_carts	Répartition des conversions mobiles de type ADD_TO_CART par post_view, post_engagement, assisted, order_quantity et sale_amount	✔	Objet JSON
mobile_conversion_payment_info_additions	Répartition des conversions mobiles de type PAYMENT_INFO_ADDITION par post_view, post_engagement, assisted, order_quantity et sale_amount	✔	Objet JSON
mobile_conversion_re_engages	Répartition des conversions mobiles de type RE_ENGAGE par post_view, post_engagement, assisted, order_quantity et sale_amount	✔	Objet JSON
mobile_conversion_shares	Répartition des conversions mobiles de type SHARE par post_view, post_engagement, assisted, order_quantity et sale_amount	✔	Objet JSON
mobile_conversion_rates	Répartition des conversions mobiles de type RATE par post_view, post_engagement, assisted, order_quantity et sale_amount	✔	Objet JSON
mobile_conversion_logins	Répartition des conversions mobiles de type LOGIN par post_view, post_engagement, assisted, order_quantity et sale_amount	✔	Objet JSON
mobile_conversion_updates	Répartition des conversions mobiles de type UPDATE par post_view, post_engagement, assisted, order_quantity et sale_amount	✔	Objet JSON
mobile_conversion_levels_achieved	Répartition des conversions mobiles de type LEVEL_ACHIEVED par post_view, post_engagement, assisted, order_quantity et sale_amount	✔	Objet JSON
mobile_conversion_invites	Répartition des conversions mobiles de type INVITE par post_view, post_engagement, assisted, order_quantity et sale_amount	✔	Objet JSON
mobile_conversion_key_page_views	Répartition des conversions mobiles de type KEY_PAGE_VIEW par post_view et post_engagement	✔	Objet JSON
mobile_conversion_downloads	Répartition des conversions mobiles de type DOWNLOAD par post_view, post_engagement, assisted, order_quantity et sale_amount	✔	Objet JSON
mobile_conversion_purchases	Répartition des conversions mobiles de type PURCHASE par post_view, post_engagement, assisted, order_quantity et sale_amount	✔	Objet JSON
mobile_conversion_sign_ups	Répartition des conversions mobiles de type SIGN_UP par post_view, post_engagement, assisted, order_quantity et sale_amount	✔	Objet JSON
mobile_conversion_site_visits	Répartition des conversions mobiles de type SITE_VISIT par post_view, post_engagement, assisted, order_quantity et sale_amount	✔	Objet JSON

​

LIFE_TIME_VALUE_MOBILE_CONVERSION

Les statistiques de conversions mobiles sur la durée de vie ne sont disponibles que pour les comptes annonceurs activés pour MACT.

Metric	Description	Segmentation Available	Data Type
mobile_conversion_lifetime_value_purchases	Ventilation des conversions mobiles de type PURCHASE		Objet JSON
mobile_conversion_lifetime_value_sign_ups	Ventilation des conversions mobiles de type SIGN_UP		Objet JSON
mobile_conversion_lifetime_value_updates	Ventilation des conversions mobiles de type UPDATE		Objet JSON
mobile_conversion_lifetime_value_tutorials_completed	Ventilation des conversions mobiles de type TUTORIAL_COMPLETED		Objet JSON
mobile_conversion_lifetime_value_reservations	Ventilation des conversions mobiles de type RESERVATION		Objet JSON
mobile_conversion_lifetime_value_add_to_carts	Ventilation des conversions mobiles de type ADD_TO_CART		Objet JSON
mobile_conversion_lifetime_value_add_to_wishlists	Ventilation des conversions mobiles de type ADD_TO_WISHLIST		Objet JSON
mobile_conversion_lifetime_value_checkouts_initiated	Ventilation des conversions mobiles de type CHECKOUT_INITIATED		Objet JSON
mobile_conversion_lifetime_value_levels_achieved	Ventilation des conversions mobiles de type LEVEL_ACHIEVED		Objet JSON
mobile_conversion_lifetime_value_achievements_unlocked	Ventilation des conversions mobiles de type ACHIEVEMENT_UNLOCKED		Objet JSON
mobile_conversion_lifetime_value_shares	Ventilation des conversions mobiles de type SHARE		Objet JSON
mobile_conversion_lifetime_value_invites	Ventilation des conversions mobiles de type INVITE		Objet JSON
mobile_conversion_lifetime_value_payment_info_additions	Ventilation des conversions mobiles de type PAYMENT_INFO_ADDITION		Objet JSON
mobile_conversion_lifetime_value_spent_credits	Ventilation des conversions mobiles de type SPENT_CREDIT		Objet JSON
mobile_conversion_lifetime_value_rates	Ventilation des conversions mobiles de type RATE		Objet JSON

​

Segmentation

Les rapports de segmentation permettent de récupérer des métriques ventilées selon les valeurs d’un type de ciblage donné. La segmentation n’est disponible que via des requêtes d’analytique asynchrones en raison de leur complexité accrue.

La segmentation n’est pas prise en charge pour les entités MEDIA_CREATIVE ou ORGANIC_TWEET.

Certains types de segmentation nécessitent des paramètres supplémentaires. Ils sont documentés ci-dessous.

Lors d’une segmentation par CITIES ou POSTAL_CODES, l’API ne renverra que les emplacements ciblés. La segmentation par région et par zone métropolitaine renverra à la fois les emplacements ciblés et non ciblés.

Type de segmentation	paramètre country requis	paramètre platform requis
AGE
APP_STORE_CATEGORY
AUDIENCES
CITIES	✔
CONVERSATIONS
CONVERSION_TAGS
DEVICES		✔
EVENTS
GENDER
INTERESTS
KEYWORDS
LANGUAGES
LOCATIONS
METROS	✔
PLATFORMS
PLATFORM_VERSIONS		✔
POSTAL_CODES	✔
REGIONS	✔
SLIDES
SIMILAR_TO_FOLLOWERS_OF_USER
TV_SHOWS

​

Métriques dérivées

Les métriques d’une campagne dépendent de son objectif de campagne. Utilisez ce guide pour déterminer comment calculer les métriques dérivées à utiliser selon les objectifs en vigueur.

Toute metric sans accolades est une métrique renvoyée par les endpoints analytics de la X Ads API. Tout nom entouré de {accolades} indique une métrique dérivée pour cette catégorie.

​

ENGAGEMENTS

Mesure dérivée	Calcul de la mesure exposée
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions
billed_charge_local_micro / {Impressions} / 1000
{Total des engagements}	promoted_account_follows + promoted_tweet_search_engagements + promoted_tweet_timeline_engagements + promoted_tweet_profile_engagements ou promoted_account_follows + promoted_tweet_search_clicks + promoted_tweet_search_replies + promoted_tweet_search_retweets + promoted_tweet_search_follows + promoted_tweet_timeline_clicks + promoted_tweet_timeline_replies + promoted_tweet_timeline_retweets + promoted_tweet_timeline_follows + promoted_tweet_profile_clicks + promoted_tweet_profile_replies + promoted_tweet_profile_retweets + promoted_tweet_profile_follows
{Taux d’engagement}	{Total des engagements} / {Impressions}
billed_charge_local_micro / {Total des engagements}
{Vues de média}	promoted_tweet_timeline_media_views + promoted_tweet_search_media_views + promoted_tweet_profile_media_views
{Taux de vues de média}	{Vues de média} / {Impressions}

​

WEBSITE_CLICKS

Indicateur dérivé	Calcul de l’indicateur exposé
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions
billed_charge_local_micro / {Impressions} / 1000
{Clics sur lien}	promoted_tweet_search_url_clicks + promoted_tweet_timeline_url_clicks + promoted_tweet_profile_url_clicks
{Taux de clics}	{Clics sur lien} / {Impressions}
billed_charge_local_micro / {Clics sur lien}
conversion_site_visits
{Taux de conversion}	conversion_site_visits / {Impressions}
billed_charge_local_micro / conversion_site_visits

​

APP_INSTALLS et APP_ENGAGEMENTS

Indicateur dérivé	Calcul de l’indicateur exposé
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions
billed_charge_local_micro / {Impressions} / 1000
{App Clicks}	promoted_tweet_app_install_attempts + promoted_tweet_app_open_attempts + promoted_tweet_timeline_url_clicks + promoted_tweet_search_url_clicks
{App Click Rate}	{App Clicks} / {Impressions}
billed_charge_local_micro / {App Clicks}
billed_charge_local_micro / mobile_conversion_installs

​

ABONNÉS

Indicateur dérivé	Calcul de l’indicateur exposé
promoted_account_impressions
billed_charge_local_micro / {Impressions} / 1000
promoted_account_follows
{Taux d’abonnement}	promoted_account_follow_rate
billed_charge_local_micro / promoted_account_follows
{Vues média}	promoted_tweet_timeline_media_views + promoted_tweet_search_media_views + promoted_tweet_profile_media_views
{Taux de vues média}	{Media Views} / {Impressions}

​

LEAD_GENERATION

Métrique dérivée	Calcul de la métrique exposée
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions
billed_charge_local_micro / {Impressions} / 1000
promoted_tweet_search_card_engagements + promoted_tweet_timeline_card_engagements + promoted_tweet_profile_card_engagements
{Taux de leads}	{Leads} / {Impressions}
{Coût par lead}	billed_charge_local_micro / {Leads}

​

VIDEO_VIEWS

Indicateur dérivé	Calcul de l’indicateur exposé
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions
billed_charge_local_micro / {Impressions} / 1000
{Vues vidéo}	promoted_video_total_views
{Taux de vue vidéo}	promoted_video_total_views / {Impressions}
{Coût par vue}	billed_charge_local_micro / promoted_video_total_views

​

QUALIFIED_IMPRESSIONS

Indicateur dérivé	Calcul de l’indicateur affiché
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions
billed_charge_local_micro / {Impressions} / 1000
{Qualified Impressions}	promoted_tweet_timeline_qualified_impressions + promoted_tweet_search_qualified_impressions + promoted_tweet_profile_qualified_impressions
{Qualified Impression Rate}	{Qualified Impressions} / {Impressions}
{Cost Per 1000 Qualified Impressions }	billed_charge_local_micro / {Qualified Impressions} / 1000

​

PERSONNALISÉ

Pour le placement_type PROMOTED_ACCOUNT, consultez l’objectif FOLLOWERS ci-dessus. Pour tous les autres emplacements avec cet objectif, consultez ENGAGEMENTS pour les métriques dérivées correspondantes.

​

Guides

​

Entités actives

​

Introduction

L’endpoint Active Entities est conçu pour être utilisé avec nos endpoints d’analytique synchrones et asynchrones, car il indique pour quelles campagnes demander des analyses. Il y parvient en renvoyant des détails sur les entités publicitaires et les moments où leurs métriques ont changé. L’utilisation de cet endpoint simplifiera considérablement votre code et votre logique de récupération des analyses.

Ce guide fournit des informations et du contexte sur l’endpoint et sa source de données. Il propose également des directives d’utilisation et une série d’exemples de requêtes montrant comment utiliser Active Entities avec nos endpoints d’analytique. La section Résumé présente une description de haut niveau de l’approche recommandée.

​

Données

Chaque fois qu’une métrique d’entité publicitaire est modifiée, nous enregistrons des informations sur cette modification. Ces événements de modification sont stockés par tranches horaires et incluent des détails sur l’entité ainsi que l’heure à laquelle la modification s’applique. Ce dernier point est nécessaire, car les événements de modification ne correspondent pas toujours au moment où ils ont été enregistrés. Les ajustements de facturation en sont une raison fréquente, entre autres.

​

Endpoint

​

Requête

Les requêtes Active Entities sont limitées aux comptes publicitaires et comportent trois paramètres de requête obligatoires : entity, start_time et end_time.

twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t/active_entities?entity=PROMOTED_TWEET&start_time=2019-03-05T00:00:00Z&end_time=2019-03-06T00:00:00Z"

Les valeurs suivantes pour entity sont prises en charge : CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE, PROMOTED_ACCOUNT et PROMOTED_TWEET. Cela reflète les types d’entités pris en charge par nos endpoints d’analytics.

Les valeurs start_time et end_time doivent être exprimées au format ISO 8601 et préciser quels regroupements horaires interroger. Elles doivent être exprimées en heures pleines.

Cet endpoint prend également en charge trois paramètres optionnels pouvant être utilisés pour filtrer les résultats : funding_instrument_ids, campaign_ids et line_item_ids. Ceux-ci fonctionnent à tous les niveaux de la hiérarchie publicitaire et avec tout type d’entity spécifié.

​

Réponse

La réponse Active Entities pour la requête ci-dessus est présentée ci-dessous.

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "entity": "PROMOTED_TWEET",
          "start_time": "2019-03-05T00:00:00Z",
          "end_time": "2019-03-06T00:00:00Z"
        }
      },
      "data": [
        {
          "entity_id": "2r0wxw",
          "activity_start_time": "2019-03-04T20:55:20Z",
          "activity_end_time": "2019-03-05T03:43:56Z",
          "placements": [
            "ALL_ON_TWITTER"
          ]
        },
        {
          "entity_id": "2r30fn",
          "activity_start_time": "2019-03-05T08:11:08Z",
          "activity_end_time": "2019-03-05T14:40:59Z",
          "placements": [
            "ALL_ON_TWITTER",
            "PUBLISHER_NETWORK"
          ]
        }
      ]
    }

Le tableau data contient un objet pour chaque entité devant être incluse dans une requête d’analytique ultérieure. Vous ne devez pas demander des analyses pour des id en dehors de cet ensemble.

Chaque objet comporte quatre fields : entity_id, activity_start_time, activity_end_time et placements. Les heures de début et de fin d’activité représentent l’intervalle temporel auquel s’appliquent les événements de modification de l’entité associée et déterminent donc les dates à spécifier dans les requêtes d’analytique ultérieures. Le tableau placements peut contenir les valeurs suivantes : ALL_ON_TWITTER, PUBLISHER_NETWORK, SPOTLIGHT et TREND. Il indique quels emplacements doivent être demandés pour l’id de l’entité donnée.

​

Utilisation

L’endpoint Active Entities doit déterminer la manière dont les requêtes d’analytique sont effectuées. Les consignes d’utilisation suivantes visent à faciliter la synchronisation des analyses, permettant aux partenaires de maintenir leurs data stores synchronisés avec Twitter. En d’autres termes, elles décrivent comment effectuer des synchronisations planifiées en arrière-plan à intervalles réguliers.

Deux décisions s’imposent au développeur.

1. À quelle fréquence demander les informations sur les entités actives et, par conséquent, à quelle fréquence extraire les analyses.
2. Comment utiliser les heures de début et de fin d’activité pour déterminer les valeurs start_time et end_time de la requête d’analytique.

Ces points sont abordés plus en détail dans chacune des deux sous-sections ci-dessous, après le résumé.

​

Résumé

Utilisez l’endpoint Active Entities comme suit pour définir la façon d’effectuer les requêtes d’analytique. Appliquez cette procédure après avoir déterminé la fréquence de récupération des informations sur les entités actives et, par conséquent, des analytics.

1. Envoyez la requête Active Entities.
2. Scindez la réponse par placement : un groupe pour ALL_ON_TWITTER, un pour PUBLISHER_NETWORK, un pour SPOTLIGHT et un pour TREND.
3. Pour chaque groupe de placement, procédez comme suit.
   1. Extrayez les id des entités.
   2. Déterminez les valeurs de start_time et end_time pour l’analytique.
      • Trouvez la valeur minimale de activity_start_time. Arrondissez-la à l’inférieur.
      • Trouvez la valeur maximale de activity_end_time. Arrondissez-la à la hausse.
   3. Effectuez la ou les requêtes d’analytique.
      • Regroupez les id d’entités par lots de 20.
      • Utilisez les valeurs de start_time et end_time de l’étape 3b.
      • Spécifiez la valeur de placement appropriée.
   4. Écrivez dans votre magasin de données.

Veuillez consulter active_entities.py pour un exemple utilisant le SDK Python.

​

Fréquence

La réponse à la première question détermine l’intervalle de temps à utiliser dans les requêtes Active Entities. Par exemple, si vous demandez des informations sur les entités actives toutes les heures, l’intervalle doit être d’une heure. Si vous demandez des informations sur les entités actives une fois par jour, l’intervalle doit être d’une journée. En d’autres termes, les intervalles doivent être choisis de sorte que le start_time de la requête actuelle soit égal au end_time de la requête précédente.

Remarque : Une fenêtre temporelle ne doit être demandée qu’une seule fois. Demander une fenêtre temporelle plus d’une fois entraînera des requêtes d’analyse inutiles. (Exception ci-dessous.)

Pour les partenaires souhaitant demander des analyses plusieurs fois par heure pour l’heure en cours, le même principe s’applique — la fréquence détermine l’intervalle de temps. Le tableau ci-dessous présente des exemples d’horodatages de début et de fin Active Entities pour ce scénario.

Heure de la requête	Horodatage start_time	Horodatage end_time
00:15:00	00:00:00	00:15:00
00:30:00	00:15:00	00:30:00
00:45:00	00:30:00	00:45:00
01:00:00	00:45:00	01:00:00

Compte tenu de la façon dont les événements de modification sont stockés, les quatre requêtes Active Entities ci-dessus interrogent le même compartiment horaire, ce qui est nécessaire pour ce cas d’usage. Toutefois, une fois l’heure en cours terminée, ce compartiment horaire ne doit plus être interrogé.

​

Heures d’activité

Nous recommandons l’approche suivante pour gérer les heures de début et de fin d’activité. Dans tous les objets de la réponse Active Entities, identifiez la valeur minimale de activity_start_time et la valeur maximale de activity_end_time. Modifiez ces valeurs en arrondissant l’heure de début minimale à la baisse et l’heure de fin maximale à la hausse. Plus précisément, définissez les heures, minutes et secondes des horodatages sur zéro, puis ajoutez un jour à l’heure de fin, comme illustré dans le tableau suivant. Ce sont les heures de début et de fin qui doivent être utilisées dans les requêtes d’analytique ultérieures.

Heures d’activité min., max.	Heures dérivées
2019-03-04T20:55:20Z 2019-03-05T14:40:59Z	2019-03-04T00:00:00Z 2019-03-06T00:00:00Z

Remarque : Il est important d’inclure les horodatages avec les heures, minutes et secondes réglées sur zéro. Sinon, si seule la date est transmise, nous supposerons que vous demandez des analyses commençant et se terminant à minuit dans le fuseau horaire du compte publicitaire, ce qui peut ne pas être souhaitable. Par exemple, si l’heure de début minimale de l’activité est 2019-02-28T01:30:07Z et que l’horodatage est omis pour un compte publicitaire avec un décalage de -08:00:00, la requête d’analytique manquera les changements survenus entre 01:30 et 08:00.

Sinon, si vous préférez demander des analyses uniquement pour la fenêtre temporelle d’activité renvoyée, sans l’étendre à des journées complètes, vous pouvez. Avec cette approche, les heures de début et de fin dérivées seraient respectivement 2019-03-04T20:00:00Z et 2019-03-05T15:00:00Z. (Notez que de telles plages ne sont pas acceptées si vous spécifiez la granularité DAY dans la requête d’analytique.)

​

Exemple

Cette section illustre l’utilisation d’Active Entities avec l’endpoint d’analytics synchrone. (Les réponses ont été légèrement modifiées pour en améliorer la lisibilité.) Dans cet exemple, l’endpoint Active Entities est appelé au début de chaque heure, chaque requête couvrant l’heure précédente. La réponse détermine la manière dont l’endpoint d’analytics synchrone est utilisé.

La première requête Active Entities est effectuée à 03:00:00. La réponse indique que les métriques du line item dvcz7 ont changé et que ces événements de modification s’appliquent à la fenêtre comprise entre 02:02:55 et 02:28:12.

`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2019-02-11T02:00:00Z&end_time=2019-02-11T03:00:00Z"`

    {
      "request": {},
      "data": [
        {
          "entity_id": "dvcz7",
          "activity_start_time": "2019-02-11T02:02:55Z",
          "activity_end_time": "2019-02-11T02:58:12Z",
          "placements": [
            "ALL_ON_TWITTER"
          ]
        }
      ]
    }

Sur la base de ces heures de début et de fin d’activité et en suivant l’approche décrite ci-dessus, les valeurs d’analytics start_time et end_time sont respectivement définies sur 2019-02-11T00:00:00Z et 2019-02-12T00:00:00Z. Nous constatons que le troisième élément de chacun des tableaux de métriques ci-dessous est non nul, comme prévu d’après les informations sur les entités actives.

`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=dvcz7&start_time=2019-02-11T00:00:00Z&end_time=2019-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"`

    {
      "data_type": "stats",
      "time_series_length": 24,
      "data": [
        {
          "id": "dvcz7",
          "id_data": [
            {
              "segment": null,
              "metrics": {
                "impressions": [
                  0,0,2792,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ],
                "engagements": [
                  0,0,60,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ],
                "video_total_views": [
                  0,0,1326,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ]
              }
            }
          ]
        }
      ],
      "request": {}
    }

La prochaine requête Active Entities a lieu à 04:00:00 et ne porte que sur l’heure précédente. Comme mentionné ci-dessus, un créneau horaire ne doit être demandé qu’une seule fois. D’après la réponse, nous constatons que les événements de modification pour cet élément de ligne s’appliquent à 02:00:00 et 03:00:00. Dans la requête d’analytique suivante, nous nous attendons à voir des changements pour les deux heures.

`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t/active_entities?entity= LINE_ITEM&start_time=2019-02-11T03:00:00Z&end_time=2019-02-11T04:00:00Z"`

    {
      "request": {},
      "data": [
        {
          "entity_id": "dvcz7",
          "activity_start_time": "2019-02-11T02:07:17Z",
          "activity_end_time": "2019-02-11T03:49:22Z",
          "placements": [
            "ALL_ON_TWITTER"
          ]
        }
      ]
    }

En plus d’observer des métriques non nulles pour 03:00:00, nous constatons que les impressions, les dépenses et les vues vidéo MRC ont été mises à jour par rapport à leurs valeurs précédentes. Les impressions, par exemple, s’élèvent désormais à 2 995 pour l’intervalle 02:00:00, contre 2 792 auparavant. Cela montre comment les événements de modification enregistrés durant l’intervalle 03:00:00 s’appliquent à l’intervalle 02:00:00.

`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=dvcz7&start_time=2019-02-11T00:00:00Z&end_time=2019-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"`

    {
      "data_type": "stats",
      "time_series_length": 24,
      "data": [
        {
          "id": "dvcz7",
          "id_data": [
            {
              "segment": null,
              "metrics": {
                "impressions": [
                  0,0,2995,734,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ],
                "engagements": [
                  0,0,65,7,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ],
                "video_total_views": [
                  0,0,1449,342,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ]
              }
            }
          ]
        }
      ],
      "request": {}
    }

La requête Active Entities à 05:00:00, en examinant à nouveau uniquement l’heure précédente, indique que les événements de modification s’appliquent uniquement à l’heure de 03:00:00. Les changements des métriques d’analyse dans la requête suivante le reflètent.

`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2019-02-11T04:00:00Z&end_time=2019-02-11T05:00:00Z"`

    {
      "request": {},
      "data": [
        {
          "entity_id": "dvcz7",
          "activity_start_time": "2019-02-11T03:42:39Z",
          "activity_end_time": "2019-02-11T03:48:48Z",
          "placements": [
            "ALL_ON_TWITTER"
          ]
        }
      ]
    }

La réponse d’analytics indique que seules les métriques de 03:00:00 ont changé ; les valeurs de 02:00:00 sont identiques à celles de la précédente requête d’analytics.

`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids= dvcz7&start_time=2019-02-11T00:00:00Z&end_time=2019-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"`

    {
      "data_type": "stats",
      "time_series_length": 24,
      "data": [
        {
          "id": "dvcz7",
          "id_data": [
            {
              "segment": null,
              "metrics": {
                "impressions": [
                  0,0,2995,753,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ],
                "engagements": [
                  0,0,65,8,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ],
                "video_total_views": [
                  0,0,1449,351,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ]
              }
            }
          ]
        }
      ],
      "request": {}
    }

Enfin, à 06:00:00, nous constatons qu’il n’y a pas d’événements de changement supplémentaires. Remarque : Cela n’implique toutefois pas que les métriques de cet élément de campagne ne puissent pas évoluer à l’avenir.

`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2019-02-11T05:00:00Z&end_time=2019-02-11T06:00:00Z"`

    {
      "request": {},
      "data": []
    }

​

Guide asynchrone

​

Référence de l’API

​

Analytique asynchrone

​

Introduction

Les endpoints d’analytique asynchrones permettent aux partenaires et aux annonceurs de demander des métriques en soumettant des requêtes de création que le serveur traite de manière asynchrone. (Nous appelons cela des « jobs » d’analytique asynchrones.) Avec cette approche, la connexion du client n’a pas besoin de rester ouverte jusqu’à l’exécution de la requête.

Ces endpoints, comme leurs homologues synchrones, permettent aux partenaires et aux annonceurs de demander des statistiques détaillées sur les performances des campagnes. Ils prennent en charge la demande de data pour les comptes, instruments de financement, campagnes, éléments de ligne, Tweets sponsorisés et créations média. La différence avec l’endpoint synchrone est que les endpoints d’analytique asynchrones prennent en charge des plages de dates plus longues, jusqu’à 90 jours, ainsi que la segmentation. Des informations supplémentaires sur les différences entre les deux sont disponibles sur notre page Présentation de l’Analytics.

Contrairement à nos endpoints synchrones, la limite de taux est basée sur le nombre de jobs simultanés pour un compte donné. Autrement dit, elle dépend du nombre de jobs pouvant être en cours de traitement à un moment donné. Nous comptabilisons cela au niveau du compte publicitaire.

​

Utilisation

La récupération des métriques de campagne à l’aide des endpoints d’analytique asynchrones se fait en plusieurs étapes. Elle consiste à créer une tâche, vérifier si son traitement est terminé, puis télécharger les données. Le fichier de données doit être décompressé. Les quatre étapes spécifiques sont décrites ci-dessous.

1. Créez la tâche à l’aide de l’endpoint POST stats/jobs/accounts/:account_id.
2. Effectuez des requêtes à intervalles réguliers vers l’endpoint GET stats/jobs/accounts/:account_id pour déterminer si la tâche a terminé son traitement.
3. Une fois le traitement de la tâche terminé, téléchargez le fichier de données.
4. Décompressez le fichier de données.

L’objet de réponse renvoyé dans le fichier de données a le même schéma JSON que la réponse de l’endpoint d’analytique synchrone.

Les métriques de campagne segmentées ne sont disponibles que via les endpoints d’analytique asynchrones. Les métriques de campagne peuvent être ventilées par emplacement, sexe, centres d’intérêt, mots‑clés, et plus encore. Pour la liste complète des options, consultez la page Metrics and Segmentation. Pour demander des métriques segmentées, utilisez le paramètre de requête segmentation_type lors de la création de la tâche.

​

Exemple

Cette section explique comment utiliser les endpoints d’analytique asynchrones.

Commencez par créer un job à l’aide de l’endpoint POST stats/jobs/accounts/:account_id. L’exemple ci-dessous demande des métriques d’engagement — telles que les impressions, les likes, les clics, etc. — pour un élément de ligne spécifique sur une période d’une semaine. (Notez que l’intervalle de temps demandé va jusqu’au 20 mars inclus, mais sans inclure le 20 mars lui-même, car l’horodatage est fixé à minuit.)

$ twurl -X POST -H ads-api.x.com "/9/stats/jobs/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=el32n&start_time=2019-03-12T00:00:00Z&end_time=2019-03-20T00:00:00Z&granularity=TOTAL&placement=ALL_ON_TWITTER&metric_groups=ENGAGEMENT"

    {
      "request": {
        "params": {
          "start_time": "2019-03-12T00:00:00Z",
          "entity_ids": [
            "el32n"
          ],
          "end_time": "2019-03-20T00:00:00Z",
          "placement": "ALL_ON_TWITTER",
          "granularity": "TOTAL",
          "entity": "LINE_ITEM",
          "metric_groups": [
            "ENGAGEMENT"
          ]
        }
      },
      "data": {
        "start_time": "2019-03-12T00:00:00Z",
        "segmentation_type": null,
        "url": null,
        "id_str": "1120829647711653888",
        "entity_ids": [
          "el32n"
        ],
        "end_time": "2019-03-20T00:00:00Z",
        "country": null,
        "placement": "ALL_ON_TWITTER",
        "id": 1120829647711653888,
        "expires_at": null,
        "account_id": "18ce54d4x5t",
        "status": "PROCESSING",
        "granularity": "TOTAL",
        "entity": "LINE_ITEM",
        "created_at": "2019-04-23T23:19:46Z",
        "platform": null,
        "updated_at": "2019-04-23T23:19:46Z",
        "metric_groups": [
          "ENGAGEMENT"
        ]
      }
    }

Cette réponse ne renvoie pas les métriques de la ligne d’article. Elle fournit simplement des informations sur le job que vous venez de créer. L’id du job est nécessaire pour vérifier son statut. Celui-ci figure dans les attributs de réponse id et id_str.

Ensuite, vous devrez vérifier si le job que vous avez créé à l’aide de id_str de la réponse précédente a terminé son traitement, comme indiqué par "status": "SUCCESS" dans la réponse. Cela signifie que les data sont prêtes à être téléchargées. Le champ url contient le lien de téléchargement.

$ twurl -H ads-api.x.com "/9/stats/jobs/accounts/18ce54d4x5t?job_ids=1120829647711653888"

    {
      "request": {
        "params": {
          "job_ids": [
            1120829647711653888
          ]
        }
      },
      "next_cursor": "1120828505715920896",
      "data": [
        {
          "start_time": "2019-03-12T00:00:00Z",
          "segmentation_type": null,
          "url": "https://ton.twimg.com/advertiser-api-async-analytics/zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz",
          "id_str": "1120829647711653888",
          "entity_ids": [
            "el32n"
          ],
          "end_time": "2019-03-20T00:00:00Z",
          "country": null,
          "placement": "ALL_ON_TWITTER",
          "id": 1120829647711653900,
          "expires_at": "2019-04-25T23:19:48Z",
          "account_id": "18ce54d4x5t",
          "status": "SUCCESS",
          "granularity": "TOTAL",
          "entity": "LINE_ITEM",
          "created_at": "2019-04-23T23:19:46Z",
          "platform": null,
          "updated_at": "2019-04-23T23:19:48Z",
          "metric_groups": [
            "ENGAGEMENT"
          ]
        }
      ]
    }

Bien que nous transmettions un seul identifiant de tâche dans l’exemple ci-dessus, en pratique, vous voudrez utiliser le paramètre job_ids pour vérifier l’état de plusieurs tâches à la fois, en spécifiant jusqu’à 200 identifiants de tâche.

Ensuite, téléchargez le fichier de données en utilisant la valeur url indiquée.

    $ wget https://ton.twimg.com/advertiser-api-async-analytics/zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz
    --2019-04-23 17:52:12--  https://ton.twimg.com/advertiser-api-async-analytics/zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz
    Résolution de ton.twimg.com (ton.twimg.com)... 72.21.91.70
    Connexion à ton.twimg.com (ton.twimg.com)|72.21.91.70|:443... connecté.
    Requête HTTP envoyée, en attente de la réponse... 200 OK
    Taille : 381 [application/gzip]
    Enregistrement sous : 'zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz'

    zBkuuPeEVx-5OygDVcZpqNtwt51Z5 100%[=================================================>]     381  --.-KB/s    in 0s

    2019-04-23 17:52:12 (5.27 MB/s) - 'zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz' enregistré [381/381]

Enfin, extrayez le fichier.

`$ gunzip zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz`

Le contenu du fichier est présenté ci-dessous.

`$ cat zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json`

    {
      "data_type": "stats",
      "time_series_length": 1,
      "data": [
        {
          "id": "el32n",
          "id_data": [
            {
              "segment": null,
              "metrics": {
                "impressions": [
                  3482
                ],
                "tweets_send": null,
                "qualified_impressions": null,
                "follows": null,
                "app_clicks": null,
                "retweets": [
                  102
                ],
                "unfollows": null,
                "likes": [
                  15
                ],
                "engagements": [
                  171
                ],
                "clicks": [
                  30
                ],
                "card_engagements": null,
                "poll_card_vote": null,
                "replies": null,
                "carousel_swipes": null
              }
            }
          ]
        }
      ],
      "request": {
        "params": {
          "start_time": "2019-03-12T00:00:00Z",
          "segmentation_type": null,
          "entity_ids": [
            "el32n"
          ],
          "end_time": "2019-03-20T00:00:00Z",
          "country": null,
          "placement": "ALL_ON_TWITTER",
          "granularity": "TOTAL",
          "entity": "LINE_ITEM",
          "platform": null,
          "metric_groups": [
            "ENGAGEMENT"
          ]
        }
      }
    }

​

Couverture et fréquence moyenne

Exécuter dans Postman

​

GET stats/accounts/:account_id/reach/campaigns

Récupérer les statistiques de portée et de fréquence moyenne pour les campagnes spécifiées.

​

URL de ressource

https://ads-api.x.com/stats/accounts/:account_id/reach/campaigns

​

Paramètres

Nom	Description
account_id requis	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API des annonceurs, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
campaign_ids requis	Limite la réponse aux campagnes visées en fournissant une liste d’identifiants séparés par des virgules. Jusqu’à 20 ID peuvent être fournis. Remarque : jusqu’à 20 identifiants de campagne peuvent être fournis. Type : string Exemple : 8fgzf
end_time requis	Limite les données récupérées à l’heure de fin spécifiée, exprimée en ISO 8601. Remarque : doit être exprimée en heures pleines (0 minute et 0 seconde). Type : string Exemple : 2017-05-26T07:00:00Z
start_time requis	Limite les données récupérées à l’heure de début spécifiée, exprimée en ISO 8601. Remarque : doit être exprimée en heures pleines (0 minute et 0 seconde). Type : string Exemple : 2017-05-19T07:00:00Z

​

Exemple de requête

GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/reach/campaigns?campaign_ids=8fgzf&start_time=2017-05-19&end_time=2017-05-26

​

Exemple de réponse

    {
      "request": {
        "params": {
          "campaign_ids": [
            "8fgzf"
          ],
          "start_time": "2017-05-19T00:00:00Z",
          "end_time": "2017-05-26T00:00:00Z",
          "account_id": "18ce54d4x5t"
        }
      },
      "data_type": "reach",
      "data": [
        {
          "id": "8fgzf",
          "total_audience_reach": 1217,
          "average_frequency": 1.01
        }
      ]
    }

​

GET stats/accounts/:account_id/reach/funding_instruments

Récupère les analyses de reach et de fréquence moyenne pour les instruments de financement spécifiés.

​

URL de la ressource

https://ads-api.x.com/stats/accounts/:account_id/reach/funding_instruments

​

Paramètres

Nom	Description
account_id obligatoire	L’identifiant du compte utilisé. Apparaît dans le chemin de la ressource et constitue généralement un paramètre obligatoire pour toutes les requêtes de l’API Advertiser, à l’exception de GET accounts. Le compte indiqué doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
funding_instrument_ids obligatoire	Restreint la réponse aux instruments de financement visés en indiquant une liste d’identifiants séparés par des virgules. Jusqu’à 20 ID peuvent être fournis. Remarque : jusqu’à 20 identifiants d’instrument de financement peuvent être fournis. Type : string Exemple : lygyi
end_time obligatoire	Restreint les données renvoyées à l’heure de fin indiquée, exprimée au format ISO 8601. Remarque : doit être exprimée en heures pleines (0 minute et 0 seconde). Type : string Exemple : 2017-05-26T07:00:00Z
start_time obligatoire	Restreint les données renvoyées à l’heure de début indiquée, exprimée au format ISO 8601. Remarque : doit être exprimée en heures pleines (0 minute et 0 seconde). Type : string Exemple : 2017-05-19T07:00:00Z

​

Exemple de requête

GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/reach/funding_instruments?funding_instrument_ids=lygyi&start_time=2017-05-19&end_time=2017-05-26

​

Exemple de réponse

    {
      "request": {
        "params": {
          "funding_instrument_ids": [
            "lygyi"
          ],
          "start_time": "2017-05-19T00:00:00Z",
          "end_time": "2017-05-26T00:00:00Z",
          "account_id": "18ce54d4x5t"
        }
      },
      "data_type": "reach",
      "data": [
        {
          "id": "lygyi",
          "total_audience_reach": 1217,
          "average_frequency": 1.01
        }
      ]
    }

​

Analyses synchrones

Exécuter dans Postman

​

GET stats/accounts/:account_id

Récupère des analyses synchrones pour le compte actuel. Une plage temporelle maximale (end_time - start_time) de 7 jours est autorisée.

​

URL de la ressource

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

​

Paramètres

Nom	Description
account_id requis	L’identifiant du compte exploité. Apparaît dans le chemin de la ressource et constitue généralement un paramètre requis pour toutes les requêtes de l’API Ads, à l’exception de GET accounts. Le compte spécifié doit être associé à l’utilisateur authentifié. Type : string Exemple : 18ce54d4x5t
end_time requis	Restreint les données récupérées à l’heure de fin spécifiée, exprimée en ISO 8601. Remarque : Doit être exprimée en heures pleines (0 minute et 0 seconde). Type : string Exemple : 2017-05-26T07:00:00Z
entity requis	Le type d’entité pour lequel récupérer des données. Type : enum Valeurs possibles : ACCOUNT, CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, ORGANIC_TWEET, PROMOTED_ACCOUNT, PROMOTED_TWEET, MEDIA_CREATIVE
entity_ids requis	Les entités spécifiques pour lesquelles récupérer des données. Indiquez une liste d’ids d’entité séparés par des virgules. Remarque : Jusqu’à 20 ids d’entité peuvent être fournis. Type : string Exemple : 8u94t
granularity requis	Indique le niveau de granularité des données récupérées. Type : enum Valeurs possibles : DAY, HOUR, TOTAL
metric_groups requis	Les métriques à retourner. Indiquez une liste de groupes de métriques séparés par des virgules. Pour plus d’informations, voir Metrics and Segmentation. Remarque : Les données MOBILE_CONVERSION doivent être demandées séparément. Type : enum Valeurs possibles : BILLING, ENGAGEMENT, LIFE_TIME_VALUE_MOBILE_CONVERSION, MEDIA, MOBILE_CONVERSION, VIDEO, WEB_CONVERSION
placement requis	Restreint les données récupérées à un placement particulier. Remarque : Une seule valeur est acceptée par requête. Pour les entités disposant à la fois d’un placement sur X et sur X Audience Platform, des requêtes distinctes sont requises, une pour chaque valeur de placement. Type : enum Valeurs possibles : ALL_ON_TWITTER, PUBLISHER_NETWORK, SPOTLIGHT, TREND
start_time requis	Restreint les données récupérées à l’heure de début spécifiée, exprimée en ISO 8601. Remarque : Doit être exprimée en heures pleines (0 minute et 0 seconde). Type : string Exemple : 2017-05-19T07:00:00Z

​

Exemple de requête

GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=8u94t&start_time=2017-05-19&end_time=2017-05-26&granularity=TOTAL&placement=ALL_ON_TWITTER&metric_groups=ENGAGEMENT

​

Exemple de réponse

    {
      "data_type": "stats",
      "time_series_length": 1,
      "data": [
        {
          "id": "8u94t",
          "id_data": [
            {
              "segment": null,
              "metrics": {
                "impressions": [
                  1233
                ],
                "tweets_send": null,
                "qualified_impressions": null,
                "follows": null,
                "app_clicks": null,
                "retweets": null,
                "likes": [
                  1
                ],
                "engagements": [
                  58
                ],
                "clicks": [
                  58
                ],
                "card_engagements": null,
                "poll_card_vote": null,
                "replies": null,
                "carousel_swipes": null
              }
            }
          ]
        }
      ],
      "request": {
        "params": {
          "start_time": "2017-05-19T07:00:00Z",
          "segmentation_type": null,
          "entity_ids": [
            "8u94t"
          ],
          "end_time": "2017-05-26T07:00:00Z",
          "country": null,
          "placement": "ALL_ON_TWITTER",
          "granularity": "TOTAL",
          "entity": "LINE_ITEM"
          "platform": null,
          "metric_groups": [
            "ENGAGEMENT"
          ]
        }
      }
    }

​

Entités actives

Exécuter dans Postman

​

GET stats/accounts/:account_id/active_entities

Récupère des informations sur les entités dont les métriques d’analytics ont changé sur une période donnée.

Cet endpoint doit être utilisé conjointement avec nos endpoints d’analytics. Les résultats de cet endpoint indiquent pour quelles entités d’annonces demander des analytics. Consultez notre Guide des entités actives pour les directives d’utilisation.

Les événements de changement sont disponibles par créneaux horaires.

• Les valeurs start_time et end_time indiquent quels créneaux horaires interroger.
• Le tableau data renvoyé inclura un objet pour chaque entité à inclure dans les demandes d’analytics ultérieures.
• IMPORTANT : Les dates à spécifier dans les demandes d’analytics ultérieures doivent être déterminées à partir des valeurs activity_start_time et activity_end_time.
  • Ces valeurs représentent les plages temporelles auxquelles s’appliquent les événements de changement stockés. Elles sont renvoyées par entité.

Remarque : Une plage temporelle maximale (end_time - start_time) de 90 jours est autorisée.

​

URL de ressource

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

​

Paramètres

Nom	Description
account_id obligatoire	L’identifiant du compte exploité. 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
end_time obligatoire	Restreint les données récupérées à l’heure de fin spécifiée, exprimée en ISO 8601. Remarque : Doit être exprimée en heures pleines (0 minute et 0 seconde). Type: string Exemple : 2017-05-26T07:00:00Z
entity obligatoire	Le type d’entité pour lequel récupérer des données. Type: enum Valeurs possibles : CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE, PROMOTED_ACCOUNT, PROMOTED_TWEET
start_time obligatoire	Restreint les données récupérées à l’heure de début spécifiée, exprimée en ISO 8601. Remarque : Doit être exprimée en heures pleines (0 minute et 0 seconde). Type: string Exemple : 2017-05-19T07:00:00Z
campaign_ids optionnel	Limite la réponse aux entités associées aux campagnes souhaitées en spécifiant une liste d’identifiants séparés par des virgules. Jusqu’à 200 identifiants peuvent être fournis. Remarque : Mutuellement exclusif avec funding_instrument_ids et line_item_ids. Type: string Exemple : 8wku2
funding_instrument_ids optionnel	Limite la réponse aux entités associées aux instruments de financement souhaités en spécifiant une liste d’identifiants séparés par des virgules. Jusqu’à 200 identifiants peuvent être fournis. Remarque : Mutuellement exclusif avec campaign_ids et line_item_ids. Type: string Exemple : lygyi
line_item_ids optionnel	Limite la réponse aux entités associées aux line items souhaités en spécifiant une liste d’identifiants séparés par des virgules. Jusqu’à 200 identifiants peuvent être fournis. Remarque : Mutuellement exclusif avec campaign_ids et line_item_ids. Type: string Exemple : 8v7jo

​

Exemple de requête

GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/active_entities?entity=PROMOTED_TWEET&start_time=2019-02-28&end_time=2019-03-01

​

Exemple de réponse

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "entity": "PROMOTED_TWEET",
          "start_time": "2019-02-28T08:00:00Z",
          "end_time": "2019-03-01T08:00:00Z"
        }
      },
      "data": [
        {
          "entity_id": "2mvb28",
          "activity_start_time": "2019-02-28T01:30:07Z",
          "activity_end_time": "2019-03-01T07:42:55Z",
          "placements": [
            "ALL_ON_TWITTER"
          ]
        },
        {
          "entity_id": "2mvb29",
          "activity_start_time": "2019-02-27T11:30:07Z",
          "activity_end_time": "2019-03-01T07:42:50Z",
          "placements": [
            "ALL_ON_TWITTER",
            "PUBLISHER_NETWORK"
          ]
        },
        {
          "entity_id": "2mvfan",
          "activity_start_time": "2019-02-27T09:00:05Z",
          "activity_end_time": "2019-03-01T06:06:36Z",
          "placements": [
            "PUBLISHER_NETWORK"
          ]
        },
        {
          "entity_id": "2n17dx",
          "activity_start_time": "2019-02-28T02:02:26Z",
          "activity_end_time": "2019-03-01T07:52:44Z",
          "placements": [
            "ALL_ON_TWITTER",
            "PUBLISHER_NETWORK"
          ]
        }
      ]
    }