Analisi

​

Introduzione

Le metriche di analytics aiutano partner e inserzionisti a comprendere le prestazioni dei contenuti che promuovono su X. Ciò include informazioni come impression, clic, visualizzazioni video e spesa. Inoltre, partner e inserzionisti possono ottenere metriche dettagliate per vari segmenti dei pubblici raggiunti.

La X Ads API supporta due modalità per ottenere metriche dettagliate sulle prestazioni delle campagne: sincrona e asincrona. Con le chiamate di analytics sincrone, le metriche richieste vengono restituite nella risposta. Con gli endpoint di analytics asincroni, le metriche richieste sono disponibili in un file di risultati scaricabile dopo che il relativo job ha terminato l’elaborazione. L’endpoint sincrono supporta intervalli di tempo brevi ed è ideale per l’ottimizzazione delle campagne in tempo reale. Gli endpoint asincroni supportano intervalli di tempo molto più lunghi e sono quindi pensati per recuperare quantità di dati molto maggiori, ideali per generare report o ricostruzioni storiche.

​

Dettagli

​

Sincrono vs asincrono

Le differenze tra gli endpoint di analytics sincroni e asincroni sono riepilogate nella tabella seguente. Queste informazioni aiutano gli sviluppatori a scegliere quale set di endpoint utilizzare.

Funzionalità	Sincrono	Asincrono
Limite di velocità	Livello utente: 250 richieste/15 minuti	Livello account: 100 job concorrenti*
Intervallo temporale	7 giorni	90 giorni (non segmentato) 45 giorni (segmentato)
Segmentazione	No	Sì
Risposta	Dati delle metriche	Stato di elaborazione del job**
Caso d’uso consigliato	Ottimizzazione in tempo reale Richieste da interfaccia utente	Sincronizzazioni pianificate regolarmente Integrazione dei dati storici

• Si riferisce al numero massimo di job che possono trovarsi in stato di elaborazione in un dato momento.

** Al termine dell’elaborazione, viene restituito un URL da cui è possibile scaricare il file dei risultati compresso (gzip).

Al di fuori di questo, gli endpoint offrono la stessa funzionalità.

​

Casi d’uso

Esistono tre principali casi d’uso per l’analisi.

1. Ottimizzazione in tempo reale: uso delle metriche di performance per aggiornare le campagne attive
2. Sincronizzazione: sincronizzazioni pianificate in background
3. Onboarding di un nuovo account: integrazione dei dati storici

L’endpoint di analytics sincrono può essere utilizzato per l’ottimizzazione in tempo reale, per aggiornare le campagne in base alle variazioni delle metriche negli ultimi 5–15 minuti. Entrambi gli endpoint possono essere utilizzati per la sincronizzazione delle analytics. Tieni presente che l’intervallo temporale desiderato e l’eventuale necessità di segmentazione determineranno quale endpoint utilizzare. L’onboarding di un nuovo account deve essere eseguito esclusivamente tramite gli endpoint di analytics asincroni. (L’endpoint di analytics sincrono non deve mai essere utilizzato per recuperare grandi quantità di data.)

Gli endpoint di analytics asincroni possono alimentare dashboard e altri elementi dell’interfaccia utente se le metriche vengono sincronizzate con un processo di backend. L’implementazione dovrebbe evitare di chiamare gli endpoint di analytics asincroni per soddisfare le richieste dell’interfaccia utente.

​

Opzioni della richiesta

Le richieste di Analytics sono limitate agli account pubblicitari e, di conseguenza, richiedono l’ID dell’account nel percorso della risorsa. Le opzioni della richiesta, elencate di seguito, sono specificate come parametri di query. Sono richiesti i seguenti tipi di valori.

• Entità: il tipo di entità e fino a 20 id di entità per cui desideri richiedere gli analytics
• Intervallo temporale: orari di inizio e fine, espressi in ISO 8601
  • Nota: devono essere espressi in ore intere
• Gruppi di metriche: uno o più insiemi di metriche correlate (consulta Metriche e Segmentazione per un elenco delle metriche incluse in ciascun gruppo)
• Granularità: specifica il livello di aggregazione con cui devono essere restituite le metriche
• Placement: determina se le metriche vengono recuperate per annunci erogati su X o al di fuori di X
  • Nota: per ogni richiesta può essere specificato un solo valore di placement

Usa i parametri di richiesta start_time e end_time per specificare un intervallo temporale. Questi valori devono essere allineati con la granularità specificata come segue.

1. TOTAL: specifica qualsiasi intervallo temporale (entro i limiti dell’endpoint)
2. DAY: sia l’orario di inizio sia quello di fine devono coincidere con la mezzanotte nel fuso orario dell’account
3. HOUR: specifica qualsiasi intervallo temporale (entro i limiti dell’endpoint)

L’orario di fine è esclusivo. Ad esempio, una richiesta con start_time=2019-01-01T00:00:00Z e end_time=2019-01-02T00:00:00Z restituirà metriche di analytics per un solo giorno (non due), poiché questo intervallo copre soltanto 24 ore.

Segmentazione

Disponibile solo tramite i nostri endpoint di analytics asincroni, la segmentazione consente a partner e inserzionisti di recuperare metriche suddivise per specifici valori di targeting. Per richiedere metriche segmentate, usa il parametro di richiesta segmentation_type. Per maggiori dettagli sulle opzioni di segmentazione, consulta Metrics and Segmentation.

​

Domande frequenti

Perché i numeri della X Ads API non corrispondono a quelli mostrati nella X Ads UI?

• Assicurati di aver richiesto i dati per tutti i posizionamenti: ALL_ON_TWITTER, PUBLISHER_NETWORK, SPOTLIGHT e TREND.
• Ricorda che le ore di fine nella X Ads API sono esclusive; nella X Ads UI sono inclusive.

Perché i numeri cambiano a seconda di quando richiedo i dati?

• Non appena le metriche di report sono disponibili, puoi recuperarle. Sono disponibili quasi in tempo reale. Questi risultati iniziali sono però stime e, di conseguenza, è previsto che cambino. Le metriche vengono finalizzate dopo 24 ore, con l’eccezione dei dati di spesa.
• Le metriche di spesa sono generalmente definitive entro 3 giorni dall’evento. Tuttavia, elaboriamo i dati di fatturazione fino a 14 giorni dalla data dell’evento (ad esempio, per il filtraggio dello spam).

Come posso determinare quali id di entità richiedere per un periodo di tempo specifico?

