Analítica

​

Introducción

Las métricas de analytics ayudan a socios y anunciantes a comprender el rendimiento del contenido que promocionan en X. Esto incluye información como impresiones, clics, visualizaciones de video y gasto. Además, los socios y anunciantes pueden obtener métricas detalladas para diversos segmentos de las audiencias a las que llegan.

La Ads API admite dos formas de obtener métricas detalladas de rendimiento de campaña: de manera sincrónica y asincrónica. Con las llamadas de analytics sincrónicas, las métrricas solicitadas se devuelven en la respuesta. Con los endpoints de analytics asincrónicos, las métricas solicitadas están disponibles en un archivo de resultados descargable después de que el “job” asociado haya terminado de procesarse. El endpoint sincrónico admite periodos de tiempo cortos y es ideal para optimizaciones de campaña en tiempo real. Los endpoints asincrónicos admiten periodos de tiempo mucho más largos y, por lo tanto, están pensados para obtener muchos más datos, ideal para generar informes o realizar cargas históricas.

​

Detalles

​

Sincrónico vs. asincrónico

Las diferencias entre los endpoints de analytics sincrónicos y asincrónicos se resumen en la siguiente tabla. Esta información está destinada a ayudar a los desarrolladores a elegir qué conjunto de endpoints usar.

Función	Sincrónico	Asincrónico
Limitación de tasa	A nivel de usuario: 250 solicitudes/15 minutos	A nivel de cuenta: 100 trabajos concurrentes*
Intervalo de tiempo	7 días	90 días (sin segmentación) 45 días (con segmentación)
Segmentación	No	Sí
Respuesta	Datos de métricas	Estado de procesamiento del trabajo**
Caso de uso recomendado	Optimización en tiempo real Solicitudes de la interfaz de usuario	Sincronización programada periódica Relleno de datos históricos

• Se refiere al número máximo de trabajos que pueden estar en estado de procesamiento en un momento dado.

** Cuando el trabajo termina de procesarse correctamente, se devuelve una URL desde la que se puede descargar el archivo de resultados comprimido (gzip).

Fuera de esto, los endpoints ofrecen la misma funcionalidad.

​

Casos de uso

Hay tres casos de uso principales de analytics.

1. Optimización en tiempo real: usar métricas de rendimiento para actualizar campañas activas
2. Sincronización: sincronizaciones periódicas en segundo plano
3. Incorporación de nuevas cuentas: rellenar datos históricos

El endpoint de analytics síncrono puede usarse para la optimización en tiempo real a fin de actualizar campañas según cambios en las métricas de los últimos 5 a 15 minutos. Cualquiera de los endpoints puede usarse para la sincronización de analytics. Ten en cuenta que el intervalo de tiempo deseado y si se requiere segmentación determinarán qué endpoint usar. La incorporación de nuevas cuentas solo debe realizarse usando los endpoints de analytics asíncronos. (El endpoint de analytics síncrono nunca debe usarse para recuperar grandes volúmenes de datos).

Los endpoints de analytics asíncronos pueden alimentar paneles y otros elementos de la interfaz de usuario si las métricas se sincronizan mediante un proceso backend. Tu implementación debe evitar llamar a los endpoints de analytics asíncronos para atender solicitudes de la interfaz de usuario.

​

Opciones de solicitud

Las solicitudes de analytics se aplican a cuentas de anuncios y, por lo tanto, requieren el id de la cuenta en la ruta del recurso. Las opciones de solicitud, enumeradas a continuación, se especifican como parámetros de consulta. Se requieren los siguientes tipos de valores:

• Entidades: el tipo de entidad, así como hasta 20 id de entidad para las que deseas solicitar analytics
• Rango temporal: las horas de inicio y fin, expresadas en ISO 8601
  • Nota: deben expresarse en horas completas
• Grupos de métricas: uno o más conjuntos de métricas relacionadas (consulta Métricas y segmentación para ver la lista de métricas dentro de cada grupo)
• Granularidad: especifica el nivel de agregación en el que se deben devolver las métricas
• Ubicación: determina si las métricas se obtienen para anuncios que se publicaron dentro o fuera de X
  • Nota: solo se puede especificar un único valor de ubicación por solicitud

Usa los parámetros de solicitud start_time y end_time para especificar un rango temporal. Estos valores deben alinearse con la granularidad indicada de la siguiente manera.

1. TOTAL: especifica cualquier rango temporal (dentro de los límites del endpoint)
2. DAY: tanto la hora de inicio como la de fin deben alinearse con la medianoche en la zona horaria de la cuenta
3. HOUR: especifica cualquier rango temporal (dentro de los límites del endpoint)

La hora de fin es exclusiva. Por ejemplo, una solicitud con start_time=2019-01-01T00:00:00Z y end_time=2019-01-02T00:00:00Z devolverá métricas de analytics equivalentes a un solo día (no dos), ya que este rango temporal abarca únicamente un período de 24 horas.

Segmentación

Disponible solo a través de nuestros endpoints de analytics asíncronos, la segmentación permite a socios y anunciantes obtener métricas desglosadas por valores de segmentación específicos. Para solicitar métricas segmentadas, usa el parámetro de solicitud segmentation_type. Para más detalles sobre las opciones de segmentación, consulta Métricas y segmentación.

​

Preguntas frecuentes

¿Por qué las cifras de la Ads API no coinciden con lo que se muestra en la interfaz de X Ads?

• Asegúrate de solicitar datos para todas las ubicaciones: ALL_ON_TWITTER y PUBLISHER_NETWORK, SPOTLIGHT y TREND.
• Recuerda que las horas de finalización en la Ads API son exclusivas; en la interfaz de Ads son inclusivas.

¿Por qué cambian las cifras según cuándo solicito los datos?

• En cuanto las métricas de informes estén disponibles, podrás recuperarlas. Están disponibles casi en tiempo real. Sin embargo, estos resultados iniciales son estimaciones y, por lo tanto, es de esperar que cambien. Las métricas se finalizan después de 24 horas, con la excepción de los datos de gasto.
• Las métricas de gasto generalmente se finalizan dentro de los 3 días posteriores al evento. No obstante, procesamos datos de facturación hasta 14 días desde la fecha del evento (por ejemplo, para el filtrado de spam).

