Passer au contenu principal

Introduction

Les indicateurs analytiques aident les partenaires et les annonceurs à comprendre les performances du contenu qu’ils diffusent sur X. Cela inclut des informations telles que les impressions, les clics, les vues vidéo et les dépenses. De plus, les partenaires et les annonceurs peuvent obtenir des métriques détaillées pour différents segments des audiences qu’ils atteignent. L’Ads API prend en charge deux façons de 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 que la tâche associée a terminé son traitement. L’endpoint synchrone prend en charge de courtes plages temporelles et est idéal pour l’optimisation en temps réel des campagnes. Les endpoints asynchrones prennent en charge des plages temporelles beaucoup plus longues et sont donc conçus pour récupérer un volume de données bien plus important, idéal pour générer des rapports ou reconstituer l’historique.

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 ont pour but d’aider les développeurs à choisir quel ensemble d’endpoints utiliser.
  • Cela fait référence au nombre maximal de jobs pouvant être dans un état de traitement à un moment donné.
** Une fois que le job a terminé son traitement avec succès, une URL est renvoyée. C’est à cet emplacement que le fichier de résultats compressé (gzip) peut être téléchargé.En dehors de ces différences, les endpoints offrent la même fonctionnalité.

Cas d’utilisation

Il existe trois principaux cas d’utilisation pour l’analytics.
  1. Optimisation en temps réel : utiliser les métriques de performance pour mettre à jour les 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’analytics synchrone peut être utilisé pour l’optimisation en temps réel afin de mettre à jour les campagnes en fonction des changements de métriques intervenus au cours des 5 à 15 dernières minutes. Les deux types d’endpoints peuvent être utilisés pour la synchronisation des analytics. Gardez à l’esprit que la plage temporelle souhaitée 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’analytics asynchrones. (L’endpoint d’analytics synchrone ne doit jamais être utilisé pour récupérer de grandes quantités de données.) Les endpoints d’analytics 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’analytics asynchrones pour traiter des requêtes de l’interface utilisateur.

Options de requête

Les requêtes d’analytics sont limitées aux comptes publicitaires et nécessitent donc l’id du compte dans le chemin de ressource. Les options de requête, listées ci-dessous, sont spécifiées sous forme de paramètres de requête. Les types de valeurs suivants sont requis.
  • Entités : le type d’entité ainsi que jusqu’à 20 id d’entité pour lesquelles vous souhaitez obtenir des analytics
  • Plage temporelle : les heures de début et de fin, exprimées au format ISO 8601
    • Remarque : elles doivent être exprimées en heures pleines
  • Groupes de métriques : un ou plusieurs ensembles de métriques associées (voir Metrics and Segmentation pour la liste des métriques dans chaque groupe de métriques)
  • Granularité : spécifie le niveau d’agrégation auquel les métriques doivent être renvoyées
  • Emplacement : détermine si les métriques sont récupérées pour des publicités diffusées sur X ou en dehors de X
    • Remarque : une seule valeur d’emplacement peut être spécifiée par requête
Utilisez les paramètres de requête start_time et end_time pour spécifier 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 du point de terminaison)
  2. DAY : les valeurs d’heure de début et de fin doivent toutes deux être alignées sur minuit dans le fuseau horaire du compte
  3. HOUR : spécifiez n’importe quelle plage temporelle (dans les limites du point de terminaison)
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 analytiques (et non deux), car cette plage temporelle ne couvre qu’une période de 24 heures. Segmentation Disponible uniquement via nos points de terminaison d’analytics asynchrones, la segmentation permet aux partenaires et aux annonceurs de récupérer des métriques ventilées selon certaines valeurs de ciblage spécifiques. 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 l’Ads API ne correspondent-ils pas à ceux affichés dans l’interface X Ads ?
  • Assurez-vous d’avoir demandé des données pour les deux emplacements : ALL_ON_TWITTER et PUBLISHER_NETWORK, SPOTLIGHT et TREND.
  • N’oubliez pas que les heures de fin dans l’Ads API sont exclusives ; elles sont inclusives dans l’interface Ads.