• Usa l’endpoint Active Entities

Perché tutti i valori nella risposta di analytics sono null?

• È probabile che la campagna non sia stata erogata durante il periodo di tempo richiesto.
• Usa l’endpoint Active Entities per determinare per quali entità recuperare gli analytics e per quale periodo di tempo.

Perché l’API mostra valori null mentre la UI mostra 0?

• La UI sceglie di visualizzare questi valori come 0, ma i valori sono equivalenti.

Come posso richiedere metriche associate a un posizionamento granulare, come la timeline di X?

• Supportiamo i seguenti valori di posizionamento negli analytics: ALL_ON_TWITTER, PUBLISHER_NETWORK, SPOTLIGHT e TREND (ossia la X Audience Platform).

È possibile recuperare metriche per entità eliminate o in pausa?

• Sì. Lo stato dell’entità non influisce sulla disponibilità delle metriche di analytics.

Perché i valori segmentati non corrispondono a quelli non segmentati?

• Non è previsto che i dati segmentati si sommino al 100% ai dati non segmentati, a causa del modo in cui queste informazioni vengono derivate.

È possibile richiedere dati segmentati per più dimensioni?

• Non supportiamo la multi-segmentazione.

​

Best Practices

Alcune best practice per la raccolta dei dati di analytics tramite la X Ads API.

​

Limitazione della velocità e tentativi

• Per le query soggette a limite di velocità (quelle che restituiscono un codice di stato HTTP 429), è necessario esaminare l’header x-rate-limit-reset e riprovare solo all’orario indicato o successivamente.
• Per le query che restituiscono un codice di stato HTTP 503 Service Unavailable, è necessario esaminare l’header retry-after e riprovare solo dopo l’orario indicato.
• Le applicazioni che non rispettano gli orari indicati per i retry potrebbero vedersi revocare o limitare l’accesso alla X Ads API senza preavviso.

​

Metriche di Analytics in breve

• Tutte le metriche di analytics sono definitive e non cambiano dopo 24 ore, ad eccezione di billed_charge_local_micro.
• La metrica billed_charge_local_micro rimane una stima fino a 3 giorni dopo la restituzione dei data.
• Dopo 24 ore, questa metrica può diminuire a causa di accrediti per spesa eccessiva (annunci erogati dopo l’end_time specificato) e per eventi fatturabili classificati come junk. Dopo 24 ore, le variazioni di questa metrica sono minime.
• Consulta Analytics per ulteriori informazioni.

​

Recupero di dati in tempo reale non segmentati

• Fornisci sempre sia start_time sia end_time.
• Non recuperare dati per entità più vecchie di 7 giorni.
• Richiedi (idealmente) i dati con granularità HOUR, poiché puoi sempre aggregare e combinare le metriche per ottenere granularità DAY e TOTAL.
• Richiedi (idealmente) i dati a livello di line_items e promoted_tweets, poiché puoi sempre aggregare e combinare queste metriche per ottenere totali sull’intera gerarchia dell’entità pubblicitaria (ad es. a livello di campagna, strumento di finanziamento o account).
• Salva e archivia localmente i valori delle metriche di analytics.
• Non eseguire ripetutamente query per dati più vecchi di 30 giorni. Questi dati non cambieranno e dovrebbero essere archiviati localmente.
• Tutti i dati non segmentati sono in tempo reale e dovrebbero essere disponibili entro pochi secondi dal verificarsi di un evento.
• Raggruppa le metriche di conversione e quelle non di conversione in richieste separate.

​

Recupero di dati segmentati

• Fare riferimento alle linee guida fornite sopra per “Recupero di dati in tempo reale non segmentati”. Ulteriori indicazioni sono riportate di seguito.
• Per la maggior parte dei tipi di dati segmentati, può capitare che i dati non siano completi per un massimo di 1 ora. I dati segmentati per INTERESTS possono essere ritardati fino a 12 ore.
• Non è previsto che i dati segmentati tornino al 100% nei dati non segmentati, a causa del modo in cui queste informazioni vengono derivate.

​

Recupero dei dati storici

• Durante il backfilling dei dati (ad esempio quando aggiungi un nuovo account inserzionista), potrebbe essere necessario suddividere le richieste in più intervalli più piccoli utilizzando start_time e end_time.
• Limita l’intervallo di ciascun recupero a finestre di 30 giorni.
• Limita e distribuisci queste richieste nel tempo per evitare di esaurire i tuoi limiti di velocità per tali recuperi.

​

Esempio

Puoi trovare uno script di esempio che illustra alcune di queste best practice (fetch_stats) nel nostro repository ads-platform-tools su GitHub.

​

Metriche per obiettivo

Le metriche applicabili a un’entità dipendono dall’obiettivo della campagna. Utilizza questa guida per determinare i gruppi di metriche rilevanti da recuperare per ciascun tipo di obiettivo e come calcolare ulteriori metriche derivate.

​

ENGAGEMENTS

Gruppi di metriche rilevanti: ENGAGEMENT e BILLING. MEDIA è inoltre applicabile se nei creativi è presente contenuto multimediale.

Metrica derivata	Calcolo della metrica esposta
Tasso di engagement	engagements/impressions
CPE	billed_charge_local_micro/engagements
Tasso di visualizzazione dei media	media_views/impressions

​

WEBSITE_CLICKS e WEBSITE_CONVERSIONS

Gruppi di metriche rilevanti: ENGAGEMENT, BILLING e WEB_CONVERSION. MEDIA è inoltre applicabile se nei creativi viene utilizzato contenuto multimediale.

Metrica derivata	Calcolo della metrica esposta
CPM	billed_charge_local_micro/impressions/1000
Tasso di clic	clicks/impressions
CPLC	billed_charge_local_micro/clicks
Conversioni totali	conversion_custom + conversion_site_visits + conversion_sign_ups + conversion_downloads + conversion_purchases
Tasso di conversione	Conversioni totali / impressions
CPA	billed_charge_local_micro / Conversioni totali

​

APP_INSTALLS e APP_ENGAGEMENTS

Gruppi di metriche rilevanti: ENGAGEMENT, BILLING, MOBILE_CONVERSION e LIFE_TIME_VALUE_MOBILE_CONVERSION. MEDIA e VIDEO sono applicabili anche se nei creativi viene utilizzata una media o una video app card.

Metrica derivata	Calcolo della metrica esposta
CPM	billed_charge_local_micro/impressions/1000
App Click Rate	app_clicks/impressions
CPAC	billed_charge_local_micro/app_clicks
CPI	billed_charge_local_micro/mobile_conversion_installs

