Analytics

​

Introdução

As métricas de analytics ajudam parceiros e anunciantes a entender o desempenho do conteúdo que promovem no X. Isso inclui informações como impressões, cliques, visualizações de vídeo e investimento. Além disso, parceiros e anunciantes podem obter métricas detalhadas para vários segmentos das audiências que alcançam.

A X Ads API oferece duas maneiras de recuperar métricas detalhadas de desempenho de campanha: de forma síncrona e assíncrona. Com chamadas de analytics síncronas, as métricas solicitadas são retornadas na resposta. Com os endpoints de analytics assíncronos, as métricas solicitadas ficam disponíveis em um arquivo de resultados para download após a conclusão do processamento do “job” associado. O endpoint síncrono oferece suporte a intervalos de tempo curtos e é ideal para otimizações de campanha em tempo real. Os endpoints assíncronos oferecem suporte a intervalos de tempo muito mais longos e, portanto, destinam-se à obtenção de muito mais dados, sendo ideais para gerar relatórios ou preenchimentos históricos.

​

Detalhes

​

Sincrônico vs. Assíncrono

As diferenças entre os endpoints de analytics sincrônicos e assíncronos são resumidas na tabela a seguir. Essas informações ajudam desenvolvedores a escolher qual conjunto de endpoints usar.

Recurso	Sincrônico	Assíncrono
Limite de taxa	Nível de usuário: 250 solicitações/15 minutos	Nível de conta: 100 jobs simultâneos*
Intervalo de tempo	7 dias	90 dias (não segmentado) 45 dias (segmentado)
Segmentação	Não	Sim
Retorno da resposta	Dados de metrics	Estado de processamento do job**
Caso de uso recomendado	Otimização em tempo real Solicitações da interface do usuário	Sincronização agendada regularmente Backfill de dados históricos

• Refere-se ao número máximo de jobs que podem estar em estado de processamento a qualquer momento.

** Quando o job conclui o processamento com sucesso, é retornada uma URL. É nela que o arquivo de resultados compactado (gzip) pode ser baixado.

Fora isso, os endpoints oferecem a mesma funcionalidade.

​

Casos de uso

Há três principais casos de uso de analytics.

1. Otimização em tempo real: uso de metrics de desempenho para atualizar campanhas ativas
2. Sincronização: sincronizações em segundo plano agendadas regularmente
3. Onboarding de nova conta: preenchimento retroativo de data histórica

O endpoint síncrono de analytics pode ser usado para otimização em tempo real, atualizando campanhas com base em alterações nas metrics nos últimos 5 a 15 minutos. Qualquer endpoint pode ser usado para sincronização de analytics. Lembre-se de que o intervalo de tempo desejado e a necessidade de segmentação determinarão qual endpoint usar. O onboarding de novas contas deve ser feito apenas usando os endpoints assíncronos de analytics. (O endpoint síncrono de analytics nunca deve ser usado para recuperar grandes quantidades de data.)

Os endpoints assíncronos de analytics podem alimentar dashboards e outros elementos de UI se as metrics forem sincronizadas com um processo de backend. Sua implementação deve evitar chamar os endpoints assíncronos de analytics para atender solicitações da interface do usuário.

​

Opções de solicitação

As solicitações de analytics são restritas a contas de anúncios e, portanto, exigem o ID da conta no caminho do recurso. As opções de solicitação, listadas abaixo, são especificadas como parâmetros de query. Os seguintes tipos de valores são obrigatórios.

• Entidades: o tipo de entidade e até 20 IDs de entidade para os quais você deseja solicitar analytics
• Intervalo de tempo: os horários de início e término, em ISO 8601
  • Observação: devem estar em horas inteiras
• Grupos de métricas: um ou mais conjuntos de metrics relacionadas (consulte Métricas e Segmentação para a lista de metrics em cada grupo de métricas)
• Granularidade: especifica o nível de agregação em que as metrics devem ser retornadas
• Posicionamento: determina se as metrics são coletadas para anúncios veiculados dentro ou fora do X
  • Observação: apenas um valor de posicionamento pode ser especificado por solicitação

Use os parâmetros de solicitação start_time e end_time para especificar um intervalo de tempo. Esses valores devem estar alinhados com a granularidade especificada da seguinte forma.

1. TOTAL: especifique qualquer intervalo de tempo (dentro dos limites do endpoint)
2. DAY: os horários de início e término devem estar alinhados à meia-noite no fuso horário da conta
3. HOUR: especifique qualquer intervalo de tempo (dentro dos limites do endpoint)

O horário de término é exclusivo. Por exemplo, uma solicitação com start_time=2019-01-01T00:00:00Z e end_time=2019-01-02T00:00:00Z retornará apenas um dia de metrics de analytics (e não dois), pois esse intervalo cobre apenas 24 horas.

Segmentação

Disponível apenas por meio de nossos endpoints de analytics assíncronos, a segmentação permite que parceiros e anunciantes obtenham metrics detalhadas por determinados valores de segmentação. Para solicitar metrics segmentadas, use o parâmetro de solicitação segmentation_type. Para mais detalhes sobre as opções de segmentação, consulte Métricas e Segmentação.

​

Perguntas frequentes

Por que os números da X Ads API não correspondem ao que é exibido na X Ads UI?

• Certifique-se de ter solicitado dados para ambos os placements: ALL_ON_TWITTER e PUBLISHER_NETWORK, SPOTLIGHT e TREND.
• Lembre-se de que os horários de término na Ads API são exclusivos; na Ads UI, eles são inclusivos.

Por que os números mudam dependendo de quando eu solicito dados?

• Assim que as metrics de relatórios estiverem disponíveis, você poderá recuperá-las. Elas ficam disponíveis quase em tempo real. No entanto, esses resultados iniciais são estimativas e, portanto, tendem a mudar. As metrics são finalizadas após 24 horas, com exceção dos dados de spend.
• As metrics de spend geralmente se tornam finais dentro de 3 dias do evento. No entanto, processamos dados de faturamento por até 14 dias a partir da data do evento (por exemplo, para filtragem de spam).

Como posso determinar quais IDs de entidades solicitar para um período específico?

• Use o endpoint Active Entities

