API de cohorte

Premium
Para:
Marketers Marketers
Última actualización:

En resumen: La API de Cohort proporciona a los anunciantes una forma programática de obtener datos de cohorte. Utiliza la API para integrar datos de cohorte en sistemas de BI y de automatización de marketing.

API de cohorte

La API de cohortes se utiliza para obtener datos de rendimiento de campañas de cohortes de la plataforma de AppsFlyer. Es funcionalmente equivalente al dashboard de cohorte.  

Para usar cohorte y retención, defines los datos que deseas ver. Seleccionas usuarios de una aplicación y los segmentas por tiempo de conversión. Se encuentran disponibles métricas de la cohorte como ingresos, ROI y tasas de conversión de eventos. La cohorte se puede desglosar más, con fines comparativos, en dimensiones como campaña o fuente de medios. El resultado se devuelve como un archivo CSV o JSON. Puedes usar los resultados para descubrir patrones o cambios en el rendimiento a lo largo de los ciclos de vida del usuario o de la campaña.

Consulta Casos de uso de la cohorte. 

Para utilizar la API de cohorte:

  1. AppsFlyerAdmin_us-en.pngConsigue el token API. Un administrador debe recuperar el token.
  2. Proporciona a tu desarrollador el token API que se usará en el encabezado de autenticación.
  3. Otorga a tus desarrolladores los parámetros que deben introducir cuando realicen la llamada a la API, como se describe en las secciones que siguen. Los parámetros determinan en qué se centra el reporte, cómo se organiza y proporcionan un marco temporal para el reporte.
  4. Dile a tu desarrollador que siga las instrucciones de la API maestra en el centro de desarrolladores.

Parámetros de la API de cohorte

Utiliza los siguientes parámetros de filtro para obtener los datos necesarios. 

Nombre de parámetro Descripción Obligatorio 
portador Token de la API utilizado en el encabezado de autenticación de la API. Sí
cohort _type El tipo de atribución de cohorte (conversión) es uno de los siguientes: user_acquisition, retargeting, unified
  • Unificado: combina el rendimiento de las campañas de retargeting y adquisición de usuarios.
  • Si un evento se atribuye tanto a campañas de retargeting como a campañas de adquisición de usuarios, solo se incluye el evento de retargeting en los KPIs devueltos, lo que significa que is_primary=true.
  • Formato: Cadena
  • Ejemplo: "cohort_type": "user_acquisition"
Sí
min_cohort_size El tamaño mínimo de la cohorte se utiliza para reducir el número de registros devueltos al excluir cohortes que tienen pocos usuarios. Esto significa que el KPI de "usuarios" tiene un valor igual o mayor al especificado. 
  • Formato: Entero
  • Valor mínimo permitido: 1. No envíes 0 (cero)
  • Predeterminado: 1 
  • Ejemplo: "min_cohort_size": 50
No
desde  Límite inferior del rango de fechas de atribución de LTV. La fecha más temprana admitida es 720 días antes de la fecha actual.  
  • Formato: Cadena aaaa-mm-dd
  • Ejemplo: "from": "2020-01-02"
Sí
a Límite superior del rango de fechas de atribución del LTV
  • Número de días en el rango: 1-31 días
  • Para un solo día: from y to los valores son idénticos. 
  • Formato: aaaa-mm-dd
  • Ejemplo: "from": "2020-01-01", "to": 2020-01-31 son 31 días.
 Sí
granularidad

Granularidad horaria para las últimas 72 horas configurando "granularity": "hour" y configurando el rango from y to para incluir la hora del día.

  • Formato: aaaa-mm-dd hh:mm:ss
  • Ejemplo:

"granularity": "hour", "from": "2021-12-01 14:00:00", "to": "2021-12-03 11:00:00",

 No
partial_data

Para evitar distorsiones e interpretaciones erróneas de datos, la cohorte devuelve los datos de días completos. Sin embargo, los datos de días parciales pueden ser útiles.  

El número de días completos de la cohorte para una consulta se calcula como la diferencia entre la fecha de hoy y la fecha a.

  • [Predeterminado] Si es falso, se devuelven días completos.
  • Si es verdadero, se devuelven hasta 180 días de cohorte, incluidos los días que tienen datos incompletos.  
  • Formato: Booleano
  • Versión de interfaz de usuario de la plataforma: false