​

FOLLOWERS

Gruppi di metriche rilevanti: ENGAGEMENT e BILLING. MEDIA è applicabile anche se nei contenuti creativi vengono utilizzati media.

Metrica derivata	Calcolo della metrica esposta
CPM	billed_charge_local_micro/impressions/1000
Tasso di follow	follows/impressions
CPF	billed_charge_local_micro/follows
Tasso di visualizzazione dei media	media_views/impressions

​

LEAD_GENERATION

Gruppi di metriche rilevanti: ENGAGEMENT e BILLING. MEDIA è applicabile anche se nei creativi vengono utilizzati contenuti multimediali.

Metrica derivata	Calcolo della metrica esposta
CPM	billed_charge_local_micro/impressions/1000
Lead	card_engagements
Tasso di lead	card_engagements/impressions
Costo per lead	billed_charge_local_micro/card_engagements

​

VIDEO_VIEWS

Gruppi di metriche rilevanti: ENGAGEMENT, BILLING e VIDEO.

Metrica derivata	Calcolo della metrica esposta
CPM	billed_charge_local_micro/impressions/1000
Tasso di video	video_total_views/impressions
Costo per visualizzazione	billed_charge_local_micro/video_total_views

​

VIDEO_VIEWS_PREROLL

Gruppi di metriche pertinenti: ENGAGEMENT, BILLING e VIDEO.

Metrica derivata	Calcolo della metrica esposta
CPM	billed_charge_local_micro/impressions/1000
Tasso di visualizzazione video	video_total_views/impressions
Costo per visualizzazione	billed_charge_local_micro/video_total_views

​

Metriche e segmentazione

Questo documento offre una panoramica delle metriche disponibili nelle nostre Analytics per ciascun tipo di entità, oltre alle opzioni di segmentazione disponibili per ciascuna metrica.

	Gruppi di metriche
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	✔		✔

*Alcune metriche della famiglia ENGAGEMENT non sono disponibili a livello di account e di funding instrument. Consultare la sezione ENGAGEMENT per dettagli.

​

Metriche disponibili per gruppo di metriche

​

ENGAGEMENT

Metric	Descrizione	Segmentazione disponibile	Tipo di dati	Disponibile per Account / Strumento di finanziamento
engagements	Numero totale di engagement	✔	Array di int	✔
impressions	Numero totale di impression	✔	Array di int	✔
retweets	Numero totale di Retweet	✔	Array di int	✔
replies	Numero totale di risposte	✔	Array di int	✔
likes	Numero totale di like	✔	Array di int	✔
follows	Numero totale di follow	✔	Array di int	✔
card_engagements	Numero totale di engagement con la Card	✔	Array di int
clicks	Numero totale di clic, inclusi i like e altri engagement	✔	Array di int
app_clicks	Numero di tentativi di installazione o apertura dell’App	✔	Array di int
url_clicks	Numero totale di clic sul link o sulla Website Card in un annuncio, inclusi quelli earned	✔	Array di int
qualified_impressions	Numero totale di impression qualificate	✔	Array di int
carousel_swipes	Numero totale di swipe su immagini o video del Carousel	✔	Array di int

​

BILLING

Metica	Descrizione	Segmentazione disponibile	Tipo di dati
billed_engagements	Numero totale di engagement fatturati	✔	Array di interi
billed_charge_local_micro	Spesa totale in micro	✔	Array di interi

​

VIDEO

Avviso sulle modifiche alla definizione delle metriche video:

La metrica video_total_views all’interno del gruppo di metriche VIDEO riporterà tutte le visualizzazioni con almeno il 50% dell’area del video in-view per 2 secondi, secondo lo standard MRC.

La nostra definizione originale di visualizzazione video (100% in view per almeno 3 secondi) continuerà a essere disponibile come nuova metrica video_3s100pct_views nel gruppo di metriche VIDEO. Per continuare a fare offerte e a essere addebitato in base alla definizione originale, usa la nuova bid_unit VIEW_3S_100PCT.

Metrica	Descrizione	Segmentazione disponibile	Tipo di dato
video_total_views	Numero totale di visualizzazioni video	✔	Array di interi
video_views_25	Numero totale di visualizzazioni in cui è stato visto almeno il 25% del video	✔	Array di interi
video_views_50	Numero totale di visualizzazioni in cui è stato visto almeno il 50% del video	✔	Array di interi
video_views_75	Numero totale di visualizzazioni in cui è stato visto almeno il 75% del video	✔	Array di interi
video_views_100	Numero totale di visualizzazioni in cui è stato visto il 100% del video	✔	Array di interi
video_cta_clicks	Numero totale di clic sulla call to action	✔	Array di interi
video_content_starts	Numero totale di avvii della riproduzione video	✔	Array di interi
video_3s100pct_views	Numero totale di visualizzazioni in cui sono stati riprodotti almeno 3 secondi con il 100% in view (metrica legacy video_total_views)	✔	Array di interi
video_6s_views	Numero totale di visualizzazioni in cui sono stati visti almeno 6 secondi di video	✔	Array di interi
video_15s_views	Numero totale di visualizzazioni in cui sono stati visti almeno 15 secondi di video o il 95% della durata totale	✔	Array di interi

​

MEDIA

Metric	Descrizione	Segmentazione disponibile	Tipo di dato
media_views	Numero totale di visualizzazioni (autoplay e clic) dei contenuti multimediali su Video, Vine, GIF e Immagini.	✔	Array di int
media_engagements	Numero totale di clic sui contenuti multimediali su Video, Vine, GIF e Immagini.	✔	Array di int

​

WEB_CONVERSION

Metrica	Descrizione	Segmentazione disponibile	Tipo di dato
conversion_purchases	Numero di conversioni di tipo PURCHASE e il relativo importo di vendita e quantità dell’ordine	PLATFORMS soltanto	Oggetto JSON
conversion_sign_ups	Numero di conversioni di tipo SIGN_UP e il relativo importo di vendita e quantità dell’ordine	PLATFORMS soltanto	Oggetto JSON
conversion_site_visits	Numero di conversioni di tipo SITE_VISIT e il relativo importo di vendita e quantità dell’ordine	PLATFORMS soltanto	Oggetto JSON
conversion_downloads	Numero di conversioni di tipo DOWNLOAD e il relativo importo di vendita e quantità dell’ordine	PLATFORMS soltanto	Oggetto JSON
conversion_custom	Numero di conversioni di tipo CUSTOM e il relativo importo di vendita e quantità dell’ordine	PLATFORMS soltanto	Oggetto JSON