Pourquoi les chiffres changent-ils en fonction du moment où je demande les données ?
  • Dès que les métriques de reporting sont disponibles, vous pouvez les récupérer. Elles sont disponibles en quasi temps réel. Cependant, ces premiers résultats sont 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 (pour le filtrage du spam, par exemple).
Comment puis-je déterminer quels identifiants (id) d’entité demander pour une période donnée ? Pourquoi toutes les valeurs dans la réponse analytics sont-elles à null ?
  • Il est probable que la campagne n’ait pas été diffusée pendant la période demandée.
  • Utilisez l’endpoint Active Entities pour déterminer pour quelles entités et pour quelle période récupérer des données analytics.
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 et PUBLISHER_NETWORK, SPOTLIGHT et TREND (c’est-à-dire la X Audience Platform).
Est-il possible de récupérer des métriques pour des entités supprimées ou en pause ?
  • Oui. Le statut de l’entité n’a pas d’impact sur la disponibilité des métriques analytics.
Pourquoi les valeurs segmentées ne correspondent-elles pas aux valeurs non segmentées ?
  • Il n’est pas attendu que les données segmentées se totalisent à 100 % par rapport aux 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 par plusieurs dimensions ?
  • Nous ne prenons pas en charge la segmentation multiple.

Bonnes pratiques

Quelques bonnes pratiques pour collecter des données d’analytics à partir de l’Ads API.

Limitation du débit et réessais

  • Pour les requêtes soumises à une limitation de débit (celles qui renvoient un code d’état HTTP 429), vous devez consulter l’en-tête x-rate-limit-reset et réessayer uniquement au moment indiqué ou après.
  • Pour les requêtes qui aboutissent à un code d’état HTTP 503 Service Unavailable, vous devez consulter l’en-tête retry-after et réessayer uniquement après le moment indiqué.
  • Les applications qui ne respectent pas les délais indiqués pour les réessais peuvent se voir retirer leur accès à l’Ads API ou faire l’objet d’une réduction de débit sans préavis.

Les métriques Analytics en bref

  • Toutes les métriques Analytics sont figées et ne changeront plus après 24 heures, à l’exception de billed_charge_local_micro.
  • La métrique billed_charge_local_micro est une estimation pendant une période pouvant aller jusqu’à 3 jours après la mise à disposition des données.
  • Après 24 heures, cette métrique peut diminuer en raison de crédits pour surdépenses (publicités diffusées après le end_time indiqué) et pour des événements facturables considérés comme non valides. Cette métrique ne change que très légèrement après 24 heures.
  • Veuillez consulter la page Analytics pour plus d’informations.

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

  • Fournissez toujours à la fois un start_time et un end_time.
  • Ne récupérez pas de données pour des entités de plus de 7 jours.
  • Demandez idéalement des données avec une granularité HOUR, car vous pouvez toujours agréger et consolider les métriques pour obtenir une granularité DAY et TOTAL.
  • Demandez idéalement des données au niveau des line_items et des promoted_tweets, car vous pouvez toujours agréger et consolider ces métriques pour obtenir des totaux sur l’ensemble de la hiérarchie des entités publicitaires (c.-à-d. aux niveaux campagne, instrument de financement ou compte).
  • Enregistrez et stockez les valeurs des métriques analytiques de votre côté (localement).
  • Ne redemandez pas de 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 doivent être disponibles en quelques secondes après la survenue d’un événement.
  • Regroupez les métriques de conversion et les métriques non liées aux conversions dans des requêtes séparées.

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

  • Reportez-vous aux consignes fournies ci-dessus pour la section « Fetching Real-time, Non-segmented Data ». Des conseils supplémentaires sont fournis 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 pouvant aller jusqu’à 1 heure. Les données segmentées par INTERESTS peuvent être retardées jusqu’à 12 heures.
  • Il est normal que les données segmentées ne totalisent pas 100 % des données non segmentées, en raison de la manière dont ces informations sont dérivées.