Ejemplo: El 10 de mayo, el número de días completos de la cohorte para los usuarios que se convertirían durante el 1-30 de abril, es de 10.  

  • Si es falso [predeterminado], se devuelven los días 0-9 de la cohorte. Este es el número de días (10) entre la última fecha de conversión y hoy.  
  • Si es verdadero, se devuelven los días 1-40 de la cohorte. Los días 11-40 contienen datos parciales y no se devuelven. Por ejemplo, desde el 20 de abril solo han transcurrido 20 días, y así sucesivamente.

Nota: Los datos parciales solo se permiten cuando el tipo de agregación es acumulativo.

  No
filtros Permite filtrar los datos y el período de días devueltos. Selecciona los filtros de la lista de dimensiones del filtro.
  • Formato: Cadenas en un JSON anidado. Los valores deben estar en un array.
  • Ejemplo de limitación a geolocalizaciones específicas: "filters": {"geo": ["US"]} incluye solo los usuarios atribuidos a Estados Unidos. 
  • Ejemplo de período (cohorte) días El filtro period establece los días para los cuales se devuelven las medidas. Los valores posibles son: 0-180. 
  • Predeterminado: Si no se establece ningún filtro de período, se devuelven los días 0-30, 60, 90 y 180.  Ejemplo de filtro con período
 No
agrupación
  • Utiliza parámetros de agrupación para incluir columnas adicionales y hacer que tus reportes sean menos granulares.
  • Selecciona 1-7 agrupaciones de la lista de dimensiones de agrupación.
  • Formato: Cadenas en un array
  • Ejemplo: "groupings": ["af_ad", "c", "af_c_id", "af_prt"]
Sí
kpis Los KPIs son las métricas utilizadas para obtener insights sobre el comportamiento de tu aplicación. Aprende a seleccionar y formatear KPIs Sí
preferred_currency Un parámetro que establece el formato de los KPI devueltos. Aprende a formatear los KPIs No
preferred_timezone Un parámetro que establece el formato de los KPI devueltos. Aprende a formatear los KPIs No
aggregation_type Un parámetro que establece el formato de los KPI devueltos. Aprende a formatear los KPIs Sí
per_user Un parámetro que establece el formato de los KPI devueltos. Aprende a formatear los KPIs No

Selección y formateo de KPIs

  • La tabla enumera los KPIs disponibles y sus funciones asociadas. Cuando llamas a un KPI, se devuelven todas sus funciones.
  • Los siguientes KPIs siempre devuelven: usuarios, eCPI y costo.  
  • Selecciona un KPI adicional por llamada.
  • Por cada KPI solicitado, se devuelven todas las funciones.  
  • Formato: Cadenas en un array 
    • Ejemplo A: "kpis": ["sessions"]
    • Ejemplo B: "kpis": ["event_name"]
    Funciones
Predeterminado/Opcional   KPI (nombre de dimensiones)   Recuento cvr (tasa de conversión) Calificación Suma Usuarios únicos
Número Porcentaje Porcentaje Número Número
Siempre usuarios SÍ - - - -
Siempre eCPI - - - SÍ -
Siempre costo - - - SÍ -
Opcional "event_name"(4)  SÍ SÍ - Sí (3) SÍ
Opcional ingresos SÍ - - SÍ -
Opcional roas - - SÍ - -
Opcional roi - - SÍ - -
Opcional sesiones SÍ - SÍ - Sí(1)
Opcional desinstalaciones (2) SÍ - SÍ - -

(1) Las sesiones únicas regresan cuando aggregation_type=on_day

(2) No disponible cuando cohort_type=unified  

(3) La suma significa los ingresos totales generados por el evento. En el reporte, esto se denota por sum_event_name"

Nota Los nombres de los eventos diferencian mayúsculas y minúsculas.

Formateando funciones de KPIs

Los siguientes parámetros establecen el formato de los KPIs devueltos. 