​

MOBILE_CONVERSION

Le statistiche sulle conversioni su dispositivi mobili sono disponibili solo per gli account pubblicitari abilitati a MACT.

Metrica	Descrizione	Segmentazione Disponibile	Tipo di Dati
mobile_conversion_spent_credits	Suddivisione delle conversioni mobile di tipo SPENT_CREDIT per post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Oggetto JSON
mobile_conversion_installs	Suddivisione delle conversioni mobile di tipo INSTALL per post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Oggetto JSON
mobile_conversion_content_views	Suddivisione delle conversioni mobile di tipo CONTENT_VIEW per post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Oggetto JSON
mobile_conversion_add_to_wishlists	Suddivisione delle conversioni mobile di tipo ADD_TO_WISHLIST per post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Oggetto JSON
mobile_conversion_checkouts_initiated	Suddivisione delle conversioni mobile di tipo CHECKOUT_INITIATED per post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Oggetto JSON
mobile_conversion_reservations	Suddivisione delle conversioni mobile di tipo RESERVATION per post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Oggetto JSON
mobile_conversion_tutorials_completed	Suddivisione delle conversioni mobile di tipo TUTORIAL_COMPLETED per post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Oggetto JSON
mobile_conversion_achievements_unlocked	Suddivisione delle conversioni mobile di tipo ACHIEVEMENT_UNLOCKED per post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Oggetto JSON
mobile_conversion_searches	Suddivisione delle conversioni mobile di tipo SEARCH per post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Oggetto JSON
mobile_conversion_add_to_carts	Suddivisione delle conversioni mobile di tipo ADD_TO_CART per post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Oggetto JSON
mobile_conversion_payment_info_additions	Suddivisione delle conversioni mobile di tipo PAYMENT_INFO_ADDITION per post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Oggetto JSON
mobile_conversion_re_engages	Suddivisione delle conversioni mobile di tipo RE_ENGAGE per post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Oggetto JSON
mobile_conversion_shares	Suddivisione delle conversioni mobile di tipo SHARE per post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Oggetto JSON
mobile_conversion_rates	Suddivisione delle conversioni mobile di tipo RATE per post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Oggetto JSON
mobile_conversion_logins	Suddivisione delle conversioni mobile di tipo LOGIN per post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Oggetto JSON
mobile_conversion_updates	Suddivisione delle conversioni mobile di tipo UPDATE per post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Oggetto JSON
mobile_conversion_levels_achieved	Suddivisione delle conversioni mobile di tipo LEVEL_ACHIEVED per post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Oggetto JSON
mobile_conversion_invites	Suddivisione delle conversioni mobile di tipo INVITE per post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Oggetto JSON
mobile_conversion_key_page_views	Suddivisione delle conversioni mobile di tipo KEY_PAGE_VIEW per post_view e post_engagement	✔	Oggetto JSON
mobile_conversion_downloads	Suddivisione delle conversioni mobile di tipo DOWNLOAD per post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Oggetto JSON
mobile_conversion_purchases	Suddivisione delle conversioni mobile di tipo PURCHASE per post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Oggetto JSON
mobile_conversion_sign_ups	Suddivisione delle conversioni mobile di tipo SIGN_UP per post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Oggetto JSON
mobile_conversion_site_visits	Suddivisione delle conversioni mobile di tipo SITE_VISIT per post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Oggetto JSON

​

LIFE_TIME_VALUE_MOBILE_CONVERSION

Le statistiche sulle conversioni mobile a valore cumulato (lifetime) sono disponibili solo per gli account inserzionista abilitati a MACT.

Metric	Descrizione	Segmentazione disponibile	Tipo di dati
mobile_conversion_lifetime_value_purchases	Dettaglio delle conversioni mobile di tipo PURCHASE		Oggetto JSON
mobile_conversion_lifetime_value_sign_ups	Dettaglio delle conversioni mobile di tipo SIGN_UP		Oggetto JSON
mobile_conversion_lifetime_value_updates	Dettaglio delle conversioni mobile di tipo UPDATE		Oggetto JSON
mobile_conversion_lifetime_value_tutorials_completed	Dettaglio delle conversioni mobile di tipo TUTORIAL_COMPLETED		Oggetto JSON
mobile_conversion_lifetime_value_reservations	Dettaglio delle conversioni mobile di tipo RESERVATION		Oggetto JSON
mobile_conversion_lifetime_value_add_to_carts	Dettaglio delle conversioni mobile di tipo ADD_TO_CART		Oggetto JSON
mobile_conversion_lifetime_value_add_to_wishlists	Dettaglio delle conversioni mobile di tipo ADD_TO_WISHLIST		Oggetto JSON
mobile_conversion_lifetime_value_checkouts_initiated	Dettaglio delle conversioni mobile di tipo CHECKOUT_INITIATED		Oggetto JSON
mobile_conversion_lifetime_value_levels_achieved	Dettaglio delle conversioni mobile di tipo LEVEL_ACHIEVED		Oggetto JSON
mobile_conversion_lifetime_value_achievements_unlocked	Dettaglio delle conversioni mobile di tipo ACHIEVEMENT_UNLOCKED		Oggetto JSON
mobile_conversion_lifetime_value_shares	Dettaglio delle conversioni mobile di tipo SHARE		Oggetto JSON
mobile_conversion_lifetime_value_invites	Dettaglio delle conversioni mobile di tipo INVITE		Oggetto JSON
mobile_conversion_lifetime_value_payment_info_additions	Dettaglio delle conversioni mobile di tipo PAYMENT_INFO_ADDITION		Oggetto JSON
mobile_conversion_lifetime_value_spent_credits	Dettaglio delle conversioni mobile di tipo SPENT_CREDIT		Oggetto JSON
mobile_conversion_lifetime_value_rates	Dettaglio delle conversioni mobile di tipo RATE		Oggetto JSON

​

Segmentazione

La reportistica di segmentazione consente di recuperare metriche suddivise in base ai valori di un determinato tipo di targeting. La segmentazione è disponibile solo tramite query di analytics asincrone a causa della loro notevole complessità aggiuntiva.

La segmentazione non è supportata per le entità MEDIA_CREATIVE o ORGANIC_TWEET.

Alcuni tipi di segmentazione richiedono parametri aggiuntivi. Sono documentati di seguito.