Récupération de données historiques

  • Lors du complément rétroactif de données (c’est‑à‑dire l’ajout d’un nouveau compte annonceur), vous devrez peut‑être effectuer plusieurs requêtes en utilisant des intervalles start_time et end_time plus courts.
  • Limitez vos extractions à des fenêtres de 30 jours.
  • Limitez la fréquence de ces requêtes et répartissez‑les dans le temps afin de ne pas épuiser vos limites de taux pour ces extractions.

Exemple

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

Indicateurs par objectif

Les indicateurs applicables à une entité dépendent de l’objectif de campagne. Utilisez ce guide pour déterminer quels groupes d’indicateurs récupérer pour chaque type d’objectif, ainsi que comment calculer des indicateurs dérivés supplémentaires.

ENGAGEMENTS

Groupes de métriques pertinents : ENGAGEMENT et BILLING. MEDIA est également applicable si des médias sont utilisés dans les éléments créatifs.

WEBSITE_CLICKS et WEBSITE_CONVERSIONS

Groupes de métriques pertinents : ENGAGEMENT, BILLING et WEB_CONVERSION. MEDIA est également applicable si un média est utilisé dans les créations publicitaires.

APP_INSTALLS et APP_ENGAGEMENTS

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

FOLLOWERS

Groupes de métriques pertinents : ENGAGEMENT et BILLING. MEDIA est également applicable si des médias sont utilisés dans les créatifs.

LEAD_GENERATION

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

VIDEO_VIEWS

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

VIDEO_VIEWS_PREROLL

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

Métriques et segmentation

Ce document présente un aperçu des métriques disponibles dans notre Analytics pour chaque type d’entité, ainsi que des segmentations disponibles pour chacune de ces métriques. *Certaines métriques de la famille de métriques 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

ENGAGEMENT

BILLING

VIDEO

Avis concernant les modifications de la définition des métriques vidéo : La métrique video_total_views au sein du groupe de métriques VIDEO prendra en compte toutes les vues pour lesquelles la vidéo est au moins à 50 % visible pendant 2 secondes, conformément au standard MRC. Notre définition d’origine d’une vue vidéo, à savoir une vidéo visible à 100 % à l’écran pendant au moins 3 secondes, restera disponible sous la forme d’une 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 de la vue, utilisez l’unité d’enchère nouvellement disponible VIEW_3S_100PCT.

MEDIA

WEB_CONVERSION

MOBILE_CONVERSION

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

LIFE_TIME_VALUE_MOBILE_CONVERSION

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

Segmentation

Les rapports de segmentation permettent d’obtenir des métriques ventilées selon les valeurs d’un type de ciblage donné. La segmentation n’est disponible que via les requêtes analytiques asynchrones en raison de la complexité supplémentaire significative qu’elles impliquent. La segmentation n’est pas prise en charge pour les entités MEDIA_CREATIVE ou ORGANIC_TWEET. Certains types de segmentation nécessitent que des paramètres supplémentaires soient transmis. Ils sont documentés ci-dessous. Lors de la segmentation par CITIES ou POSTAL_CODES, l’API ne renverra que les emplacements ciblés. La segmentation par régions et par zones métropolitaines renverra à la fois les emplacements ciblés et non ciblés.

Indicateurs dérivés

Les indicateurs de campagne dépendent de leur objectif de campagne. Utilisez ce guide pour savoir comment calculer les indicateurs dérivés à utiliser en fonction des objectifs définis. Tout metric sans accolades correspond à un indicateur renvoyé par les endpoints analytics de l’Ads API. Tout nom entouré de {accolades} indique un indicateur dérivé pour cette catégorie.

ENGAGEMENTS

WEBSITE_CLICKS

APP_INSTALLS et APP_ENGAGEMENTS

ABONNÉS

LEAD_GENERATION

VIDEO_VIEWS

QUALIFIED_IMPRESSIONS

PERSONNALISÉ

Pour un placement_type égal à PROMOTED_ACCOUNT, voir l’objectif FOLLOWERS ci-dessus. Pour tous les autres emplacements utilisant cet objectif, voir ENGAGEMENTS pour les métriques dérivées correspondantes.