Por que todos os valores na resposta de analytics estão null?

• É provável que a campanha não tenha sido veiculada durante o período solicitado.
• Use o endpoint Active Entities para determinar para quais entidades buscar analytics e para qual período.

Por que a API mostra valores null enquanto a UI mostra 0?

• A UI opta por exibir esses valores como 0, mas eles são equivalentes.

Como posso solicitar metrics associadas a um placement granular, como a timeline do X?

• Oferecemos suporte aos seguintes valores de placement em analytics: ALL_ON_TWITTER e PUBLISHER_NETWORK, SPOTLIGHT e TREND (ou seja, a X Audience Platform).

É possível recuperar metrics de entidades excluídas ou pausadas?

• Sim. O status da entidade não impacta a disponibilidade das analytics metrics.

Por que os valores segmentados não correspondem aos não segmentados?

• Não se espera que os dados segmentados se agreguem em 100% aos dados não segmentados, devido à forma como essas informações são derivadas.

É possível solicitar dados segmentados por várias dimensões?

• Não oferecemos suporte a multissegmentação.

​

Melhores práticas

Algumas melhores práticas ao coletar dados de analytics da X Ads API.

​

Limitação de taxa e novas tentativas

• Em consultas sujeitas a limite de taxa (que retornam o status HTTP 429), você deve verificar o cabeçalho x-rate-limit-reset e tentar novamente somente no horário indicado ou depois.
• Em consultas que resultarem no status HTTP 503 Service Unavailable, você deve verificar o cabeçalho retry-after e tentar novamente somente após o horário indicado.
• Apps que não respeitarem os horários indicados para novas tentativas podem ter seu acesso à X Ads API revogado ou sofrer redução (throttling) sem aviso prévio.

​

Métricas de Analytics em poucas palavras

• Todas as métricas de analytics ficam bloqueadas e não mudam após 24 horas, com exceção de billed_charge_local_micro.
• A métrica billed_charge_local_micro é uma estimativa por até 3 dias após o retorno dos dados.
• Após 24 horas, essa métrica pode diminuir devido a créditos por gasto excedente (anúncios veiculados após o end_time especificado) e por eventos faturáveis considerados inválidos. Essa métrica muda minimamente após 24 horas.
• Consulte Analytics para mais informações.

​

Coleta de dados em tempo real, não segmentados

• Sempre forneça start_time e end_time.
• Não colete dados de entidades com mais de 7 dias.
• Solicite dados (de preferência) com granularidade HOUR, pois você sempre pode agregar e consolidar metrics para obter as granularidades DAY e TOTAL.
• Solicite dados (de preferência) nos níveis line_items e promoted_tweets, pois você sempre pode agregar e consolidar essas metrics para obter totais em toda a hierarquia de entidades de anúncios (ou seja, nos níveis de campanha, instrumento de financiamento ou conta).
• Salve e armazene localmente os valores das analytics metrics.
• Não faça query repetidas vezes por dados com mais de 30 dias. Esses dados não mudarão e devem ser armazenados localmente.
• Todos os dados não segmentados são em tempo real e devem estar disponíveis em segundos após a ocorrência de um evento.
• Agrupe metrics de conversão e de não conversão em solicitações separadas.

​

Obtenção de dados segmentados

• Consulte as diretrizes fornecidas para “Obtenção de dados em tempo real, não segmentados” acima. Orientações adicionais são fornecidas abaixo.
• Para a maioria dos tipos de dados segmentados, os dados podem não estar completos por até 1 hora em determinados momentos. Dados segmentados por INTERESTS podem sofrer atraso de até 12 horas.
• Não se espera que os dados segmentados consolidem 100% em relação aos dados não segmentados, devido à forma como essas informações são derivadas.

​

Coletando dados históricos

• Ao preencher dados retroativos (por exemplo, ao adicionar uma nova conta de anunciante), talvez seja necessário fazer várias solicitações em pequenos intervalos de start_time e end_time.
• Limite suas coletas a janelas de 30 dias.
• Controle o ritmo dessas solicitações e distribua-as ao longo do tempo para não esgotar seus limites de requisições para essas coletas.

​

Exemplo

Você pode encontrar um script de exemplo que demonstra algumas dessas práticas recomendadas (fetch_stats) no nosso repositório ads-platform-tools no GitHub.

​

Métricas por objetivo

As métricas aplicáveis a uma entidade dependem do objetivo da campanha. Use este guia para determinar quais grupos de métricas recuperar para cada tipo de objetivo, assim como como calcular métricas derivadas adicionais.

​

ENGAGEMENTS

Grupos de métricas relevantes: ENGAGEMENT e BILLING. MEDIA também se aplica quando há uso de mídia nos criativos.

Métrica derivada	Cálculo da métrica exposta
Taxa de engajamento	engagements/impressions
CPE	billed_charge_local_micro/engagements
Taxa de visualização de mídia	media_views/impressions

​

WEBSITE_CLICKS e WEBSITE_CONVERSIONS

Grupos de métricas relevantes: ENGAGEMENT, BILLING e WEB_CONVERSION. MEDIA também se aplica se houver uso de mídia nos criativos.

Métrica derivada	Cálculo da métrica exposta
CPM	billed_charge_local_micro/impressions/1000
Taxa de cliques	clicks/impressions
CPLC	billed_charge_local_micro/clicks
Conversões totais	conversion_custom + conversion_site_visits + conversion_sign_ups + conversion_downloads + conversion_purchases
Taxa de conversão	Conversões totais / impressions
CPA	billed_charge_local_micro / Conversões totais

​

APP_INSTALLS e APP_ENGAGEMENTS

Grupos de métricas relevantes: ENGAGEMENT, BILLING, MOBILE_CONVERSION e LIFE_TIME_VALUE_MOBILE_CONVERSION. MEDIA e VIDEO também se aplicam se um app card de mídia ou vídeo for usado nos criativos.

Métrica derivada	Cálculo da métrica exposta
CPM	billed_charge_local_micro/impressions/1000
Taxa de cliques no App	app_clicks/impressions
CPAC	billed_charge_local_micro/app_clicks
CPI	billed_charge_local_micro/mobile_conversion_installs

​

FOLLOWERS