Quando si segmenta per CITIES o POSTAL_CODES, l’API restituirà solo le località targetizzate. La segmentazione per regioni e aree metropolitane restituirà sia località targetizzate sia non targetizzate.

Tipo di segmentazione	parametro country richiesto	parametro platform richiesto
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

​

Metriche derivate

Le metriche di una campagna dipendono dal relativo campaign objective. Usa questa guida per determinare come calcolare le metriche derivate da utilizzare in base agli obiettivi in vigore.

Qualsiasi metric senza parentesi graffe è una metrica restituita dagli endpoint di analytics della X Ads API. Qualsiasi nome racchiuso tra {parentesi graffe} indica una metrica derivata per quella categoria.

​

COINVOLGIMENTO

Metrica derivata	Calcolo metrica esposta
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions
billed_charge_local_micro / {Impressions} / 1000
{Totale coinvolgimenti}	promoted_account_follows + promoted_tweet_search_engagements + promoted_tweet_timeline_engagements + promoted_tweet_profile_engagements oppure 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
{Tasso di coinvolgimento}	{Total Engagements} / {Impressions}
billed_charge_local_micro / {Total Engagements}
{Visualizzazioni media}	promoted_tweet_timeline_media_views + promoted_tweet_search_media_views + promoted_tweet_profile_media_views
{Tasso di visualizzazione dei media}	{Media Views} / {Impressions}

​

WEBSITE_CLICKS

Metrica derivata	Calcolo metrica esposta
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions
billed_charge_local_micro / {Impressions} / 1000
{Link Clicks}	promoted_tweet_search_url_clicks + promoted_tweet_timeline_url_clicks + promoted_tweet_profile_url_clicks
{Click Rate}	{Link Clicks} / {Impressions}
billed_charge_local_micro / {Link Clicks}
conversion_site_visits
{Conversion Rate}	conversion_site_visits / {Impressions}
billed_charge_local_micro / conversion_site_visits

​

APP_INSTALLS e APP_ENGAGEMENTS

Metrica derivata	Calcolo della metrica esposta
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

​

FOLLOWERS

Metrica derivata	Calcolo della metrica esposta
promoted_account_impressions
billed_charge_local_micro / {Impressions} / 1000
promoted_account_follows
{Tasso di follow}	promoted_account_follow_rate
billed_charge_local_micro / promoted_account_follows
{Visualizzazioni dei media}	promoted_tweet_timeline_media_views + promoted_tweet_search_media_views + promoted_tweet_profile_media_views
{Tasso di visualizzazioni dei media}	{Media Views} / {Impressions}

​

LEAD_GENERATION

Metrica derivata	Calcolo metrica esposta
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
{Lead Rate}	{Leads} / {Impressions}
{Cost Per Lead}	billed_charge_local_micro / {Leads}

​

VIDEO_VIEWS

Metrica derivata	Calcolo della metrica esposta
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions
billed_charge_local_micro / {Impressions} / 1000
{Video Views}	promoted_video_total_views
{Video Rate}	promoted_video_total_views / {Impressions}
{Cost Per View}	billed_charge_local_micro / promoted_video_total_views

​

QUALIFIED_IMPRESSIONS

Metrica derivata	Calcolo della metrica esposta
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

​

PERSONALIZZATO

Per placement_type di PROMOTED_ACCOUNT, consulta l’obiettivo FOLLOWERS sopra. Per tutti gli altri placement con questo obiettivo, consulta ENGAGEMENTS per le corrispondenti metriche derivate.

​

Guide

​

Entità attive

​

Introduzione

L’endpoint Active Entities è progettato per essere utilizzato in combinazione con i nostri endpoint di analytics sincroni e asincroni, in quanto fornisce indicazioni su quali campagne richiedere per le analisi. Lo fa restituendo dettagli sulle entità pubblicitarie e su quando le loro metriche sono cambiate. L’uso di questo endpoint semplificherà notevolmente il codice e la logica di raccolta delle analytics.

Questa guida include informazioni e contesto sull’endpoint e sulla relativa fonte dati. Fornisce inoltre le linee guida di utilizzo e una serie di esempi di richieste che mostrano come usare Active Entities insieme ai nostri endpoint di analytics. La sezione Riepilogo offre una descrizione di alto livello dell’approccio consigliato.

​

Dati

Ogni volta che cambia una metrica di un’entità pubblicitaria, registriamo informazioni su tale modifica. Questi eventi di modifica sono memorizzati in aggregazioni orarie e includono dettagli sull’entità e sull’istante a cui si riferisce la modifica. Questo è necessario perché gli eventi di modifica non corrispondono sempre al momento in cui vengono registrati. Gli adeguamenti di fatturazione sono un motivo comune, ma non l’unico.

​

Endpoint

​

Richiesta

Le richieste Active Entities sono inquadrate negli account pubblicitari e includono tre parametri di query obbligatori: entity, start_time e 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"

Sono supportati i seguenti valori per entity: CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE, PROMOTED_ACCOUNT e PROMOTED_TWEET. Questo riflette i tipi di entità supportati dai nostri endpoint di analytics.

I valori start_time e end_time devono essere espressi in formato ISO 8601 e indicare quali intervalli orari (hourly buckets) interrogare. Devono essere in ore intere.

Questo endpoint supporta anche tre parametri opzionali che possono essere usati per filtrare i risultati: funding_instrument_ids, campaign_ids e line_item_ids. Questi funzionano a tutti i livelli della gerarchia degli annunci e con qualsiasi tipo di entity specificato.

​

Risposta

Di seguito è riportata la risposta di Active Entities per la richiesta precedente.

    {
      "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"
          ]
        }
      ]
    }

L’array data include un oggetto per ogni entità da includere in una successiva richiesta di analytics. Non richiedere analytics per ID al di fuori di questo insieme.

Ogni oggetto include quattro fields: entity_id, activity_start_time, activity_end_time e placements. Gli orari di inizio e fine attività rappresentano l’intervallo temporale a cui si applicano gli eventi di modifica dell’entità associata e, di conseguenza, determinano le date da specificare nelle successive richieste di analytics. L’array placements può includere i seguenti valori: ALL_ON_TWITTER, PUBLISHER_NETWORK, SPOTLIGHT e TREND. Indica quali placement devono essere richiesti per il relativo ID dell’entità.

​

Utilizzo