¿Cómo puedo determinar qué id de entidad solicitar para un período de tiempo específico?

• Usa el Active Entities endpoint

¿Por qué todos los valores en la respuesta de analytics son null?

• Es probable que la campaña no haya tenido impresiones durante el período de tiempo solicitado.
• Usa el Active Entities endpoint para determinar para qué entidades obtener analytics y para qué período de tiempo.

¿Por qué la API muestra valores null mientras que la interfaz muestra 0?

• La interfaz opta por mostrar estos valores como 0, pero los valores son equivalentes.

¿Cómo puedo solicitar métricas asociadas con una ubicación granular, como la cronología de X?

• Admitimos los siguientes valores de ubicación en analytics: ALL_ON_TWITTER y PUBLISHER_NETWORK, SPOTLIGHT y TREND (es decir, la X Audience Platform).

¿Es posible recuperar métricas de entidades eliminadas o pausadas?

• Sí. El estado de la entidad no afecta la disponibilidad de las métricas de analytics.

¿Por qué los valores segmentados no coinciden con los no segmentados?

• No se espera que los datos segmentados se acumulen al 100% con los datos no segmentados, debido a cómo se derivan.

¿Es posible solicitar datos segmentados por múltiples dimensiones?

• No admitimos la multisegmentación.

​

Mejores prácticas

Algunas prácticas recomendadas al recopilar datos de analytics desde la Ads API.

​

Limitación de tasa y reintentos

• En las consultas sujetas a limitación de tasa (las que devuelven un código de estado HTTP 429), debes revisar el encabezado x-rate-limit-reset y volver a intentar únicamente en o después de la hora indicada.
• En las consultas que devuelven un código de estado HTTP 503 Service Unavailable, debes revisar el encabezado retry-after y volver a intentar solo después de la hora indicada.
• Las aplicaciones que no respeten los tiempos indicados para los reintentos podrían ver su acceso a la Ads API revocado o limitado sin previo aviso.

​

Métricas de Analytics en pocas palabras

• Todas las métricas de analytics quedan bloqueadas y no cambian después de 24 horas, con la excepción de billed_charge_local_micro.
• La métrica billed_charge_local_micro es una estimación durante hasta 3 días después de que se devuelve el data.
• Después de 24 horas, esta métrica puede disminuir debido a créditos por gasto excesivo (anuncios publicados después del end_time indicado) y por eventos facturables que se determinen como no válidos. Esta métrica cambia mínimamente después de 24 horas.
• Consulta Analytics para obtener más información.

​

Obtención de datos no segmentados en tiempo real

• Proporciona siempre tanto start_time como end_time.
• No extraigas datos de entidades con más de 7 días de antigüedad.
• Solicita datos (idealmente) con granularidad HOUR, ya que siempre puedes agregar y consolidar métricas para obtener granularidad DAY y TOTAL.
• Solicita datos (idealmente) a nivel de line_items y promoted_tweets, ya que siempre puedes agregar y consolidar estas métricas para obtener totales en toda la jerarquía de entidades de anuncios (es decir, a nivel de campaña, instrumento de financiación o cuenta).
• Guarda y almacena localmente los valores de las métricas de analytics.
• No consultes repetidamente datos con más de 30 días. Estos datos no cambiarán y deben almacenarse localmente.
• Todos los datos no segmentados son en tiempo real y deberían estar disponibles en cuestión de segundos tras producirse un evento.
• Agrupa las métricas de conversión y las de no conversión en solicitudes separadas.

​

Obtención de datos segmentados

• Consulta las pautas anteriores para “Obtención de datos en tiempo real no segmentados”. A continuación se ofrece orientación adicional.
• En la mayoría de los tipos de datos segmentados, es posible que los datos no estén completos durante hasta 1 hora en ciertos momentos. Los datos segmentados por INTERESTS pueden retrasarse hasta 12 horas.
• No se espera que los datos segmentados sumen el 100% de los no segmentados, debido a la forma en que se derivan.

​

Obtención de datos históricos

• Al completar datos retrospectivos (por ejemplo, al agregar una nueva cuenta de anunciante), puede que debas hacer varias solicitudes en intervalos más pequeños de start_time y end_time.
• Limita tus consultas a ventanas de 30 días.
• Regula estas solicitudes y distribúyelas en el tiempo para no agotar los límites de velocidad de estas consultas.

​

Ejemplo

Puedes encontrar un script de ejemplo que muestra algunas de estas prácticas recomendadas (fetch_stats) en nuestro repositorio de ads-platform-tools en GitHub.

​

Métricas por objetivo

Las métricas aplicables a una entidad dependen del objetivo de la campaña. Usa esta guía para determinar qué grupos de métricas obtener para cada tipo de objetivo, así como la forma de calcular métricas derivadas adicionales.

​

ENGAGEMENTS

Grupos de métricas relevantes: ENGAGEMENT y BILLING. MEDIA también aplica si se utiliza contenido multimedia en los creativos.

Métrica derivada	Cálculo de la métrica expuesta
Tasa de engagement	engagements/impressions
CPE	billed_charge_local_micro/engagements
Tasa de visualización de medios	media_views/impressions

​

WEBSITE_CLICKS y WEBSITE_CONVERSIONS

Grupos de métricas relevantes: ENGAGEMENT, BILLING y WEB_CONVERSION. MEDIA también aplica si se utiliza contenido multimedia en los creativos.

Métrica derivada	Cálculo de la métrica expuesta
CPM	billed_charge_local_micro/impressions/1000
Tasa de clics	clicks/impressions
CPLC	billed_charge_local_micro/clicks
Conversiones totales	conversion_custom + conversion_site_visits + conversion_sign_ups + conversion_downloads + conversion_purchases
Tasa de conversión	Conversiones totales / impressions
CPA	billed_charge_local_micro / Conversiones totales

​

APP_INSTALLS y APP_ENGAGEMENTS

Grupos de métricas relevantes:ENGAGEMENT, BILLING, MOBILE_CONVERSION y LIFE_TIME_VALUE_MOBILE_CONVERSION. MEDIA y VIDEO también aplican si se utiliza una app card de medios o video en los creativos.

Métrica derivada	Cálculo de la métrica expuesta
CPM	billed_charge_local_micro/impressions/1000
Tasa de clics de la 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 y BILLING. MEDIA también aplica si se utiliza contenido multimedia en los creativos.