Grupos de métricas relevantes: ENGAGEMENT e BILLING. MEDIA também se aplica quando houver uso de mídia em criativos.

Métrica derivada	Cálculo da métrica exposta
CPM	billed_charge_local_micro/impressions/1000
Taxa de novos seguidores	follows/impressions
CPF	billed_charge_local_micro/follows
Taxa de visualização de mídia	media_views/impressions

​

LEAD_GENERATION

Grupos de métricas relevantes: ENGAGEMENT e BILLING. MEDIA também se aplica se houver uso de mídia nos criativos.

Métrica derivada	Cálculo da métrica exposta
CPM	billed_charge_local_micro/impressions/1000
Leads	card_engagements
Taxa de leads	card_engagements/impressions
Custo por lead	billed_charge_local_micro/card_engagements

​

VIDEO_VIEWS

Grupos de métricas relevantes: ENGAGEMENT, BILLING e VIDEO.

Métrica derivada	Cálculo da métrica exposta
CPM	billed_charge_local_micro/impressions/1000
Taxa de vídeo	video_total_views/impressions
Custo por visualização	billed_charge_local_micro/video_total_views

​

VIDEO_VIEWS_PREROLL

Grupos de métricas relevantes: ENGAGEMENT, BILLING e VIDEO.

Métrica derivada	Cálculo da métrica exposta
CPM	billed_charge_local_micro/impressions/1000
Taxa de vídeo	video_total_views/impressions
Custo por visualização	billed_charge_local_micro/video_total_views

​

Métricas e segmentação

Este documento apresenta uma visão geral das métricas disponíveis em nossa Analytics para cada tipo de entidade, bem como das segmentações disponíveis para cada conjunto de métricas.

	Grupos de métricas
Entity	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	✔		✔

*Algumas métricas da família ENGAGEMENT não estão disponíveis nos níveis de conta (ACCOUNT) e instrumento de financiamento (FUNDING_INSTRUMENT). Consulte a seção ENGAGEMENT para mais detalhes.

​

Metrics disponíveis por grupo de metrics

​

ENGAGEMENT

Métrica	Descrição	Segmentação disponível	Tipo de dado	Disponível para Conta / Instrumento de financiamento
engagements	Número total de engajamentos	✔	Array de ints	✔
impressions	Número total de impressões	✔	Array de ints	✔
retweets	Número total de Retweets	✔	Array de ints	✔
replies	Número total de respostas	✔	Array de ints	✔
likes	Número total de likes	✔	Array de ints	✔
follows	Número total de follows	✔	Array de ints	✔
card_engagements	Número total de engajamentos com Card	✔	Array de ints
clicks	Número total de cliques, incluindo likes e outros engajamentos	✔	Array de ints
app_clicks	Número de tentativas de instalação ou abertura de App	✔	Array de ints
url_clicks	Total de cliques no link ou Website Card em um anúncio, incluindo orgânicos	✔	Array de ints
qualified_impressions	Número total de impressões qualificadas	✔	Array de ints
carousel_swipes	Total de deslizes em imagens ou vídeos de Carrossel	✔	Array de ints

​

BILLING

Métrica	Descrição	Segmentação disponível	Tipo de dado
billed_engagements	Número total de engajamentos faturados	✔	Array de ints
billed_charge_local_micro	Gasto total (em micros)	✔	Array de ints

​

VIDEO

Aviso sobre alterações na definição de metrics de vídeo:

A metric video_total_views dentro do grupo de metrics VIDEO passará a contabilizar visualizações em que pelo menos 50% do player esteve visível por 2 segundos, de acordo com o padrão MRC.

Nossa definição original de visualização de vídeo — 100% em exibição por pelo menos 3 segundos — continuará disponível como uma nova metric video_3s100pct_views no grupo de metrics VIDEO. Para continuar a dar lances e ser cobrado com base na definição original, use o bid_unit VIEW_3S_100PCT recém-disponível.

Metric	Descrição	Segmentação disponível	Tipo de dados
video_total_views	Número total de visualizações de vídeo	✔	Array de ints
video_views_25	Número total de visualizações em que ao menos 25% do vídeo foi visto	✔	Array de ints
video_views_50	Número total de visualizações em que ao menos 50% do vídeo foi visto	✔	Array de ints
video_views_75	Número total de visualizações em que ao menos 75% do vídeo foi visto	✔	Array de ints
video_views_100	Número total de visualizações em que 100% do vídeo foi visto	✔	Array de ints
video_cta_clicks	Total de cliques no call to action	✔	Array de ints
video_content_starts	Número total de inícios de reprodução do vídeo	✔	Array de ints
video_3s100pct_views	Número total de visualizações em que pelo menos 3 segundos foram reproduzidos com 100% em exibição (legado de video_total_views)	✔	Array de ints
video_6s_views	Número total de visualizações em que pelo menos 6 segundos do vídeo foram vistos	✔	Array de ints
video_15s_views	Número total de visualizações em que pelo menos 15 segundos do vídeo, ou 95% da duração total, foram vistos	✔	Array de ints

​

MEDIA

Métrica	Descrição	Segmentação disponível	Tipo de dados
media_views	Número total de visualizações (autoplay e clique) de mídia em Vídeos, Vines, GIFs e Imagens.	✔	Array de ints
media_engagements	Número total de cliques em mídia em Vídeos, Vines, GIFs e Imagens.	✔	Array de ints

​

WEB_CONVERSION

Métrica	Descrição	Segmentação disponível	Tipo de dados
conversion_purchases	Número de conversões do tipo PURCHASE e os respectivos valor de venda e quantidade do pedido	apenas PLATFORMS	Objeto JSON
conversion_sign_ups	Número de conversões do tipo SIGN_UP e os respectivos valor de venda e quantidade do pedido	apenas PLATFORMS	Objeto JSON
conversion_site_visits	Número de conversões do tipo SITE_VISIT e os respectivos valor de venda e quantidade do pedido	apenas PLATFORMS	Objeto JSON
conversion_downloads	Número de conversões do tipo DOWNLOAD e os respectivos valor de venda e quantidade do pedido	apenas PLATFORMS	Objeto JSON
conversion_custom	Número de conversões do tipo CUSTOM e os respectivos valor de venda e quantidade do pedido	apenas PLATFORMS	Objeto JSON