L’endpoint Active Entities dovrebbe stabilire come effettuare le richieste di analytics. Le seguenti linee guida d’uso sono pensate per supportare la sincronizzazione degli analytics, consentendo ai partner di mantenere i propri archivi dati allineati con X. In altre parole, descrivono come eseguire sincronizzazioni periodiche in background.

Ci sono due decisioni che uno sviluppatore deve prendere.

1. Con quale frequenza richiedere le informazioni sulle entità attive e, di conseguenza, con quale frequenza acquisire gli analytics.
2. Come utilizzare gli orari di inizio e fine dell’attività per determinare i valori di start_time e end_time della richiesta di analytics.

Questi aspetti sono approfonditi nelle due sottosezioni seguenti, dopo il riepilogo.

​

Riepilogo

Usa l’endpoint Active Entities nel modo seguente per definire come effettuare le richieste di analytics. Segui queste indicazioni dopo aver stabilito con quale frequenza richiedere le informazioni sulle entità attive e, di conseguenza, con quale frequenza acquisire le analytics.

1. Esegui la richiesta Active Entities.
2. Suddividi la risposta per placement: un gruppo per ALL_ON_TWITTER, uno per PUBLISHER_NETWORK, uno per SPOTLIGHT e uno per TREND.
3. Per ciascun gruppo di placement, procedi come segue.
   1. Estrai gli id delle entità.
   2. Determina i valori di start_time e end_time per le analytics.
      • Trova il valore minimo di activity_start_time. Arrotondalo per difetto.
      • Trova il valore massimo di activity_end_time. Arrotondalo per eccesso.
   3. Esegui la/le richiesta/e di analytics.
      • Raggruppa gli id delle entità in batch da 20.
      • Usa i valori di start_time e end_time dal punto 3b.
      • Specifica il valore di placement appropriato.
   4. Scrivi nel tuo data store.

Consulta active_entities.py come esempio che utilizza il Python SDK.

​

Frequenza

La risposta alla prima domanda determina l’intervallo di tempo da usare nelle richieste di Active Entities. Ad esempio, se si richiedono informazioni sulle entità attive ogni ora, l’intervallo dovrebbe essere di un’ora. Se si richiedono informazioni sulle entità attive una volta al giorno, l’intervallo dovrebbe essere di un giorno. In altre parole, gli intervalli vanno scelti in modo che il start_time della richiesta corrente sia uguale all’end_time della richiesta precedente.

Nota: Una finestra temporale andrebbe richiesta una sola volta. Richiedere la stessa finestra più di una volta genera richieste di analytics non necessarie. (Eccezione di seguito.)

Per i partner che desiderano richiedere analytics più volte all’ora per l’ora corrente, si applica lo stesso schema: la frequenza determina l’intervallo di tempo. La tabella seguente mostra esempi di timestamp di inizio e fine di Active Entities per questo scenario.

Ora della richiesta	timestamp di start_time	timestamp di 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

Dato il modo in cui gli eventi di modifica vengono archiviati, tutte e quattro le richieste di Active Entities sopra interrogano lo stesso bucket orario, necessario per questo caso d’uso. Tuttavia, terminata l’ora corrente, questo bucket orario non dovrebbe più essere interrogato.

​

Orari di attività

Consigliamo il seguente approccio per gestire gli orari di inizio e fine dell’attività. In tutti gli oggetti nella risposta Active Entities, individua il activity_start_time minimo e il activity_end_time massimo. Modifica questi valori arrotondando per difetto l’orario minimo di inizio attività e per eccesso l’orario massimo di fine attività. In particolare, imposta a zero i timestamp per entrambi e aggiungi un giorno all’orario di fine, come illustrato nella tabella seguente. Questi sono gli orari di inizio e fine che dovrebbero essere specificati nelle richieste di analytics successive.

Orari min e max di attività	Orari derivati
2019-03-04T20:55:20Z 2019-03-05T14:40:59Z	2019-03-04T00:00:00Z 2019-03-06T00:00:00Z

Nota: È importante includere i timestamp con ore, minuti e secondi impostati a zero. Altrimenti, se viene fornita solo la data, presumeremo che tu stia richiedendo analytics con inizio e fine a mezzanotte nel fuso orario dell’account ads, il che potrebbe non essere desiderabile. Ad esempio, se l’orario minimo di inizio attività è 2019-02-28T01:30:07Z e il timestamp viene omesso per un account ads con offset -08:00:00, la richiesta di analytics non includerà le modifiche avvenute tra le 01:30 e le 08:00.

In alternativa, se preferisci richiedere analytics solo per la finestra temporale di attività restituita senza estenderla a giornate intere, puoi farlo. Con questo approccio, gli orari di inizio e fine derivati sarebbero rispettivamente 2019-03-04T20:00:00Z e 2019-03-05T15:00:00Z. (Nota: intervalli di questo tipo non sono accettati se specifichi la granularità DAY nella richiesta di analytics.)

​

Esempio

Questa sezione mostra come utilizzare Active Entities insieme all’endpoint di analytics sincrono. (Le risposte sono state leggermente modificate per migliorarne la leggibilità.) In questo esempio, l’endpoint Active Entities viene chiamato all’inizio di ogni ora, e ogni richiesta prende in esame l’ora precedente. La risposta determina come viene utilizzato l’endpoint di analytics sincrono.

La prima richiesta a Active Entities viene effettuata alle 03:00:00. La risposta indica che le metriche della line item dvcz7 sono cambiate e che tali eventi di modifica si applicano alla finestra compresa tra 02:02:55 e 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"
          ]
        }
      ]
    }

Sulla base di questi tempi di inizio e fine attività e utilizzando l’approccio descritto sopra, i valori di analytics start_time e end_time sono impostati rispettivamente su 2019-02-11T00:00:00Z e 2019-02-12T00:00:00Z. Notiamo che il terzo elemento in ciascuno degli array di metriche qui sotto è diverso da zero, come previsto in base alle informazioni sulle entità attive.

`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 successiva richiesta Active Entities avviene alle 04:00:00 e prende in considerazione solo l’ora precedente. Come indicato sopra, una finestra temporale dovrebbe essere richiesta una sola volta. In base alla risposta, vediamo che gli eventi di modifica per questo line item si applicano a sia 02:00:00 che 03:00:00. Nella successiva richiesta di analytics, ci aspettiamo di vedere modifiche per entrambe le ore.

`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"
          ]
        }
      ]
    }