Guides

Entités actives

Introduction

L’endpoint Active Entities est conçu pour être utilisé conjointement avec nos endpoints d’analytics synchrones et asynchrones, car il fournit des informations sur les campagnes pour lesquelles demander des analytics. Il le fait en renvoyant des détails sur les entités publicitaires et sur les moments où leurs métriques ont changé. L’utilisation de cet endpoint simplifiera grandement votre code et votre logique de récupération des analytics. Ce guide inclut des informations et du contexte à propos de l’endpoint et de sa source de données. Il fournit également des directives d’utilisation et une série d’exemples de requêtes illustrant comment utiliser Active Entities avec nos endpoints d’analytics. La section Résumé propose une vue d’ensemble de l’approche recommandée.

Données

Chaque fois qu’une métrique d’entité publicitaire change, nous enregistrons des informations sur ce changement. Ces événements de modification sont stockés dans des tranches horaires et incluent des détails sur l’entité ainsi que sur le moment auquel le changement 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, mais il peut y en avoir d’autres.

Endpoint

Request

Les requêtes Active Entities sont rattaché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 que nos endpoints d’analyse prennent en charge. Les valeurs start_time et end_time doivent être exprimées au format ISO 8601 et indiquer quelles tranches horaires interroger. Elles doivent être exprimées en heures pleines. Cet endpoint prend également en charge trois paramètres optionnels qui peuvent ê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 n’importe quelle valeur entity spécifiée.

Réponse

La réponse Active Entities pour la requête ci-dessus est affichée ci-dessous.
Le tableau data contient un objet pour chaque entité devant être incluse dans une requête d’analytics ultérieure. Vous ne devez pas demander des analytics pour des identifiants en dehors de cet ensemble. Chaque objet comporte quatre champs : entity_id, activity_start_time, activity_end_time et placements. Les heures de début et de fin d’activité représentent l’intervalle de temps auquel s’appliquent les événements de modification de l’entité associée et déterminent donc les dates qui doivent être spécifiées dans les requêtes d’analytics 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’identifiant d’entité donné.

Utilisation

L’endpoint Active Entities doit déterminer la manière dont les requêtes d’analytics sont effectuées. Les directives d’utilisation suivantes sont rédigées pour prendre en charge la synchronisation des analytics, afin de permettre aux partenaires de garder leurs magasins de données synchronisés avec Twitter. En d’autres termes, elles décrivent comment effectuer des synchronisations en arrière-plan planifiées à intervalles réguliers. Il y a deux décisions qu’un développeur doit prendre.
  1. À quelle fréquence demander des informations sur les entités actives et, par conséquent, à quelle fréquence récupérer les analytics.
  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’analytics.
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 de la manière suivante pour définir la façon dont les requêtes d’analytics sont effectuées. Suivez cette procédure après avoir décidé de la fréquence à laquelle vous demandez les informations sur les entités actives et, par conséquent, de la fréquence à laquelle vous récupérez les données d’analytics.
  1. Effectuez la requête Active Entities.
  2. Divisez 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 d’entité.
    2. Déterminez les valeurs start_time et end_time pour l’analytics.
      • Trouvez la valeur minimale de activity_start_time. Arrondissez cette valeur à la valeur inférieure la plus proche.
      • Trouvez la valeur maximale de activity_end_time. Arrondissez cette valeur à la valeur supérieure la plus proche.
    3. Effectuez la ou les requêtes d’analytics.
      • Regroupez les id d’entité par lots de 20.
      • Utilisez les valeurs start_time et end_time de l’étape 3b.
      • Indiquez la valeur de placement appropriée.
    4. Écrivez dans votre stockage de données.
Veuillez consulter active_entities.py pour un exemple qui utilise le SDK Python.

Fréquence