​

MOBILE_CONVERSION

As estatísticas de conversão em dispositivos móveis estão disponíveis somente para contas de anunciante habilitadas para MACT.

Métrica	Descrição	Segmentação Disponível	Tipo de Dados
mobile_conversion_spent_credits	Detalhamento de conversões móveis do tipo SPENT_CREDIT por post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Objeto JSON
mobile_conversion_installs	Detalhamento de conversões móveis do tipo INSTALL por post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Objeto JSON
mobile_conversion_content_views	Detalhamento de conversões móveis do tipo CONTENT_VIEW por post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Objeto JSON
mobile_conversion_add_to_wishlists	Detalhamento de conversões móveis do tipo ADD_TO_WISHLIST por post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Objeto JSON
mobile_conversion_checkouts_initiated	Detalhamento de conversões móveis do tipo CHECKOUT_INITIATED por post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Objeto JSON
mobile_conversion_reservations	Detalhamento de conversões móveis do tipo RESERVATION por post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Objeto JSON
mobile_conversion_tutorials_completed	Detalhamento de conversões móveis do tipo TUTORIAL_COMPLETED por post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Objeto JSON
mobile_conversion_achievements_unlocked	Detalhamento de conversões móveis do tipo ACHIEVEMENT_UNLOCKED por post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Objeto JSON
mobile_conversion_searches	Detalhamento de conversões móveis do tipo SEARCH por post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Objeto JSON
mobile_conversion_add_to_carts	Detalhamento de conversões móveis do tipo ADD_TO_CART por post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Objeto JSON
mobile_conversion_payment_info_additions	Detalhamento de conversões móveis do tipo PAYMENT_INFO_ADDITION por post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Objeto JSON
mobile_conversion_re_engages	Detalhamento de conversões móveis do tipo RE_ENGAGE por post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Objeto JSON
mobile_conversion_shares	Detalhamento de conversões móveis do tipo SHARE por post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Objeto JSON
mobile_conversion_rates	Detalhamento de conversões móveis do tipo RATE por post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Objeto JSON
mobile_conversion_logins	Detalhamento de conversões móveis do tipo LOGIN por post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Objeto JSON
mobile_conversion_updates	Detalhamento de conversões móveis do tipo UPDATE por post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Objeto JSON
mobile_conversion_levels_achieved	Detalhamento de conversões móveis do tipo LEVEL_ACHIEVED por post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Objeto JSON
mobile_conversion_invites	Detalhamento de conversões móveis do tipo INVITE por post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Objeto JSON
mobile_conversion_key_page_views	Detalhamento de conversões móveis do tipo KEY_PAGE_VIEW por post_view e post_engagement	✔	Objeto JSON
mobile_conversion_downloads	Detalhamento de conversões móveis do tipo DOWNLOAD por post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Objeto JSON
mobile_conversion_purchases	Detalhamento de conversões móveis do tipo PURCHASE por post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Objeto JSON
mobile_conversion_sign_ups	Detalhamento de conversões móveis do tipo SIGN_UP por post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Objeto JSON
mobile_conversion_site_visits	Detalhamento de conversões móveis do tipo SITE_VISIT por post_view, post_engagement, assisted, order_quantity e sale_amount	✔	Objeto JSON

​

LIFE_TIME_VALUE_MOBILE_CONVERSION

As estatísticas de conversão móvel por valor de vida útil estão disponíveis apenas para contas de anunciante com MACT habilitado.

Métrica	Descrição	Segmentação disponível	Tipo de dados
mobile_conversion_lifetime_value_purchases	Detalhamento de conversões móveis do tipo PURCHASE		Objeto JSON
mobile_conversion_lifetime_value_sign_ups	Detalhamento de conversões móveis do tipo SIGN_UP		Objeto JSON
mobile_conversion_lifetime_value_updates	Detalhamento de conversões móveis do tipo UPDATE		Objeto JSON
mobile_conversion_lifetime_value_tutorials_completed	Detalhamento de conversões móveis do tipo TUTORIAL_COMPLETED		Objeto JSON
mobile_conversion_lifetime_value_reservations	Detalhamento de conversões móveis do tipo RESERVATION		Objeto JSON
mobile_conversion_lifetime_value_add_to_carts	Detalhamento de conversões móveis do tipo ADD_TO_CART		Objeto JSON
mobile_conversion_lifetime_value_add_to_wishlists	Detalhamento de conversões móveis do tipo ADD_TO_WISHLIST		Objeto JSON
mobile_conversion_lifetime_value_checkouts_initiated	Detalhamento de conversões móveis do tipo CHECKOUT_INITIATED		Objeto JSON
mobile_conversion_lifetime_value_levels_achieved	Detalhamento de conversões móveis do tipo LEVEL_ACHIEVED		Objeto JSON
mobile_conversion_lifetime_value_achievements_unlocked	Detalhamento de conversões móveis do tipo ACHIEVEMENT_UNLOCKED		Objeto JSON
mobile_conversion_lifetime_value_shares	Detalhamento de conversões móveis do tipo SHARE		Objeto JSON
mobile_conversion_lifetime_value_invites	Detalhamento de conversões móveis do tipo INVITE		Objeto JSON
mobile_conversion_lifetime_value_payment_info_additions	Detalhamento de conversões móveis do tipo PAYMENT_INFO_ADDITION		Objeto JSON
mobile_conversion_lifetime_value_spent_credits	Detalhamento de conversões móveis do tipo SPENT_CREDIT		Objeto JSON
mobile_conversion_lifetime_value_rates	Detalhamento de conversões móveis do tipo RATE		Objeto JSON

​

Segmentação

Os relatórios de segmentação permitem recuperar metrics detalhadas pelos valores de um determinado tipo de segmentação. A segmentação está disponível apenas por meio de consultas assíncronas de analytics devido à sua complexidade adicional significativa.

A segmentação não é compatível para as entidades MEDIA_CREATIVE ou ORGANIC_TWEET.

Alguns tipos de segmentação exigem o envio de parâmetros adicionais. Eles estão documentados abaixo.