Oltre a vedere metriche non nulle per le 03:00:00, notiamo che le impression, la spesa e le visualizzazioni video MRC sono state aggiornate rispetto ai valori precedenti. Le impression, ad esempio, sono ora pari a 2.995 per l’ora 02:00:00, in aumento rispetto a 2.792. Ciò dimostra come gli eventi di modifica registrati durante l’ora 03:00:00 si applichino all’ora 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 richiesta Active Entities alle 05:00:00, considerando nuovamente solo l’ora precedente, mostra che gli eventi di modifica si applicano esclusivamente all’ora 03:00:00. Le variazioni alle metriche di analytics nella richiesta successiva lo confermano.

`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 risposta di analytics mostra che sono cambiate solo le metriche dell’ora 03:00:00; i valori dell’ora 02:00:00 sono gli stessi della precedente richiesta di 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": {}
    }

Infine, alle 06:00:00 constatiamo che non ci sono ulteriori eventi di modifica. Nota: ciò non implica, però, che le metriche per questa voce di riga non possano cambiare in futuro.

`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": []
    }

​

Guida all’asincronia

​

Riferimento all’API

​

Analisi asincrone

​

Introduzione

Gli endpoint di analytics asincroni consentono a partner e inserzionisti di richiedere metriche inviando richieste di creazione che il server elabora in modo asincrono. (Li definiamo “job” di analytics asincroni.) Con questo approccio, la connessione del client non deve rimanere aperta fino all’evasione della richiesta.

Questi endpoint, come la loro controparte sincrona, consentono a partner e inserzionisti di richiedere statistiche dettagliate sulle prestazioni delle campagne. Supportano la richiesta di dati per account, strumenti di finanziamento, campagne, elementi di riga, Tweet promossi e creatività multimediali. La differenza rispetto all’endpoint sincrono è che gli endpoint di analytics asincroni supportano intervalli temporali più estesi, fino a 90 giorni, oltre alla segmentazione. Ulteriori dettagli sulle differenze tra i due sono disponibili nella nostra pagina Panoramica su Analytics.

A differenza dei nostri endpoint sincroni, il rate limit si basa sul numero di job concorrenti per un determinato account. In altre parole, si basa sul numero di job che possono trovarsi nello stato di elaborazione in un dato momento. Effettuiamo il conteggio a livello di account pubblicitario.

​

Utilizzo

Il recupero delle metriche di campagna tramite gli endpoint di analytics asincroni è un processo in più fasi: prevede la creazione di un job, la verifica del termine dell’elaborazione e, infine, il download dei dati. Il file dei dati deve essere decompresso. I quattro passaggi specifici sono illustrati di seguito.

1. Crea il job utilizzando l’endpoint POST stats/jobs/accounts/:account_id.
2. Effettua richieste a intervalli regolari all’endpoint GET stats/jobs/accounts/:account_id per verificare se il job ha terminato l’elaborazione.
3. Una volta che il job ha terminato l’elaborazione, scarica il file dei dati.
4. Decomprimi il file dei dati.

L’oggetto di risposta restituito nel file dei dati ha lo stesso schema JSON della risposta dell’endpoint di analytics sincrono.

Le metriche di campagna segmentate sono disponibili solo tramite gli endpoint di analytics asincroni. Le metriche di campagna possono essere suddivise per località, genere, interessi, parole chiave e altro. Per l’elenco completo delle opzioni, consulta la pagina Metrics and Segmentation. Per richiedere metriche segmentate, utilizza il parametro di richiesta segmentation_type quando crei il job.

​

Esempio

Questa sezione illustra come utilizzare gli endpoint di analytics asincroni.

Inizia creando un job tramite l’endpoint POST stats/jobs/accounts/:account_id. Nell’esempio seguente vengono richieste le metriche di engagement — come impression, like, clic, ecc. — per uno specifico line item nell’arco di una settimana. (Nota: l’intervallo temporale richiesto arriva fino al 20 marzo escluso, poiché il timestamp è impostato a mezzanotte.)

$ 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"
        ]
      }
    }

Questa risposta non restituisce le metriche della riga di dettaglio. Fornisce semplicemente informazioni sul job che hai appena creato. L’id del job è necessario per verificarne lo stato. Questo è riportato negli attributi di risposta id e id_str.

Successivamente, dovrai verificare se il job che hai creato utilizzando l’id_str della risposta precedente ha terminato l’elaborazione, come indicato da "status": "SUCCESS" nella risposta. Ciò significa che i dati sono pronti per il download. Il campo url contiene il link per lo scaricamento.

$ 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"
          ]
        }
      ]
    }

Sebbene nell’esempio sopra venga passato un singolo job ID, in pratica è consigliabile usare il parametro job_ids per verificare lo stato di più job alla volta, specificando fino a 200 job ID.

Quindi, scarica il file di dati utilizzando il valore url indicato.

    $ 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
    Risoluzione di ton.twimg.com (ton.twimg.com)... 72.21.91.70
    Connessione a ton.twimg.com (ton.twimg.com)|72.21.91.70|:443... connesso.
    Richiesta HTTP inviata, in attesa di risposta... 200 OK
    Lunghezza: 381 [application/gzip]
    Salvataggio in: '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' salvato [381/381]

Infine, estrai il file.

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

Il contenuto del file è riportato di seguito.