Parámetro Los valores Obligatorio 
preferred_currency Divisa de los ingresos de KPIs
  • Si es true, los se devuelven utilizando la divisa específica de la aplicación establecida en la plataforma.  
  • [Predeterminado] Si es falso, los resultados se devuelven en USD.
  • Formato: Booleano 
  • Versión de la interfaz de usuario de la plataforma: true
  No
preferred_timezone Zona horaria de rangos de datos
  • Si es true, las horas se expresan usando la zona horaria específica de la aplicación establecida en la plataforma.
  • [Predeterminado] Si es falso, las horas se expresan usando la zona horaria UTC.
  • Formato: Booleano 
  • Versión de la interfaz de usuario de la plataforma: true
  No
aggregation_type
  • cumulative
  • on_day

"aggregation_type": "cumulative"

Format: String

 Sí
per_user Divide la función de KPIs por el número de usuarios de la aplicación. Aplica únicamente a los KPIs relevantes.
  • Si es true, los valores de KPIs se dividen por el número de usuarios en la cohorte.
  • Si es falso, los valores de KPIs no se dividen por el número de usuarios.
  • Formato: Booleano 
  • Ejemplo si es verdadero: el ingreso total es de $1000 dólares, el número de usuarios de la aplicación es de $500, el valor devuelto es de $2 dólares. 
  No

Agrupar por y filtrar dimensiones

Nombre de la dimensión   Valor de API de la dimensión Agrupaciones Filters
Anuncio af_ad SÍ SÍ
ID del anuncio af_ad_id SÍ SÍ
Campaña c SÍ SÍ
ID de campaña af_c_id SÍ SÍ
Canal af_channel SÍ SÍ
Fuente de medios pid SÍ SÍ
Subparámetro 1 af_sub1 SÍ SÍ
Palabras clave af_keywords SÍ SÍ
Agencia af_prt SÍ SÍ
Tipo de conversión (1)   cohort_type SÍ SÍ
ID del sitio site_id SÍ SÍ
Tipo de ingresos (2) revenue_type x  SÍ
Tipo de toque atribuido (3) attributed_touch_type SÍ SÍ
Conjunto de anuncios af_adset SÍ SÍ
Adset ID af_adset_id SÍ SÍ
País geo SÍ SÍ
Fecha (fecha de instalación/reatribución/re-engagement en el contexto del cohort_type seleccionado)   date SÍ x 
Periodo

period

Explicación detallada

 

 x  SÍ

Notas: 

Opciones de dimensión:

(1) Tipo de conversión:  user_acquisition, retargeting(re-engagement y re-attribution), unified

  • Al exportar:
    • re-engagement se mostrará como retargeting
    • re-attribution se mostrará como reattr

(2) Tipo de ingresos: regular, ad_monetization

(3) Tipo de toque de atribución: click, impression, TV, pre-installed

Información adicional

Uso de filtros de período

El período se refiere al día posterior a la atribución, donde el período 0 es el día de atribución. Por ejemplo, un usuario instala la aplicación el 1 de enero. Este es el día de la atribución. Una compra realizada en el período 0 significa que se realizó el 1 de enero. Una compra realizada en el período 3 significa que se realizó el 4 de enero. De manera similar, un usuario que instala el 11 de enero, este es el período 0. Una compra realizada el 14 de enero sería el período 3.

Si el rango de fechas de tu reporte es del 1 al 11 de enero, se incluyen en el reporte los usuarios que atribuyeron (instalaron) durante este período. No se incluyen otros datos.  

  • El valor del período puede ser uno o más de los siguientes 0-180. Por ejemplo: 0, 1, 2, 30, 180.  
  • Si no se especifica ningún período, se devuelven los valores predeterminados 0, 1, 2 y así sucesivamente hasta 30, 60, 90 y 180.    

 Ejemplo de filtro de período

  • Este ejemplo contiene los parámetros de la consulta JSON, el raw data y el archivo CSV resultante.
  • La consulta filtra los períodos 0, 1 y 2 y el KPI seleccionado es ingresos.
  • La consulta especifica el tipo de agregación como "cumulativa". Cambia a "on_day" si deseas datos del mismo día.
  • Como resultado, los datos devueltos contienen:
    • Las medidas de usuarios, costo y eCPI que siempre se devuelven  
    • Medidas de ingresos consistentes en suma y recuento para cada período, es decir, los períodos 0, 1 y 2.  