Ao segmentar por CITIES ou POSTAL_CODES, a API somente retornará locais segmentados (alvos). A segmentação por região e por área metropolitana retornará locais segmentados e não segmentados.

Tipo de segmentação	parâmetro country obrigatório	parâmetro platform obrigatório
AGE
APP_STORE_CATEGORY
AUDIENCES
CITIES	✔
CONVERSATIONS
CONVERSION_TAGS
DEVICES		✔
EVENTS
GENDER
INTERESTS
KEYWORDS
LANGUAGES
LOCATIONS
METROS	✔
PLATFORMS
PLATFORM_VERSIONS		✔
POSTAL_CODES	✔
REGIONS	✔
SLIDES
SIMILAR_TO_FOLLOWERS_OF_USER
TV_SHOWS

​

Métricas derivadas

As métricas de campanha dependem do objetivo da campanha. Use este guia para determinar como calcular métricas derivadas com base nos objetivos em uso.

Qualquer metric sem chaves é retornada pelos endpoints de analytics da X Ads API. Qualquer nome entre {chaves} indica uma métrica derivada para essa categoria.

​

ENGAGEMENTS

Métrica derivada	Cálculo da métrica exposta
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions
billed_charge_local_micro / {Impressions} / 1000
{Total Engagements}	promoted_account_follows + promoted_tweet_search_engagements + promoted_tweet_timeline_engagements + promoted_tweet_profile_engagements ou promoted_account_follows + promoted_tweet_search_clicks + promoted_tweet_search_replies + promoted_tweet_search_retweets + promoted_tweet_search_follows + promoted_tweet_timeline_clicks + promoted_tweet_timeline_replies + promoted_tweet_timeline_retweets + promoted_tweet_timeline_follows + promoted_tweet_profile_clicks + promoted_tweet_profile_replies + promoted_tweet_profile_retweets + promoted_tweet_profile_follows
{Engagement Rate}	{Total Engagements} / {Impressions}
billed_charge_local_micro / {Total Engagements}
{Media Views}	promoted_tweet_timeline_media_views + promoted_tweet_search_media_views + promoted_tweet_profile_media_views
{Media View Rate}	{Media Views} / {Impressions}

​

WEBSITE_CLICKS

Métrica derivada	Cálculo da métrica exposta
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

Métrica derivada	Cálculo da métrica exposta
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

​

SEGUIDORES

Métrica derivada	Cálculo da métrica exposta
promoted_account_impressions
billed_charge_local_micro / {Impressions} / 1000
promoted_account_follows
{Follow Rate}	promoted_account_follow_rate
billed_charge_local_micro / promoted_account_follows
{Media Views}	promoted_tweet_timeline_media_views + promoted_tweet_search_media_views + promoted_tweet_profile_media_views
{Media View Rate}	{Media Views} / {Impressions}

​

LEAD_GENERATION

Métrica derivada	Cálculo da métrica exposta
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
{Taxa de leads}	{Leads} / {Impressions}
{Custo por lead}	billed_charge_local_micro / {Leads}

​

VIDEO_VIEWS

Métrica derivada	Cálculo da métrica exposta
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

Métrica derivada	Cálculo da métrica exposta
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

​

PERSONALIZADO

Para placement_type de PROMOTED_ACCOUNT, consulte o objetivo FOLLOWERS acima. Para todas as outras colocações com este objetivo, consulte ENGAGEMENTS para as metrics derivadas correspondentes.

​

Guias

​

Entidades ativas

​

Introdução

O endpoint Active Entities foi projetado para ser usado em conjunto com nossos endpoints de analytics síncronos e assíncronos, pois fornece informações sobre quais campanhas devem ter analytics solicitados. Ele faz isso retornando detalhes sobre entidades de anúncios e quando suas metrics foram alteradas. Usar este endpoint simplificará bastante seu código e a lógica de obtenção de analytics.

Este guia inclui informações e contexto sobre o endpoint e sua fonte de data. Ele também fornece diretrizes de uso e uma série de exemplos de solicitações, demonstrando como usar Active Entities em conjunto com nossos endpoints de analytics. A seção de resumo fornece uma descrição em alto nível da abordagem recomendada.

​

Dados

Sempre que a métrica de uma entidade de anúncios é alterada, registramos informações sobre essa alteração. Esses eventos de alteração são armazenados em janelas horárias e incluem detalhes sobre a entidade, assim como o horário ao qual a alteração se aplica. Este último é necessário porque os eventos de alteração nem sempre correspondem ao momento em que foram registrados. Ajustes de cobrança são um motivo comum para isso, entre outros.

​

Endpoint

​

Solicitação

As solicitações de Active Entities são vinculadas a contas de anúncios e têm três parâmetros de query obrigatórios: 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"

São compatíveis os seguintes valores para entity: CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE, PROMOTED_ACCOUNT e PROMOTED_TWEET. Isso reflete os tipos de entidade que nossos endpoints de analytics oferecem suporte.

Os valores de start_time e end_time devem ser informados no padrão ISO 8601 e definem quais intervalos horários consultar. Eles devem ser expressos em horas completas.

Este endpoint também oferece suporte a três parâmetros opcionais que podem ser usados para filtrar os resultados: funding_instrument_ids, campaign_ids e line_item_ids. Eles funcionam em todos os níveis da hierarquia de anúncios e com qualquer tipo de entity especificado.

​

Resposta

A resposta de Active Entities para a solicitação acima é apresentada abaixo.

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

A matriz data inclui um objeto para cada entidade que deve ser considerada em uma solicitação de analytics subsequente. Não solicite analytics para IDs fora desse conjunto.

Cada objeto inclui quatro fields: entity_id, activity_start_time, activity_end_time e placements. Os horários de início e término da atividade representam o intervalo ao qual os eventos de alteração da entidade associada se aplicam e, portanto, determinam as datas que devem ser especificadas em solicitações de analytics subsequentes. A matriz placements pode incluir os seguintes valores: ALL_ON_TWITTER, PUBLISHER_NETWORK, SPOTLIGHT e TREND. Ela indica quais placements devem ser solicitados para o ID da entidade em questão.

​

Uso