Métrica derivada	Cálculo de la métrica expuesta
CPM	billed_charge_local_micro/impressions/1000
Tasa de seguimiento	follows/impressions
CPF	billed_charge_local_micro/follows
Tasa de visualización de medios	media_views/impressions

​

LEAD_GENERATION

Grupos de métricas relevantes: ENGAGEMENT y BILLING. MEDIA también aplica si se utiliza contenido multimedia en los creativos.

Métrica derivada	Cálculo de la métrica expuesta
CPM	billed_charge_local_micro/impressions/1000
Leads	card_engagements
Tasa de leads	card_engagements/impressions
Costo por lead	billed_charge_local_micro/card_engagements

​

VIDEO_VIEWS

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

Métrica derivada	Cálculo de la métrica expuesta
CPM	billed_charge_local_micro/impressions/1000
Tasa de video	video_total_views/impressions
Costo por visualización	billed_charge_local_micro/video_total_views

​

VIDEO_VIEWS_PREROLL

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

Métrica derivada	Cálculo de la métrica expuesta
CPM	billed_charge_local_micro/impressions/1000
Tasa de vídeo	video_total_views/impressions
Costo por visualización	billed_charge_local_micro/video_total_views

​

Métricas y segmentación

Este documento ofrece una descripción general de las métricas disponibles en nuestras Analytics para cada tipo de entidad, así como de la segmentación disponible para cada métrica.

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

*Algunas métricas de la familia de ENGAGEMENT no están disponibles a nivel de cuenta e instrumento de financiación. Consulta la sección ENGAGEMENT para más detalles.

​

Métricas disponibles por grupo de métricas

​

ENGAGEMENT

Métrica	Descripción	Segmentación disponible	Tipo de dato	Disponible para cuenta / instrumento de financiación
engagements	Número total de interacciones	✔	Array de enteros	✔
impressions	Número total de impresiones	✔	Array de enteros	✔
retweets	Número total de retweets	✔	Array de enteros	✔
replies	Número total de respuestas	✔	Array de enteros	✔
likes	Número total de Me gusta	✔	Array de enteros	✔
follows	Número total de follows	✔	Array de enteros	✔
card_engagements	Número total de interacciones con la Card	✔	Array de enteros
clicks	Número total de clics, incluidos los Me gusta y otras interacciones	✔	Array de enteros
app_clicks	Número de intentos de instalación o apertura de la App	✔	Array de enteros
url_clicks	Número total de clics en el enlace o en la Website Card de un anuncio, incluidos los obtenidos	✔	Array de enteros
qualified_impressions	Número total de impresiones cualificadas	✔	Array de enteros
carousel_swipes	Número total de deslizamientos en imágenes o videos de Carrusel	✔	Array de enteros

​

BILLING

Métrica	Descripción	Segmentación disponible	Tipo de datos
billed_engagements	Número total de interacciones facturadas	✔	Array de enteros
billed_charge_local_micro	Gasto total en micros	✔	Array de enteros

​

VIDEO

Aviso sobre cambios en la definición de métricas de video:

La métrica video_total_views dentro del grupo de métricas VIDEO contabilizará cualquier visualización con al menos un 50% en pantalla durante 2 segundos, según el estándar del MRC.

Nuestra definición original de visualización de video (100% en pantalla durante al menos 3 segundos) seguirá disponible como la nueva métrica video_3s100pct_views en el grupo de métricas VIDEO. Para seguir ofertando y que la facturación se base en la definición original de visualización, usa la nueva VIEW_3S_100PCT como bid_unit.

Métrica	Descripción	Segmentación disponible	Tipo de dato
video_total_views	Número total de visualizaciones de video	✔	Array de ints
video_views_25	Número total de visualizaciones en las que se vio al menos el 25% del video	✔	Array de ints
video_views_50	Número total de visualizaciones en las que se vio al menos el 50% del video	✔	Array de ints
video_views_75	Número total de visualizaciones en las que se vio al menos el 75% del video	✔	Array de ints
video_views_100	Número total de visualizaciones en las que se vio el 100% del video	✔	Array de ints
video_cta_clicks	Clics totales en el llamado a la acción	✔	Array de ints
video_content_starts	Número total de inicios de reproducción de video	✔	Array de ints
video_3s100pct_views	Número total de visualizaciones en las que se reprodujeron al menos 3 segundos con el 100% en pantalla (definición anterior de video_total_views)	✔	Array de ints
video_6s_views	Número total de visualizaciones en las que se vieron al menos 6 segundos del video	✔	Array de ints
video_15s_views	Número total de visualizaciones en las que se vieron al menos 15 segundos del video o el 95% de la duración total	✔	Array de ints

​

MEDIA

Métrica	Descripción	Segmentación disponible	Tipo de datos
media_views	Número total de visualizaciones (reproducción automática y al hacer clic) de medios en videos, Vines, GIF y imágenes.	✔	Arreglo de enteros
media_engagements	Número total de clics en medios en videos, Vines, GIF y imágenes.	✔	Arreglo de enteros

​

WEB_CONVERSION

Métrica	Descripción	Segmentación disponible	Tipo de dato
conversion_purchases	Número de conversiones de tipo PURCHASE y el importe de venta y la cantidad de pedidos correspondientes	Solo PLATFORMS	Objeto JSON
conversion_sign_ups	Número de conversiones de tipo SIGN_UP y el importe de venta y la cantidad de pedidos correspondientes	Solo PLATFORMS	Objeto JSON
conversion_site_visits	Número de conversiones de tipo SITE_VISIT y el importe de venta y la cantidad de pedidos correspondientes	Solo PLATFORMS	Objeto JSON
conversion_downloads	Número de conversiones de tipo DOWNLOAD y el importe de venta y la cantidad de pedidos correspondientes	Solo PLATFORMS	Objeto JSON
conversion_custom	Número de conversiones de tipo CUSTOM y el importe de venta y la cantidad de pedidos correspondientes	Solo PLATFORMS	Objeto JSON

​

MOBILE_CONVERSION

Las estadísticas de conversiones móviles están disponibles únicamente para las cuentas de anunciantes habilitadas para MACT.