Consulta

{
    "cohort_type": "user_acquisition",
    "min_cohort_size": 1,
    "preferred_timezone": false,
    "from": "2019-12-01",
    "to": "2020-01-01",
    "filters": {
        "period": [
            0,
            1,
            2
        ]
    },
    "aggregation_type": "cumulative",
    "per_user": false,
    "groupings": [
        "pid"
    ],
    "kpis": [
        "revenue"
    ]
}

Raw data

mceclip1.png

Resultados

mceclip0.png

Rasgos y limitaciones

Característica Observaciones 
Acceso a la ad network  No
Acceso a la agencia No
Zona horaria específica de la aplicación Sí
Moneda específica de la aplicación  Sí
Limitaciones de tamaño Ninguno
Limitación de tasa
  • Límite de tasa de llamadas a la API: 60 llamadas por minuto y 50.000 llamadas al día por cuenta
  • Las consultas devuelven hasta 30.000 filas
Datos orgánicos Disponible
Datos no orgánicos Disponible
Limitación de datos de costos
  • Los datos de costos son solo para campañas con al menos 1 instalación registrada.
  • AppsFlyer no reporta los datos de costos de las palabras clave que contienen letras mayúsculas en el reporte de cohortes o la API de cohortes.
  • No se pueden combinar algunas combinaciones de agrupamientos con el costo. Por ejemplo, Meta Ads puede tener agrupamientos por geolocalización o canales, pero no ambos. La combinación exacta de agrupaciones depende de la ad network.
Actualización de los datos La actualización de los datos depende de partial_data de la siguiente manera:  
  • [Predeterminado] Si es falso, a diario.
  • Si es verdadero, es continuo (en tiempo real).
  • Las métricas de costos y desinstalaciones se actualizan diariamente en todas las instancias.
Datos históricos Cohortes diarias: 2 años
Acceso de usuario a la cuenta El token de autorización está disponible para los usuarios administradores en el dashboard.
Ingresos de anuncios Para los eventos af_ad_revenue, la métrica de usuarios únicos no está disponible cuando el tipo de agregación es:
  • Acumulativa.
  • "On day" para fechas entre el 5 de octubre de 2022 y el 16 de febrero de 2023.
Agrupaciones semanales y mensuales Las agrupaciones de dimensiones semanales y mensuales no están disponibles con la API de cohortes. Utiliza el dashboard de cohortes.
Período de API de cohorte
  • El período de conversión se denomina 0 (Hora 0 o Día 0). Al siguiente período posterior a la conversión se le denomina 1 (Hora 1 o Día 1), y así sucesivamente.
  • En AppsFlyer un período de cohorte no toma en cuenta la marca de tiempo de instalación específica. Más bien, las horas de cohorte se redondean a la hora más cercana y los días de cohorte se basan en el día de calendario. Esto puede causar discrepancias al comparar los datos de cohortes de AppsFlyer con los datos de cohorte de otras redes, donde todos los períodos de cohorte están determinados por la marca de tiempo de instalación específica (es decir, una hora es 60 minutos después de la instalación, un día es el período posterior a la instalación de 24 horas después de la marca de tiempo de instalación). 
Fechas
  • Las fechas o rangos de fechas se refieren a fechas de lifetime value (LTV), es decir, la fecha en que el usuario se atribuyó (convirtió) y no la fecha de la actividad en sí.
  • La fecha más antigua admitida: 730 días antes de la fecha actual. Es decir, 2 años.
  • Rango máximo de consulta: 60 días.
Reinstalaciones
  • Si los eventos post-reinstalación son considerados orgánicos no atribuidos:
    • Se incluirán solo a partir del 26 de mayo de 2024. Más información
    • El tiempo de instalación se basa en el campo device_download_time.
    • No se cuentan para las mediciones de usuarios únicos y de retención.
  • Si los eventos post-reinstalación se atribuyen a la primera instalación, siempre se incluyen. Saber más
API de cohorte para partners El acceso a la API de cohorte para partners de marketing se está descontinuando a partir del 15 de septiembre de 2024. Se anima a los partners de marketing a habilitar Data Locker para garantizar el acceso continuo a los datos de los clientes.