O endpoint Active Entities deve orientar como as solicitações de analytics são feitas. As diretrizes de uso a seguir foram elaboradas para dar suporte à sincronização de analytics, permitindo que parceiros mantenham seus repositórios de dados em sincronia com o Twitter. Em outras palavras, descrevem como realizar sincronizações periódicas em segundo plano.

Há duas decisões que o desenvolvedor deve tomar.

1. Com que frequência solicitar informações de entidades ativas e, consequentemente, com que frequência coletar analytics.
2. Como usar os horários de início e término da atividade para determinar os valores de start_time e end_time da solicitação de analytics.

Esses tópicos são discutidos com mais detalhes em cada uma das duas subseções abaixo, após o resumo.

​

Resumo

Use o endpoint Active Entities da seguinte maneira para definir como as solicitações de analytics serão feitas. Siga este procedimento depois de decidir com que frequência solicitar informações de active entities e, consequentemente, com que frequência extrair analytics.

1. Faça a solicitação de Active Entities.
2. Separe a resposta por placement. Um grupo para ALL_ON_TWITTER, um para PUBLISHER_NETWORK, um para SPOTLIGHT e um para TREND.
3. Para cada grupo de placement, faça o seguinte.
   1. Extraia os IDs das entidades.
   2. Determine os valores de start_time e end_time para analytics.
      • Encontre o menor activity_start_time. Arredonde esse valor para baixo.
      • Encontre o maior activity_end_time. Arredonde esse valor para cima.
   3. Faça a(s) solicitação(ões) de analytics.
      • Agrupe os IDs das entidades em lotes de 20.
      • Use os valores start_time e end_time do item #3b.
      • Especifique o valor de placement apropriado.
   4. Grave no seu armazenamento de dados.

Consulte active_entities.py como exemplo do uso do SDK do Python.

​

Frequência

A resposta à primeira pergunta determina o intervalo de tempo que deve ser usado em solicitações de Active Entities. Por exemplo, se você solicitar informações de entidades ativas a cada hora, o intervalo de tempo deverá ser de uma hora. Se solicitar informações de entidades ativas uma vez por dia, o intervalo deverá ser de um dia. Em outras palavras, os intervalos de tempo devem ser escolhidos de forma que o start_time da solicitação atual seja igual ao end_time da solicitação anterior.

Observação: Uma janela de tempo deve ser solicitada apenas uma vez. Solicitar a mesma janela de tempo mais de uma vez resultará em solicitações de analytics desnecessárias. (Exceção abaixo.)

Para parceiros que desejam solicitar analytics várias vezes dentro da hora atual, aplica-se o mesmo padrão — a frequência determina o intervalo de tempo. A tabela abaixo mostra exemplos de timestamps de início e fim de Active Entities para esse cenário.

Hora da solicitação	timestamp de start_time	timestamp de 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

Dado o modo como os eventos de alteração são armazenados, todas as quatro solicitações de Active Entities acima consultam o mesmo bucket horário, o que é necessário para este caso de uso. No entanto, após a hora atual, esse bucket horário não deve mais ser consultado.

​

Horários de atividade

Recomendamos a seguinte abordagem para trabalhar com horários de início e término de atividade. Em todos os objetos na resposta de Active Entities, encontre o menor activity_start_time e o maior activity_end_time. Ajuste esses valores arredondando o horário mínimo de início para baixo e o horário máximo de término para cima. Especificamente, defina os timestamps com zero nos campos de hora, minuto e segundo em ambos e adicione um dia ao horário de término, conforme ilustrado na tabela a seguir. Estes são os horários de início e término que devem ser especificados em solicitações de analytics subsequentes.

Horários mínimos e máximos de atividade	Horários derivados
2019-03-04T20:55:20Z 2019-03-05T14:40:59Z	2019-03-04T00:00:00Z 2019-03-06T00:00:00Z

Observação: É importante incluir os timestamps com horas, minutos e segundos definidos como zero. Caso contrário, se apenas a data for informada, assumiremos que você está solicitando analytics começando e terminando à meia-noite no fuso horário da conta de anúncios, o que pode não ser desejável. Por exemplo, se o horário mínimo de início de atividade for 2019-02-28T01:30:07Z e o timestamp for omitido para uma conta de anúncios com deslocamento de -08:00:00, a solicitação de analytics perderá alterações que ocorreram entre 01:30 e 08:00.

Como alternativa, se preferir solicitar analytics apenas para a janela de tempo de atividade retornada, sem expandir para dias completos, você pode. Usando essa abordagem, os horários derivados de início e término seriam 2019-03-04T20:00:00Z e 2019-03-05T15:00:00Z, respectivamente. (Observe que intervalos como esses não são aceitos se você especificar a granularidade DAY na solicitação de analytics.)

​

Exemplo

Esta seção demonstra como usar Active Entities em conjunto com o endpoint de analytics síncrono. (As respostas foram levemente modificadas para melhorar a legibilidade.) Neste exemplo, o endpoint de Active Entities é chamado no início de cada hora, com cada solicitação analisando a hora anterior. A resposta determina como o endpoint de analytics síncrono é usado.

A primeira solicitação de Active Entities é feita às 03:00:00. A resposta indica que as metrics do line item dvcz7 foram alteradas e que esses eventos de alteração se aplicam ao intervalo entre 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"
          ]
        }
      ]
    }

Com base nesses horários de início e término de atividade e seguindo a abordagem descrita acima, os valores de analytics start_time e end_time são definidos como 2019-02-11T00:00:00Z e 2019-02-12T00:00:00Z, respectivamente. Observamos que o terceiro elemento em cada um dos arrays de metrics abaixo é diferente de zero, como esperado com base nas informações sobre as entidades ativas.

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

A próxima solicitação de Active Entities ocorre às 04:00:00 e considera apenas a hora anterior. Como mencionado acima, uma janela de tempo deve ser solicitada apenas uma vez. Com base na resposta, vemos que os eventos de alteração para este line item se aplicam a tanto 02:00:00 quanto 03:00:00. Na solicitação de analytics subsequente, esperamos ver alterações em ambas as horas.

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