Métrica	Descripción	Segmentación disponible	Tipo de dato
mobile_conversion_spent_credits	Desglose de conversiones móviles del tipo SPENT_CRÉDITO por Post_vista, Post_interacción, asistida, orden_cantidad y ventas_importe	✔	Objeto JSON
mobile_conversion_installs	Desglose de conversiones móviles de tipo INSTALL por Post_vista, Post_interacción, asistida, pedido_cantidad y ventas_importe	✔	Objeto JSON
mobile_conversion_content_views	Desglose de conversiones móviles del tipo CONTENT_VISTA por Post_vista, Post_interacción, asistido, orden_cantidad y venta_importe	✔	Objeto de JSON
mobile_conversion_add_to_wishlists	Desglose de conversiones móviles del tipo ADD_A_LISTA DE DESEOS por Post_vista, Post_interacción, asistido, orden_cantidad y venta_importe	✔	Objeto JSON
mobile_conversion_checkouts_initiated	Desglose de conversiones móviles del tipo CHECKOUT_INITIATED by Post_vista, Post_interacción, asistido, orden_cantidad y venta_importe	✔	Objeto JSON
mobile_conversion_reservations	Desglose de conversiones móviles de tipo RESERVATION por publicación_vista, Post_interacción, asistida, orden_cantidad y venta_importe	✔	Objeto JSON
mobile_conversion_tutorials_completed	Desglose de conversiones móviles del tipo TUTORIAL_COMPLETED por Post_vista, Post_interacción, asistido, orden_cantidad y venta_importe	✔	Objeto JSON
mobile_conversion_achievements_unlocked	Desglose de conversiones móviles de tipo ACHIEVEMENT_DESBLOQUEADO por Post_vista, Post_interacción, asistida, orden_cantidad y ventas_importe	✔	Objeto JSON
mobile_conversion_searches	Desglose de conversiones móviles de tipo SEARCH por Post_vista, publicación_interacción, asistido, pedido_cantidad y venta_importe	✔	Objeto JSON
mobile_conversion_add_to_carts	Desglose de conversiones móviles del tipo ADD_PARA_CARRITO por Post_vista, Post_participación, asistido, orden_cantidad y ventas_importe	✔	Objeto JSON
mobile_conversion_payment_info_additions	Desglose de conversiones móviles de tipo PAYMENT_INFORMACIÓN_ADICIÓN por Post_vista, Post_interacción, asistido, pedido_cantidad y venta_importe	✔	Objeto JSON
mobile_conversion_re_engages	Desglose de conversiones móviles del tipo RE_INTERACCIÓN por Post_vista, Post_interacción, asistido, pedido_cantidad y venta_importe	✔	Objeto JSON
mobile_conversion_shares	Desglose de conversiones móviles de tipo SHARE por Post_vista, Post_interacción, asistida, orden_cantidad y venta_importe	✔	Objeto JSON
mobile_conversion_rates	Desglose de conversiones móviles de tipo RATE por Post_vista, Post_interacción, asistida, orden_cantidad y venta_importe	✔	Objeto JSON
mobile_conversion_logins	Desglose de conversiones móviles de tipo LOGIN por Post_vista, Post_interacción, asistida, orden_cantidad y venta_importe	✔	Objeto JSON
mobile_conversion_updates	Desglose de conversiones móviles de tipo UPDATE por Post_vista, Post_interacción, asistido, orden_cantidad y venta_importe	✔	Objeto JSON
mobile_conversion_levels_achieved	Desglose de conversiones móviles del tipo LEVEL_LOGRADO por Post_vista, Post_interacción, asistida, pedido_cantidad y venta_importe	✔	Objeto JSON
mobile_conversion_invites	Desglose de conversiones móviles de tipo INVITE por Post_vista, Post_interacción, asistida, orden_cantidad y venta_importe	✔	Objeto JSON
mobile_conversion_key_page_views	Desglose de conversiones móviles de tipo KEY_PÁGINA_VER por Post_ver y publicar_interacción	✔	Objeto JSON
móvil_conversión_Descargas	Desglose de conversiones móviles de tipo DOWNLOAD por Post_vista, Post_interacción, asistido, orden_cantidad y venta_importe	✔	Objeto JSON
móvil_conversión_compras	Desglose de conversiones móviles de tipo PURCHASE por Post_vista, Post_interacción, asistido, orden_cantidad y venta_importe	✔	Objeto JSON
móvil_conversión_firmar_oops	Desglose de conversiones móviles del tipo FIRMA_SUBIDAS por Post_vista, Post_interacción, asistida, orden_cantidad y ventas_importe	✔	Objeto JSON
dispositivo móvil_conversión_sitio_visitas	Desglose de conversiones móviles de tipo SITIO_VISITAS por Post_vista, Post_interacción, asistida, orden_cantidad y venta_importe	✔	Objeto JSON

​

LIFE_TIME_VALUE_MOBILE_CONVERSION

Las estadísticas de conversiones móviles de valor de vida útil están disponibles solo para cuentas de anunciantes con MACT habilitado.

Métrica	Descripción	Segmentación disponible	Tipo de dato
mobile_conversion_lifetime_value_purchases	Desglose de conversiones móviles de tipo PURCHASE		Objeto JSON
mobile_conversion_lifetime_value_sign_ups	Desglose de conversiones móviles de tipo SIGN_UP		Objeto JSON
mobile_conversion_lifetime_value_updates	Desglose de conversiones móviles de tipo UPDATE		Objeto JSON
mobile_conversion_lifetime_value_tutorials_completed	Desglose de conversiones móviles de tipo TUTORIAL_COMPLETED		Objeto JSON
mobile_conversion_lifetime_value_reservations	Desglose de conversiones móviles de tipo RESERVATION		Objeto JSON
mobile_conversion_lifetime_value_add_to_carts	Desglose de conversiones móviles de tipo ADD_TO_CART		Objeto JSON
mobile_conversion_lifetime_value_add_to_wishlists	Desglose de conversiones móviles de tipo ADD_TO_WISHLIST		Objeto JSON
mobile_conversion_lifetime_value_checkouts_initiated	Desglose de conversiones móviles de tipo CHECKOUT_INITIATED		Objeto JSON
mobile_conversion_lifetime_value_levels_achieved	Desglose de conversiones móviles de tipo LEVEL_ACHIEVED		Objeto JSON
mobile_conversion_lifetime_value_achievements_unlocked	Desglose de conversiones móviles de tipo ACHIEVEMENT_UNLOCKED		Objeto JSON
mobile_conversion_lifetime_value_shares	Desglose de conversiones móviles de tipo SHARE		Objeto JSON
mobile_conversion_lifetime_value_invites	Desglose de conversiones móviles de tipo INVITE		Objeto JSON
mobile_conversion_lifetime_value_payment_info_additions	Desglose de conversiones móviles de tipo PAYMENT_INFO_ADDITION		Objeto JSON
mobile_conversion_lifetime_value_spent_credits	Desglose de conversiones móviles de tipo SPENT_CREDIT		Objeto JSON
mobile_conversion_lifetime_value_rates	Desglose de conversiones móviles de tipo RATE		Objeto JSON