`$ 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"
          ]
        }
      }
    }

​

Copertura e frequenza media

Apri in Postman

​

GET stats/accounts/:account_id/reach/campaigns

Recupera le metriche di copertura (reach) e frequenza media per le campagne specificate.

​

URL della risorsa

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

​

Parametri

Nome	Descrizione
account_id obbligatorio	Identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è in genere un parametro obbligatorio per tutte le richieste dell’API per inserzionisti, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
campaign_ids obbligatorio	Limita la risposta alle sole campagne desiderate specificando un elenco di identificatori separati da virgole. È possibile fornire fino a 20 ID. Nota: È possibile fornire fino a 20 ID campagna. Tipo: string Esempio: 8fgzf
end_time obbligatorio	Limita i dati recuperati all’ora di fine specificata, espressa in ISO 8601. Nota: Deve essere espressa in ore piene (0 minuti e 0 secondi). Tipo: string Esempio: 2017-05-26T07:00:00Z
start_time obbligatorio	Limita i dati recuperati all’ora di inizio specificata, espressa in ISO 8601. Nota: Deve essere espressa in ore piene (0 minuti e 0 secondi). Tipo: string Esempio: 2017-05-19T07:00:00Z

​

Esempio di richiesta

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

​

Esempio di risposta

    {
      "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

Recupera le metriche di copertura e frequenza media per gli strumenti di finanziamento specificati.

​

URL della risorsa

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

​

Parametri

Nome	Descrizione
account_id obbligatorio	Identificatore dell’account leveraged. Compare nel percorso della risorsa ed è in genere un parametro obbligatorio per tutte le richieste dell’Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
funding_instrument_ids obbligatorio	Limita la risposta ai soli strumenti di finanziamento desiderati specificando un elenco di identificatori separati da virgole. È possibile fornire fino a 20 ID. Nota: È possibile fornire fino a 20 ID di strumenti di finanziamento. Tipo: string Esempio: lygyi
end_time obbligatorio	Limita i dati restituiti all’ora di fine specificata, espressa in ISO 8601. Nota: Deve essere espressa in ore intere (0 minuti e 0 secondi). Tipo: string Esempio: 2017-05-26T07:00:00Z
start_time obbligatorio	Limita i dati restituiti all’ora di inizio specificata, espressa in ISO 8601. Nota: Deve essere espressa in ore intere (0 minuti e 0 secondi). Tipo: string Esempio: 2017-05-19T07:00:00Z

​

Esempio di richiesta

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

​

Esempio di risposta

    {
      "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
        }
      ]
    }

​

Analisi sincrona

Apri in Postman

​

GET stats/accounts/:account_id

Recupera le analisi sincrone per l’account corrente. È consentito un intervallo temporale massimo (end_time - start_time) di 7 giorni.

​

URL della risorsa

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

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
end_time obbligatorio	Limita i data recuperati all’ora di fine specificata, espressa in ISO 8601. Nota: Deve essere espressa in ore intere (0 minuti e 0 secondi). Tipo: string Esempio: 2017-05-26T07:00:00Z
entity obbligatorio	Il tipo di entità per cui recuperare i data. Tipo: enum Valori possibili: ACCOUNT, CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, ORGANIC_TWEET, PROMOTED_ACCOUNT, PROMOTED_TWEET, MEDIA_CREATIVE
entity_ids obbligatorio	Le entità specifiche per cui recuperare i data. Specificare un elenco di ID di entità separati da virgola. Nota: È possibile fornire fino a 20 ID di entità. Tipo: string Esempio: 8u94t
granularity obbligatorio	Specifica il livello di granularità dei data restituiti. Tipo: enum Valori possibili: DAY, HOUR, TOTAL
metric_groups obbligatorio	Le metriche specifiche da restituire. Specificare un elenco di gruppi di metriche separati da virgola. Per maggiori informazioni, vedere Metrics and Segmentation. Nota: I data relativi a MOBILE_CONVERSION devono essere richiesti separatamente. Tipo: enum Valori possibili: BILLING, ENGAGEMENT, LIFE_TIME_VALUE_MOBILE_CONVERSION, MEDIA, MOBILE_CONVERSION, VIDEO, WEB_CONVERSION
placement obbligatorio	Limita i data recuperati a una specifica collocazione. Nota: È accettato un solo valore per richiesta. Per le entità con collocazione sia su X sia su X Audience Platform, sono necessarie richieste separate, una per ciascun valore di collocazione. Tipo: enum Valori possibili: ALL_ON_TWITTER, PUBLISHER_NETWORK, SPOTLIGHT, TREND
start_time obbligatorio	Limita i data recuperati all’ora di inizio specificata, espressa in ISO 8601. Nota: Deve essere espressa in ore intere (0 minuti e 0 secondi). Tipo: string Esempio: 2017-05-19T07:00:00Z

​

Esempio di richiesta

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

​

Esempio di risposta

    {
      "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à attive

Apri in Postman

​

GET stats/accounts/:account_id/active_entities

Recupera i dettagli su quali metriche di analytics delle entità sono cambiate in un determinato periodo di tempo.

Questo endpoint va utilizzato insieme ai nostri endpoint di analytics. I risultati di questo endpoint indicano per quali entità pubblicitarie richiedere gli analytics. Consulta la nostra Guida alle entità attive per le linee guida d’uso.

Gli eventi di modifica sono disponibili in aggregazioni orarie.

• I valori start_time e end_time specificano quali intervalli orari interrogare.
• L’array data restituito includerà un oggetto per ogni entità che deve essere inclusa nelle richieste di analytics successive.
• IMPORTANTE: Le date da specificare nelle richieste di analytics successive vanno determinate in base ai valori activity_start_time e activity_end_time.
  • Questi valori rappresentano gli intervalli di tempo a cui si applicano gli eventi di modifica memorizzati. Questo è restituito per singola entità.

Nota: È consentito un intervallo di tempo massimo (end_time - start_time) di 90 giorni.

​

URL della risorsa

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

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API per gli inserzionisti, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
end_time obbligatorio	Limita i dati recuperati all’ora di fine specificata, espressa in ISO 8601. Nota: Deve essere espressa in ore intere (0 minuti e 0 secondi). Tipo: string Esempio: 2017-05-26T07:00:00Z
entity obbligatorio	Il tipo di entità per cui recuperare i dati. Tipo: enum Valori possibili: CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE, PROMOTED_ACCOUNT, PROMOTED_TWEET
start_time obbligatorio	Limita i dati recuperati all’ora di inizio specificata, espressa in ISO 8601. Nota: Deve essere espressa in ore intere (0 minuti e 0 secondi). Tipo: string Esempio: 2017-05-19T07:00:00Z
campaign_ids opzionale	Limita la risposta alle sole entità associate alle campagne desiderate specificando un elenco di identificatori separati da virgola. È possibile fornire fino a 200 ID. Nota: Mutuamente esclusivo con funding_instrument_ids e line_item_ids. Tipo: string Esempio: 8wku2
funding_instrument_ids opzionale	Limita la risposta alle sole entità associate agli strumenti di finanziamento desiderati specificando un elenco di identificatori separati da virgola. È possibile fornire fino a 200 ID. Nota: Mutuamente esclusivo con campaign_ids e line_item_ids. Tipo: string Esempio: lygyi
line_item_ids opzionale	Limita la risposta alle sole entità associate alle line item desiderate specificando un elenco di identificatori separati da virgola. È possibile fornire fino a 200 ID. Nota: Mutuamente esclusivo con campaign_ids e line_item_ids. Tipo: string Esempio: 8v7jo

​

Esempio di richiesta

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

​

Esempio di risposta

    {
      "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"
          ]
        }
      ]
    }