La réponse à la première question détermine l’intervalle de temps qui doit être utilisé dans les requêtes Active Entities. Par exemple, si vous demandez des informations sur les entités actives toutes les heures, l’intervalle de temps doit être d’une heure. Si vous demandez des informations sur les entités actives une fois par jour, l’intervalle de temps doit être d’une journée. En d’autres termes, les intervalles de temps 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 données d’analyse 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 montre des exemples d’horodatages de début et de fin Active Entities pour ce scénario. Étant donné la manière dont les événements de modification sont stockés, les quatre requêtes Active Entities ci‑dessus interrogent toutes le même bucket horaire, ce qui est nécessaire pour ce cas d’utilisation. Cependant, après l’heure en cours, ce bucket 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, recherchez la valeur minimale de activity_start_time et la valeur maximale de activity_end_time. Modifiez ces valeurs en arrondissant l’heure minimale de début d’activité à l’inférieur et l’heure maximale de fin d’activité au supérieur. Plus précisément, définissez les horodatages avec les heures, les minutes et les secondes à zéro pour les deux, puis ajoutez un jour à l’heure de fin, comme illustré dans le tableau suivant. Ce sont ces heures de début et de fin qui doivent être spécifiées dans les requêtes d’analytics ultérieures. Remarque : Il est important d’inclure les horodatages avec les heures, les minutes et les secondes définies à zéro. Sinon, si seule la date est transmise, nous supposerons que vous demandez des analytics 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 minimale de début d’activité est 2019-02-28T01:30:07Z et que l’horodatage est omis pour un compte publicitaire avec un décalage horaire de -08:00:00, la requête d’analytics ne prendra pas en compte les changements intervenus entre 01:30 et 08:00. Autrement, si vous préférez demander des analytics uniquement pour la fenêtre temporelle d’activité renvoyée, sans l’étendre à des jours complets, vous pouvez le faire. En suivant 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 tels intervalles ne sont pas acceptés si vous spécifiez une granularité DAY dans la requête d’analytics.)

Exemple

Cette section montre comment utiliser Active Entities conjointement avec l’endpoint d’analytics synchrone. (Les réponses ont été légèrement modifiées pour plus de lisibilité.) Dans cet exemple, l’endpoint Active Entities est appelé au début de chaque heure, chaque requête portant sur l’heure précédente. La réponse détermine la façon 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 à l’intervalle compris entre 02:02:55 et 02:28:12.
En se basant sur ces heures de début et de fin d’activité et en utilisant l’approche décrite ci-dessus, les valeurs de start_time et end_time pour l’analytics sont définies respectivement 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 nous nous y attendions d’après les informations sur les entités actives.
La requête Active Entities suivante a lieu à 04:00:00 et ne prend en compte que l’heure précédente. Comme mentionné ci‑dessus, une fenêtre temporelle ne doit être demandée qu’une seule fois. D’après la réponse, nous voyons que les événements de modification pour cet élément de campagne s’appliquent à la fois à 02:00:00 et à 03:00:00. Dans la requête Analytics suivante, nous nous attendons à voir des changements pour les deux heures.
En plus de constater des métriques non nulles pour 03:00:00, nous voyons 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, sont désormais de 2 995 pour l’heure 02:00:00, contre 2 792 auparavant. Cela montre comment les événements de changement qui ont été enregistrés pendant l’heure 03:00:00 s’appliquent à l’heure 02:00:00.
La requête Active Entities à 05:00:00, en ne considérant à nouveau que l’heure précédente, montre que les événements de changement s’appliquent uniquement à l’heure 03:00:00. Les modifications apportées aux métriques d’analytics dans la requête suivante le reflètent.
La réponse Analytics montre que seuls les indicateurs pour 03:00:00 ont changé ; les valeurs pour 02:00:00 sont identiques à ce qu’elles étaient lors de la précédente requête Analytics.
Enfin, à 06:00:00, nous constatons qu’il n’y a aucun autre événement de modification. Remarque : cela n’implique pas pour autant que les métriques pour cette ligne ne puissent pas évoluer à l’avenir.

Guide asynchrone

Référence de l’API

Analytique asynchrone

Introduction