Além de vermos metrics diferentes de zero para 03:00:00, observamos que as impressões, o gasto e as visualizações de vídeo MRC foram atualizados em relação aos valores anteriores. As impressões, por exemplo, agora são 2.995 no intervalo das 02:00:00, acima de 2.792. Isso demonstra como os eventos de alteração registrados durante o período das 03:00:00 se aplicam ao período das 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": {}
    }

A solicitação de Active Entities às 05:00:00, novamente considerando apenas a hora anterior, mostra que os eventos de alteração se aplicam apenas à hora de 03:00:00. As mudanças nas metrics de analytics na solicitação subsequente refletem isso.

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

A resposta de analytics mostra que apenas as metrics da hora 03:00:00 foram alteradas; os valores da hora 02:00:00 são os mesmos da solicitação de analytics anterior.

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

Finalmente, às 06:00:00, vemos que não há eventos de alteração adicionais. Observação: Isso não implica, porém, que as metrics desse item de linha não possam mudar no 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": []
    }

​

Guia de Assincronia

​

Referência da API

​

Análises assíncronas

​

Introdução

Os endpoints de analytics assíncronos permitem que parceiros e anunciantes solicitem metrics enviando solicitações de criação que o servidor processa de forma assíncrona. (Chamamos isso de “jobs” de analytics assíncronos.) Com essa abordagem, a conexão do cliente não precisa permanecer aberta até que a solicitação seja atendida.

Esses endpoints, assim como seus equivalentes síncronos, permitem que parceiros e anunciantes solicitem estatísticas detalhadas sobre o desempenho de campanhas. Eles oferecem suporte à solicitação de data para contas, instrumentos de financiamento, campanhas, line items, Tweets promovidos e criativos de mídia. A diferença entre estes e o endpoint síncrono é que os endpoints de analytics assíncronos suportam intervalos de datas mais longos, de até 90 dias, além de segmentação. Detalhes adicionais sobre as diferenças entre ambos podem ser encontrados em nossa página de Visão geral de Analytics.

Ao contrário de nossos endpoints síncronos, o limite de taxa é baseado no número de jobs simultâneos para uma determinada conta. Em outras palavras, baseia-se no número de jobs que podem estar em estado de processamento em um dado momento. Fazemos essa contagem no nível da conta de anúncios.

​

Uso

A recuperação de métricas de campanha usando os endpoints de analytics assíncronos é um processo em várias etapas. Envolve criar um job, verificar se o job concluiu o processamento e, por fim, baixar os dados. O arquivo de dados deve ser descompactado. As quatro etapas específicas estão descritas abaixo.

1. Crie o job usando o endpoint POST stats/jobs/accounts/:account_id.
2. Faça solicitações em intervalos regulares ao endpoint GET stats/jobs/accounts/:account_id para determinar se o job concluiu o processamento.
3. Quando o job tiver concluído o processamento, baixe o arquivo de dados.
4. Descompacte o arquivo de dados.

O objeto de resposta retornado no arquivo de dados tem o mesmo schema JSON da resposta do endpoint de analytics síncrono.

Métricas de campanha segmentadas estão disponíveis apenas por meio dos endpoints de analytics assíncronos. As métricas de campanha podem ser detalhadas por localização, gênero, interesse, palavra‑chave e mais. Para uma lista completa de opções, consulte a página Metrics and Segmentation. Para solicitar métricas segmentadas, use o parâmetro de solicitação segmentation_type ao criar o job.

​

Exemplo

Esta seção demonstra como usar os endpoints de analytics assíncronos.

Comece criando um job usando o endpoint POST stats/jobs/accounts/:account_id. O exemplo abaixo solicita metrics de engajamento — como impressões, likes, cliques etc. — para um item de linha específico ao longo de uma semana. (Observe que o intervalo de tempo solicitado vai até, mas não inclui 20 de março, já que o timestamp está definido para meia-noite.)

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

Esta resposta não retorna as metrics do line item. Ela apenas fornece informações sobre o job que você acabou de criar. O id do job é necessário para verificar o status do job. Isso é exibido nos atributos de resposta id e id_str.

Em seguida, verifique se o job que você criou, usando o id_str da resposta anterior, concluiu o processamento, conforme indicado por "status": "SUCCESS" na resposta. Isso significa que os data estão prontos para download. O campo url contém o link de download.

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

Embora o exemplo acima utilize um único id de job, na prática você deve usar o parâmetro job_ids para verificar o status de vários jobs simultaneamente, especificando até 200 ids de job.

Em seguida, faça o download do arquivo de data usando o valor url fornecido.

    $ 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
    Resolvendo ton.twimg.com (ton.twimg.com)... 72.21.91.70
    Conectando a ton.twimg.com (ton.twimg.com)|72.21.91.70|:443... conectado.
    Requisição HTTP enviada, aguardando resposta... 200 OK
    Tamanho: 381 [application/gzip]
    Salvando em: 'zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz'

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

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

Por fim, extraia o arquivo.

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

O conteúdo do arquivo é exibido abaixo.

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

​

Alcance e frequência média

Executar no Postman

​

GET stats/accounts/:account_id/reach/campaigns

Recupere métricas de alcance e frequência média para as campanhas especificadas.

​

URL do recurso

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

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: 18ce54d4x5t
campaign_ids obrigatório	Limita a resposta às campanhas desejadas ao especificar uma lista de identificadores separados por vírgula. É possível informar até 20 IDs. Observação: É possível informar até 20 IDs de campanha. Tipo: string Exemplo: 8fgzf
end_time obrigatório	Restringe os dados recuperados ao horário de término especificado, expresso em ISO 8601. Observação: Deve ser expresso em horas inteiras (0 minutos e 0 segundos). Tipo: string Exemplo: 2017-05-26T07:00:00Z
start_time obrigatório	Restringe os dados recuperados ao horário de início especificado, expresso em ISO 8601. Observação: Deve ser expresso em horas inteiras (0 minutos e 0 segundos). Tipo: string Exemplo: 2017-05-19T07:00:00Z

​

Exemplo de requisição

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

​

Exemplo de resposta

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

Recupere métricas de alcance e frequência média para os instrumentos de financiamento especificados.

​

URL do recurso

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

​

Parâmetros