​

Segmentación

Los informes de segmentación permiten obtener métricas desglosadas por los valores de un tipo de segmentación determinado. La segmentación solo está disponible a través de consultas de Analytics asincrónicas debido a su mayor complejidad.

La segmentación no es compatible para las entidades MEDIA_CREATIVE u ORGANIC_TWEET.

Algunos tipos de segmentación requieren que se envíen parámetros adicionales. Estos se documentan a continuación.

Al segmentar por CITIES o POSTAL_CODES, la API solo devolverá ubicaciones dirigidas. La segmentación por región y área metropolitana devolverá ubicaciones tanto dirigidas como no dirigidas.

Tipo de segmentación	se requiere el parámetro country	se requiere el parámetro platform
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

Las métricas de campaña dependen de su objetivo de campaña. Usa esta guía para determinar cómo calcular métricas derivadas para su uso según los objetivos vigentes.

Cualquier metric sin llaves es una devuelta por los endpoints de Analytics de la Ads API. Cualquier nombre entre {llaves} indica una métrica derivada para esa categoría.

​

INTERACCIONES

Métrica derivada	Cálculo de la métrica expuesta
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 o 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 de Métrica Expuesta
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 y APP_ENGAGEMENTS

Métrica derivada	Cálculo de la métrica expuesta
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 de la métrica expuesta
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 de métrica expuesta
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

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

​

IMPRESIONES_CUALIFICADAS

Métrica derivada	Cálculo de la métrica expuesta
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, consulta el objetivo FOLLOWERS más arriba. Para las demás ubicaciones con este objetivo, consulta ENGAGEMENTS para ver las métricas derivadas correspondientes.

​

Guías

​

Entidades activas

​

Introducción

El endpoint Active Entities está diseñado para usarse junto con nuestros endpoints de Analytics síncronos y asíncronos, ya que proporciona información sobre qué campañas requieren Analytics. Lo hace devolviendo detalles sobre las entidades de anuncios y cuándo cambiaron sus métricas. Usar este endpoint simplificará considerablemente tu código y la lógica para obtener Analytics.

Esta guía incluye información y contexto sobre el endpoint y su fuente de datos. También proporciona directrices de uso y una serie de ejemplos de solicitudes que muestran cómo usar Active Entities junto con nuestros endpoints de Analytics. La sección de resumen ofrece una descripción general del enfoque recomendado.

​

Data

Cada vez que cambia una métrica de una entidad de anuncios, registramos información sobre ese cambio. Estos eventos de cambio se almacenan en intervalos de una hora e incluyen detalles sobre la entidad, así como el momento al que aplica el cambio. Esto último es necesario porque los eventos de cambio no siempre coinciden con cuándo se registraron. Los ajustes de facturación son una razón común para ello, aunque hay otras también.

​

Endpoint

​

Solicitud

Las solicitudes de Active Entities se limitan a cuentas de anuncios y tienen tres parámetros de consulta obligatorios: entity, start_time y 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"

Se admiten los siguientes valores para entity: CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE, PROMOTED_ACCOUNT y PROMOTED_TWEET. Esto refleja los tipos de entidad que admiten nuestros endpoints de analytics.

Los valores de start_time y end_time deben expresarse en formato ISO 8601 y especificar qué intervalos horarios consultar. Deben expresarse en horas completas.

Este endpoint también admite tres parámetros opcionales que se pueden usar para filtrar los resultados: funding_instrument_ids, campaign_ids y line_item_ids. Funcionan en todos los niveles de la jerarquía de anuncios y con cualquier tipo de entity especificado.

​

Respuesta

A continuación se muestra la respuesta de Active Entities para la solicitud anterior.

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

La matriz data incluye un objeto por cada entidad que debe incluirse en una solicitud de analytics posterior. No debes solicitar analytics para IDs fuera de este conjunto.

Cada objeto incluye cuatro campos: entity_id, activity_start_time, activity_end_time y placements. Las horas de inicio y fin de la actividad representan el intervalo de tiempo al que se aplican los eventos de cambio de la entidad asociada y, por lo tanto, determinan las fechas que deben especificarse en solicitudes de analytics posteriores. La matriz placements puede incluir los siguientes valores: ALL_ON_TWITTER, PUBLISHER_NETWORK, SPOTLIGHT y TREND. Indica qué ubicaciones deben solicitarse para el ID de la entidad indicada.

​

Uso

El endpoint de Active Entities debe definir cómo se realizan las solicitudes de analytics. Las siguientes pautas de uso están pensadas para facilitar la sincronización de analytics, permitiendo que los socios mantengan sus almacenes de datos sincronizados con Twitter. En otras palabras, describen cómo llevar a cabo sincronizaciones periódicas en segundo plano.

Hay dos decisiones que debe tomar un desarrollador.

1. Con qué frecuencia solicitar información de entidades activas y, por lo tanto, con qué frecuencia obtener analytics.
2. Cómo usar las horas de inicio y fin de la actividad para determinar los valores start_time y end_time de la solicitud de analytics.

Estas se tratan con mayor detalle en cada una de las dos subsecciones a continuación, después del resumen.

​

Resumen

Utiliza el endpoint Active Entities de la siguiente manera para definir cómo se realizan las solicitudes de analytics. Sigue estos pasos después de decidir con qué frecuencia solicitar la información de entidades activas y, por lo tanto, con qué frecuencia extraer analytics.