Les endpoints d’analytics 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’analytics asynchrones). Avec cette approche, la connexion du client n’a pas besoin de rester ouverte jusqu’à ce que la requête ait été traitée. 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 les demandes de données pour les comptes, les instruments de financement, les campagnes, les line items, les Tweets sponsorisés et les créatifs média. La différence entre ceux‑ci et l’endpoint synchrone est que les endpoints d’analytics 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 Vue d’ensemble de l’analytics. Contrairement à nos endpoints synchrones, la limitation de débit est basée sur le nombre de jobs concurrents pour un compte donné. En d’autres termes, elle est basée sur le nombre de jobs pouvant être dans un état de traitement à un moment donné. Nous effectuons ce comptage au niveau du compte publicitaire.

Utilisation

La récupération des métriques de campagne à l’aide des endpoints d’analytics asynchrones est un processus en plusieurs étapes. Elle implique la création d’un job, la vérification que le job a terminé son traitement et, enfin, le téléchargement des données. Le fichier de données doit être décompressé. Les quatre étapes spécifiques sont décrites ci‑dessous.
  1. Créez le job à 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 le job a terminé son traitement.
  3. Une fois que le job a terminé son traitement, 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 possède le même schéma JSON que la réponse de l’endpoint d’analytics synchrone. Les métriques de campagne segmentées ne sont disponibles qu’au moyen des endpoints d’analytics asynchrones. Les métriques de campagne peuvent être ventilées par lieu, sexe, centre d’intérêt, mot‑clé, et plus encore. Pour obtenir la liste complète des options, consultez la page Metrics and Segmentation. Pour obtenir des métriques segmentées, utilisez le paramètre de requête segmentation_type lors de la création du job.

Exemple

Cette section illustre comment utiliser les endpoints d’analyses asynchrones. Commencez par créer un job en utilisant 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 campagne spécifique sur une période d’une semaine. (Notez que la plage temporelle demandée va jusqu’au 20 mars sans l’inclure, car l’horodatage est défini à minuit.)
Cette réponse ne renvoie pas les métriques de l’élément de campagne. Elle fournit simplement des informations sur le job que vous venez de créer. L’id du job est nécessaire pour vérifier l’état du job. Celui-ci apparaît dans les attributs de réponse id et id_str. Ensuite, vous devez vérifier si le job que vous avez créé en utilisant l’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 données sont prêtes à être téléchargées. Le champ url contient le lien de téléchargement.
Bien que nous transmettions un seul identifiant de tâche dans l’exemple ci-dessus, en pratique, il est recommandé d’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.
Enfin, extrayez l’archive.
Le contenu de ce fichier est présenté ci-dessous.

Portée et fréquence moyenne

GET stats/accounts/:account_id/reach/campaigns

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

URL de la ressource

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

Paramètres

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

GET stats/accounts/:account_id/reach/funding_instruments

Récupérez les statistiques de portée 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

Exemple de requête

Exemple de réponse

Analyses synchrones

GET stats/accounts/:account_id

Récupérer les analyses synchrones du compte actuel. Un intervalle de temps maximal de 7 jours entre (end_time - start_time) est autorisé.

URL de la ressource

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

Paramètres

Exemple de requête

Exemple de réponse

Entités actives

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 publicitaires vous devez demander des analytics. Consultez notre guide sur les entités actives pour les consignes d’utilisation. Les événements de modification sont disponibles par tranches horaires.
  • Les valeurs start_time et end_time indiquent quelles tranches horaires interroger.
  • Le tableau data renvoyé contiendra un objet pour chaque entité devant être incluse dans les requêtes d’analytics suivantes.
  • IMPORTANT : les dates à spécifier dans les requêtes d’analytics suivantes doivent être déterminées à partir des valeurs activity_start_time et activity_end_time.
    • Ces valeurs représentent les plages horaires auxquelles les événements de modification stockés s’appliquent. Elles sont renvoyées pour chaque entité.
Remarque : une plage de temps maximale (end_time - start_time) de 90 jours est autorisée.

URL de la ressource

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

Paramètres

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