Nome	Descrição
account_id obrigatório	Identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Ads API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: 18ce54d4x5t
funding_instrument_ids obrigatório	Limite a resposta apenas aos instrumentos de financiamento desejados especificando uma lista de identificadores separados por vírgula. É possível informar até 20 IDs. Observação: É possível informar até 20 IDs de instrumentos de financiamento. Tipo: string Exemplo: lygyi
end_time obrigatório	Restringe os dados retornados ao horário de término especificado, em ISO 8601. Observação: Deve ser informado em horas cheias (0 minutos e 0 segundos). Tipo: string Exemplo: 2017-05-26T07:00:00Z
start_time obrigatório	Restringe os dados retornados ao horário de início especificado, em ISO 8601. Observação: Deve ser informado em horas cheias (0 minutos e 0 segundos). Tipo: string Exemplo: 2017-05-19T07:00:00Z

​

Exemplo de requisição

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

​

Exemplo de resposta

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

​

Análises síncronas

Executar no Postman

​

GET stats/accounts/:account_id

Recupere análises síncronas da conta atual. É permitido um intervalo máximo de tempo (end_time - start_time) de 7 dias.

​

URL do recurso

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

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta usada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: 18ce54d4x5t
end_time obrigatório	Restringe os dados retornados ao horário final especificado, expresso em ISO 8601. Observação: Deve ser expresso em horas inteiras (0 minutos e 0 segundos). Tipo: string Exemplo: 2017-05-26T07:00:00Z
entity obrigatório	O tipo de entidade para o qual os dados serão recuperados. Tipo: enum Valores possíveis: ACCOUNT, CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, ORGANIC_TWEET, PROMOTED_ACCOUNT, PROMOTED_TWEET, MEDIA_CREATIVE
entity_ids obrigatório	As entidades específicas para as quais os dados serão recuperados. Especifique uma lista de IDs de entidade separados por vírgula. Observação: É possível informar até 20 IDs de entidade. Tipo: string Exemplo: 8u94t
granularity obrigatório	Especifica o nível de granularidade dos dados retornados. Tipo: enum Valores possíveis: DAY, HOUR, TOTAL
metric_groups obrigatório	As métricas específicas que devem ser retornadas. Especifique uma lista de grupos de métricas separados por vírgula. Para mais informações, consulte Metrics and Segmentation. Observação: Os dados de MOBILE_CONVERSION devem ser solicitados separadamente. Tipo: enum Valores possíveis: BILLING, ENGAGEMENT, LIFE_TIME_VALUE_MOBILE_CONVERSION, MEDIA, MOBILE_CONVERSION, VIDEO, WEB_CONVERSION
placement obrigatório	Restringe os dados retornados a uma colocação específica. Observação: Apenas um valor é aceito por solicitação. Para entidades com colocação tanto em X quanto na X Audience Platform, são necessárias solicitações separadas, uma para cada valor de colocação. Tipo: enum Valores possíveis: ALL_ON_TWITTER, PUBLISHER_NETWORK, SPOTLIGHT, TREND
start_time obrigatório	Restringe os dados retornados ao horário inicial especificado, expresso em ISO 8601. Observação: Deve ser expresso em horas inteiras (0 minutos e 0 segundos). Tipo: string Exemplo: 2017-05-19T07:00:00Z

​

Exemplo de requisição

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

​

Exemplo de resposta

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

​

Entidades ativas

Executar no Postman

​

GET stats/accounts/:account_id/active_entities

Recupere detalhes sobre quais métricas de analytics das entidades foram alteradas em um determinado período.

Este endpoint deve ser usado em conjunto com nossos endpoints de analytics. Os resultados deste endpoint indicam para quais entidades de anúncios solicitar analytics. Consulte nosso Guia de Entidades Ativas para diretrizes de uso.

Eventos de alteração estão disponíveis em intervalos horários.

• Os valores de start_time e end_time especificam quais intervalos horários consultar.
• O array data retornado incluirá um objeto para cada entidade que deve ser incluída em solicitações de analytics subsequentes.
• IMPORTANTE: As datas a serem especificadas em solicitações de analytics subsequentes devem ser determinadas com base nos valores de activity_start_time e activity_end_time.
  • Esses valores representam os intervalos de tempo aos quais os eventos de alteração armazenados se aplicam. Isso é retornado por entidade.

Observação: É permitido um intervalo máximo de (end_time - start_time) de 90 dias.

​

URL do recurso

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

​

Parâmetros

Nome	Descrição
account_id obrigatório	O identificador da conta utilizada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Ads API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado. Tipo: string Exemplo: 18ce54d4x5t
end_time obrigatório	Restringe os dados retornados ao horário de término especificado, expresso em ISO 8601. Observação: Deve ser expresso em horas cheias (0 minutos e 0 segundos). Tipo: string Exemplo: 2017-05-26T07:00:00Z
entity obrigatório	O tipo de entidade para a qual obter dados. Tipo: enum Valores possíveis: CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE, PROMOTED_ACCOUNT, PROMOTED_TWEET
start_time obrigatório	Restringe os dados retornados ao horário de início especificado, expresso em ISO 8601. Observação: Deve ser expresso em horas cheias (0 minutos e 0 segundos). Tipo: string Exemplo: 2017-05-19T07:00:00Z
campaign_ids opcional	Restrinja a resposta apenas às entidades associadas às campanhas desejadas, especificando uma lista de identificadores separados por vírgula. Até 200 IDs podem ser fornecidos. Observação: Mutuamente exclusivo com funding_instrument_ids e line_item_ids. Tipo: string Exemplo: 8wku2
funding_instrument_ids opcional	Restrinja a resposta apenas às entidades associadas aos instrumentos de financiamento desejados, especificando uma lista de identificadores separados por vírgula. Até 200 IDs podem ser fornecidos. Observação: Mutuamente exclusivo com campaign_ids e line_item_ids. Tipo: string Exemplo: lygyi
line_item_ids opcional	Restrinja a resposta apenas às entidades associadas aos line items desejados, especificando uma lista de identificadores separados por vírgula. Até 200 IDs podem ser fornecidos. Observação: Mutuamente exclusivo com campaign_ids e line_item_ids. Tipo: string Exemplo: 8v7jo

​

Exemplo de requisição

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

​

Exemplo de resposta

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