1. Realiza la solicitud de Active Entities.
2. Divide la respuesta por placement. Un grupo para ALL_ON_TWITTER, otro para PUBLISHER_NETWORK, otro para SPOTLIGHT y otro para TREND.
3. Para cada grupo de placement, haz lo siguiente.
   1. Extrae los id de entidad.
   2. Determina los valores de start_time y end_time de analytics.
      • Encuentra el activity_start_time mínimo. Redondea este valor hacia abajo.
      • Encuentra el activity_end_time máximo. Redondea este valor hacia arriba.
   3. Realiza las solicitudes de analytics.
      • Agrupa los id de entidad en lotes de 20.
      • Usa los valores de start_time y end_time del punto 3b.
      • Especifica el valor de placement correspondiente.
   4. Escribe en tu almacén de datos.

Consulta active_entities.py como ejemplo que utiliza el SDK de Python.

​

Frecuencia

La respuesta a la primera pregunta determina el intervalo de tiempo que debe usarse en las solicitudes de Active Entities. Por ejemplo, si se solicitan datos de entidades activas cada hora, el intervalo debe ser de una hora. Si se solicitan una vez al día, el intervalo debe ser de un día. En otras palabras, los intervalos deben seleccionarse de modo que el start_time de la solicitud actual sea igual al end_time de la solicitud anterior.

Nota: Una ventana de tiempo debe solicitarse solo una vez. Solicitar la misma ventana más de una vez generará solicitudes de analíticas innecesarias. (Excepción a continuación).

Para los partners que deseen solicitar analíticas varias veces por hora para la hora actual, se aplica el mismo patrón: la frecuencia determina el intervalo. La tabla a continuación muestra ejemplos de marcas de tiempo de inicio y fin de Active Entities para este escenario.

Hora de solicitud	Marca de tiempo de start_time	Marca de tiempo 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

Dada la forma en que se almacenan los eventos de cambio, las cuatro solicitudes de Active Entities anteriores consultan el mismo bucket horario, lo cual es necesario para este caso de uso. Sin embargo, una vez transcurrida la hora actual, ya no se debe consultar ese bucket horario.

​

Tiempos de actividad

Recomendamos el siguiente enfoque para trabajar con las horas de inicio y fin de la actividad. En todos los objetos de la respuesta de Active Entities, identifica el mínimo activity_start_time y el máximo activity_end_time. Modifica estos valores redondeando hacia abajo la hora mínima de inicio de actividad y redondeando hacia arriba la hora máxima de fin de actividad. En concreto, establece en cero las marcas de tiempo en ambos y añade un día a la hora de finalización, como se muestra en la siguiente tabla. Estos serán los tiempos de inicio y fin que deberán especificarse en solicitudes de analytics posteriores.

Tiempos mínimos y máximos de actividad	Tiempos derivados
2019-03-04T20:55:20Z 2019-03-05T14:40:59Z	2019-03-04T00:00:00Z 2019-03-06T00:00:00Z

Nota: Es importante incluir las marcas de tiempo con horas, minutos y segundos en cero. De lo contrario, si solo se pasa la fecha, asumiremos que solicitas analytics que comienzan y terminan a medianoche en la zona horaria de la cuenta de anuncios, lo cual puede no ser deseable. Por ejemplo, si la hora mínima de inicio de actividad es 2019-02-28T01:30:07Z y se omite la marca de tiempo para una cuenta de anuncios con un desfase de -08:00:00, la solicitud de analytics omitirá cambios que ocurrieron entre las 01:30 y las 08:00.

Como alternativa, si prefieres solicitar analytics únicamente para la ventana de tiempo de actividad devuelta, sin expandir a días completos, puedes hacerlo. Con este enfoque, los tiempos de inicio y fin derivados serían 2019-03-04T20:00:00Z y 2019-03-05T15:00:00Z, respectivamente. (Ten en cuenta que rangos como estos no se aceptan si especificas la granularidad DAY en la solicitud de analytics.)

​

Ejemplo

Esta sección muestra cómo usar Active Entities junto con el endpoint de analytics síncrono. (Las respuestas se han modificado ligeramente para mejorar la legibilidad). En este ejemplo, se llama al endpoint de Active Entities al inicio de cada hora y cada solicitud analiza la hora anterior. La respuesta determina cómo se usa el endpoint de analytics síncrono.

La primera solicitud de Active Entities se realiza a las 03:00:00. La respuesta indica que las métricas del line item dvcz7 cambiaron y que esos eventos de cambio se aplican a la ventana comprendida entre las 02:02:55 y las 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"
          ]
        }
      ]
    }

Basándonos en estas horas de inicio y fin de la actividad y usando el enfoque descrito arriba, los valores de start_time y end_time de analytics se establecen en 2019-02-11T00:00:00Z y 2019-02-12T00:00:00Z, respectivamente. Vemos que el tercer elemento de cada uno de los arreglos de métricas a continuación es distinto de cero, como esperábamos según la información sobre entidades activas.

`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 siguiente solicitud de Active Entities sucede a las 04:00:00 y solo considera la hora anterior. Como se mencionó anteriormente, una ventana de tiempo solo debe solicitarse una vez. Según la respuesta, vemos que los eventos de cambio para este line item se aplican a ambas, 02:00:00 y 03:00:00. En la solicitud de analytics posterior, esperamos ver cambios para ambas 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"
          ]
        }
      ]
    }

Además de ver métricas distintas de cero para las 03:00:00, observamos que las impresiones, el gasto y las visualizaciones de video MRC se han actualizado con respecto a sus valores anteriores. Las impresiones, por ejemplo, ahora son 2,995 para la hora de las 02:00:00, frente a 2,792. Esto demuestra cómo los eventos de cambio registrados durante la hora de las 03:00:00 se aplican a la hora de las 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 solicitud de Active Entities a las 05:00:00, nuevamente considerando solo la hora anterior, muestra que los eventos de cambio se aplican únicamente a la hora de las 03:00:00. Los cambios en las métricas de analytics en la solicitud posterior lo reflejan.

`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 respuesta de analytics indica que solo han cambiado las métricas de la hora 03:00:00; los valores de la hora 02:00:00 son los mismos que en la solicitud 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, a las 06:00:00 vemos que no hay eventos de cambio adicionales. Nota: Esto no implica, sin embargo, que las métricas de este ítem de línea no puedan cambiar en el 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": []
    }

​

Guía asíncrona

​

Referencia de API

​

Analíticas asincrónicas

​

Introducción

Los endpoints de analytics asíncronos permiten a socios y anunciantes solicitar métricas enviando solicitudes de creación que el servidor procesa de forma asíncrona. (Nos referimos a estas como “jobs” de analytics asíncronos). Con este enfoque, la conexión del cliente no necesita permanecer abierta hasta que la solicitud se haya completado.

Estos endpoints, al igual que su equivalente síncrono, permiten a socios y anunciantes solicitar estadísticas detalladas sobre el rendimiento de las campañas. Admiten solicitar data para cuentas, instrumentos de financiamiento, campañas, line items, Tweets promocionados y creatividades de medios. La diferencia con el endpoint síncrono es que los endpoints de analytics asíncronos admiten rangos de fechas más amplios, de hasta 90 días, así como segmentación. Puedes encontrar más detalles sobre las diferencias entre ambos en nuestra página de Descripción general de Analytics.

A diferencia de nuestros endpoints síncronos, la limitación de frecuencia se basa en el número de jobs concurrentes para una cuenta determinada. En otras palabras, se basa en el número de jobs que pueden estar en estado de procesamiento en un momento dado. Contabilizamos esto a nivel de cuenta de anuncios.

​

Uso

Obtener métricas de campaña mediante los endpoints asíncronos de Analytics es un proceso de varios pasos. Consiste en crear un job, comprobar si el job ha terminado de procesarse y, por último, descargar los datos. El archivo de datos debe descomprimirse. Los cuatro pasos específicos se describen a continuación.

1. Crea el job con el endpoint POST stats/jobs/accounts/:account_id.
2. Realiza solicitudes a intervalos regulares al endpoint GET stats/jobs/accounts/:account_id para determinar si el job ha terminado de procesarse.
3. Una vez que el job haya terminado de procesarse, descarga el archivo de datos.
4. Descomprime el archivo de datos.

El objeto de respuesta incluido en el archivo de datos tiene el mismo esquema JSON que la respuesta del endpoint síncrono de Analytics.

Las métricas de campaña segmentadas solo están disponibles a través de los endpoints asíncronos de Analytics. Las métricas de campaña pueden desglosarse por ubicación, sexo, intereses, palabra clave y más. Para ver la lista completa de opciones, consulta la página Métricas y segmentación. Para solicitar métricas segmentadas, usa el parámetro de solicitud segmentation_type al crear el job.

​

Ejemplo

Esta sección muestra cómo usar los endpoints de analytics asíncronos.

Comienza creando un job mediante el endpoint POST stats/jobs/accounts/:account_id. El siguiente ejemplo solicita métricas de interacción —como impresiones, Me gusta, clics, etc.— para un elemento de línea específico durante una semana. (Ten en cuenta que el intervalo de tiempo solicitado llega hasta, pero no incluye, el 20 de marzo, ya que la marca de tiempo está configurada a medianoche.)

$ 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 respuesta no devuelve las métricas del elemento de línea. Solo proporciona información sobre el trabajo que acabas de crear. Se necesita el id del trabajo para verificar su estado. Esto se muestra en los atributos de la respuesta id e id_str.

A continuación, debes comprobar si el trabajo que creaste utilizando el id_str de la respuesta anterior ha terminado de procesarse, tal como se indica con "status": "SUCCESS" en la respuesta. Esto significa que los datos están listos para descargar. El campo url contiene el enlace de descarga.

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

Aunque en el ejemplo anterior pasamos un único id de tarea, en la práctica querrás usar el parámetro job_ids para comprobar el estado de varias tareas a la vez especificando hasta 200 id de tarea.

A continuación, descarga el archivo de datos utilizando el valor url indicado.

    $ 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
    Resolviendo ton.twimg.com (ton.twimg.com)... 72.21.91.70
    Conectando con ton.twimg.com (ton.twimg.com)|72.21.91.70|:443... conectado.
    Petición HTTP enviada, esperando respuesta... 200 OK
    Longitud: 381 [application/gzip]
    Guardando como: 'zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz'

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

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

Por último, descomprime el archivo.

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

El contenido del archivo se muestra a continuación.

`$ 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 y frecuencia media

Ejecutar en Postman

​

GET stats/accounts/:account_id/reach/campaigns

Obtén analíticas de alcance y frecuencia media para las campañas especificadas.

​

URL del recurso

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

​

Parámetros

Nombre	Descripción
account_id obligatorio	El identificador de la cuenta utilizada. Aparece en la ruta del recurso y, por lo general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto GET accounts. La cuenta especificada debe estar asociada al usuario autenticado. Tipo: string Ejemplo: 18ce54d4x5t
campaign_ids obligatorio	Limita la respuesta a las campañas deseadas especificando una lista de identificadores separados por comas. Se pueden proporcionar hasta 20 id. Nota: Se pueden proporcionar hasta 20 id de campaña. Tipo: string Ejemplo: 8fgzf
end_time obligatorio	Limita los datos recuperados a la hora de finalización especificada, expresada en ISO 8601. Nota: Debe expresarse en horas completas (0 minutos y 0 segundos). Tipo: string Ejemplo: 2017-05-26T07:00:00Z
start_time obligatorio	Limita los datos recuperados a la hora de inicio especificada, expresada en ISO 8601. Nota: Debe expresarse en horas completas (0 minutos y 0 segundos). Tipo: string Ejemplo: 2017-05-19T07:00:00Z

​

Ejemplo de solicitud

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

​

Respuesta de ejemplo

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

Obtén analíticas de alcance y frecuencia media para los instrumentos de financiación especificados.

​

URL del recurso

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

​

Parámetros

Nombre	Descripción
account_id obligatorio	El identificador de la cuenta utilizada. Aparece en la ruta del recurso y, por lo general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto GET accounts. La cuenta especificada debe estar asociada al usuario autenticado. Tipo: string Ejemplo: 18ce54d4x5t
funding_instrument_ids obligatorio	Restringe la respuesta a los instrumentos de financiación deseados especificando una lista de identificadores separados por comas. Se pueden proporcionar hasta 20 id. Nota: Se pueden proporcionar hasta 20 id de instrumentos de financiación. Tipo: string Ejemplo: lygyi
end_time obligatorio	Restringe los datos recuperados a la hora de finalización especificada, expresada en ISO 8601. Nota: Debe expresarse en horas completas (0 minutos y 0 segundos). Tipo: string Ejemplo: 2017-05-26T07:00:00Z
start_time obligatorio	Restringe los datos recuperados a la hora de inicio especificada, expresada en ISO 8601. Nota: Debe expresarse en horas completas (0 minutos y 0 segundos). Tipo: string Ejemplo: 2017-05-19T07:00:00Z

​

Ejemplo de solicitud

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

​

Respuesta de ejemplo

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

​

Analítica sincrónica

Ejecutar en Postman

​

GET stats/accounts/:account_id

Recupera analíticas sincrónicas de la cuenta actual. Se permite un intervalo de tiempo máximo (end_time - start_time) de 7 días.

​

URL del recurso

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

​

Parámetros

Nombre	Descripción
account_id obligatorio	El identificador de la cuenta apalancada. Aparece en la ruta del recurso y, por lo general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto GET accounts. La cuenta especificada debe estar asociada con el usuario autenticado. Tipo: string Ejemplo: 18ce54d4x5t
end_time obligatorio	Restringe los datos recuperados hasta la hora de finalización especificada, expresada en ISO 8601. Nota: Debe expresarse en horas completas (0 minutos y 0 segundos). Tipo: string Ejemplo: 2017-05-26T07:00:00Z
entity obligatorio	El tipo de entidad para la que se recuperarán datos. Tipo: enum Valores posibles: ACCOUNT, CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, ORGANIC_TWEET, PROMOTED_ACCOUNT, PROMOTED_TWEET, MEDIA_CREATIVE
entity_ids obligatorio	Las entidades específicas para las que se recuperarán datos. Especifica una lista de id de entidad separada por comas. Nota: Se pueden proporcionar hasta 20 id de entidad. Tipo: string Ejemplo: 8u94t
granularity obligatorio	Especifica el nivel de detalle de los datos recuperados. Tipo: enum Valores posibles: DAY, HOUR, TOTAL
metric_groups obligatorio	Las métricas específicas que deben devolverse. Especifica una lista de grupos de métricas separada por comas. Para obtener más información, consulta Métricas y segmentación. Nota: Los datos de MOBILE_CONVERSION deben solicitarse por separado. Tipo: enum Valores posibles: BILLING, ENGAGEMENT, LIFE_TIME_VALUE_MOBILE_CONVERSION, MEDIA, MOBILE_CONVERSION, VIDEO, WEB_CONVERSION
placement obligatorio	Restringe los datos recuperados a una ubicación específica. Nota: Solo se acepta un valor por solicitud. Para entidades con ubicación tanto en X como en X Audience Platform, se requieren solicitudes separadas, una para cada valor de ubicación. Tipo: enum Valores posibles: ALL_ON_TWITTER, PUBLISHER_NETWORK, SPOTLIGHT, TREND
start_time obligatorio	Restringe los datos recuperados a la hora de inicio especificada, expresada en ISO 8601. Nota: Debe expresarse en horas completas (0 minutos y 0 segundos). Tipo: string Ejemplo: 2017-05-19T07:00:00Z

​

Ejemplo de solicitud

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

​

Ejemplo de respuesta

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

Ejecutar en Postman

​

GET stats/accounts/:account_id/active_entities

Recupera detalles sobre qué métricas de analytics de las entidades han cambiado en un período de tiempo determinado.

Este endpoint debe usarse junto con nuestros endpoints de analytics. Los resultados de este endpoint indican para qué entidades de anuncios solicitar analytics. Consulta nuestra Guía de entidades activas para conocer las pautas de uso.

Los eventos de cambio están disponibles en intervalos de una hora.

• Los valores start_time y end_time especifican qué intervalos de una hora consultar.
• El array data devuelto incluirá un objeto por cada entidad que deba incluirse en solicitudes de analytics posteriores.
• IMPORTANTE: Las fechas que deben especificarse en las solicitudes de analytics posteriores deben determinarse en función de los valores activity_start_time y activity_end_time.
  • Estos valores representan los rangos de tiempo a los que se aplican los eventos de cambio almacenados. Esto se devuelve por entidad.

Nota: Se permite un rango de tiempo máximo (end_time - start_time) de 90 días.

​

URL del recurso

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

​

Parámetros

Nombre	Descripción
account_id obligatorio	El identificador de la cuenta utilizada. Aparece en la ruta del recurso y, por lo general, es un parámetro obligatorio para todas las solicitudes de la Advertiser API, excepto GET accounts. La cuenta especificada debe estar asociada con el usuario autenticado. Tipo: string Ejemplo: 18ce54d4x5t
end_time obligatorio	Limita los datos recuperados hasta la hora de finalización especificada, expresada en ISO 8601. Nota: Debe expresarse en horas completas (0 minutos y 0 segundos). Tipo: string Ejemplo: 2017-05-26T07:00:00Z
entity obligatorio	El tipo de entidad para la que se recuperarán datos. Tipo: enum Valores posibles: CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE, PROMOTED_ACCOUNT, PROMOTED_TWEET
start_time obligatorio	Limita los datos recuperados a partir de la hora de inicio especificada, expresada en ISO 8601. Nota: Debe expresarse en horas completas (0 minutos y 0 segundos). Tipo: string Ejemplo: 2017-05-19T07:00:00Z
campaign_ids opcional	Limita la respuesta solo a las entidades asociadas con las campañas deseadas, especificando una lista de identificadores separada por comas. Se pueden proporcionar hasta 200 id. Nota: Mutuamente excluyente con funding_instrument_ids y line_item_ids. Tipo: string Ejemplo: 8wku2
funding_instrument_ids opcional	Limita la respuesta solo a las entidades asociadas con los instrumentos de financiación deseados, especificando una lista de identificadores separada por comas. Se pueden proporcionar hasta 200 id. Nota: Mutuamente excluyente con campaign_ids y line_item_ids. Tipo: string Ejemplo: lygyi
line_item_ids opcional	Limita la respuesta solo a las entidades asociadas con los line items deseados, especificando una lista de identificadores separada por comas. Se pueden proporcionar hasta 200 id. Nota: Mutuamente excluyente con campaign_ids y line_item_ids. Tipo: string Ejemplo: 8v7jo

​

Ejemplo de solicitud

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

​

Ejemplo de respuesta

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