De un vistazo: la API de reportes de cohortes proporciona a los anunciantes una forma programática de obtener datos de Cohorte. Utiliza la API para integrar datos de Cohorte en Business Intelligence y los sistemas de automatización de marketing.
API de reportes de cohortes
La API de reportes de cohortes se utiliza para obtener datos de rendimiento de campañas de cohortes de la plataforma AppsFlyer. Es funcionalmente equivalente al panel de control de Cohort.
Consideraciones para desarrolladores
- Fechas: las fechas o rangos de fechas se refieren a fechas de valor de vida útil (LTV), es decir, la fecha en que el usuario se atribuyó (convirtió) y no la fecha de la actividad en sí.
- Valores booleanos: verdadero o falso (distinguen entre mayúsculas y minúsculas).
- Tráfico de agencias transparente y no transparente: la fuente de medios del tráfico impulsado por agencias es siempre la agencia y no la fuente de medios original. En la actualidad, la versión de la interfaz de usuario (UI) de cohorte se comporta de manera diferente.
- Aplicación única: la API de cohortes es una solución de aplicación única. Esto contrasta con el panel de cohorte, que admite múltiples aplicaciones en una sola llamada.
- Actualización de los datos: consulta rasgos y limitaciones.
Instrucciones de la API
Las secciones contienen la información necesaria para que puedas generar y utilizar la API de cohortes.
Datos de la API de cohortes
| Resumen general | La llamada a la API consiste en la ruta, los encabezados y un JSON que contiene la consulta de datos. Los datos se devuelven por defecto en un archivo CSV. |
| Ruta |
|
| Parámetros de ruta (obligatorio) |
|
|
Parámetros de consulta (opcional) |
Los resultados se devuelven como CSV o JSON. La estructura del archivo CSV es tabular mientras que la del JSON está orientada al registro.
|
| Método HTTP | POST |
| Tipos de contenido aceptado | application/json |
| Autorización |
|
| Limitaciones de fecha |
|
| Limitación de velocidad |
|
| Valores booleanos | Siempre en minúsculas: true, false |
Encabezados de solicitud
|
Clave |
value | Obligatorio |
|---|---|---|
| Tipo de contenido | application/json |
Sí |
| Authorization | Portador api_token_placeholder |
Sí |
| Aceptar | application/json |
Sí |
Parámetros de filtrado y agrupación
Utiliza los siguientes parámetros de filtro para obtener los datos necesarios.
|
Nombre de parámetro |
Descripción | Obligatorio |
|---|---|---|
|
cohort _type |
El tipo de atribución de cohorte (conversión) es uno de los siguientes:
|
Sí |
|
min_cohort_size |
El tamaño mínimo de cohorte se utiliza para reducir el número de registros devueltos al excluir a las cohortes que tienen pocos usuarios. Esto significa que el KPI de los usuarios tiene un valor igual o mayor al especificado.
|
No |
|
from |
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.
|
Sí |
|
a |
Límite superior del rango de fechas de atribución del LTV.
|
Sí |
|
granularity |
Granularidad horaria para las 72 horas anteriores, estableciendo
"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 to.
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.
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.
|
No |
Utiliza los siguientes parámetros de agrupación para incluir columnas adicionales y hacer que tus reportes sean menos granulares.
|
Parámetro |
Valores | Obligatorio |
|---|---|---|
|
groupings |
|
Sí |
Selección y formateo de KPI
- La tabla enumera los KPI disponibles y sus funciones asociadas. Cuando llamas a un KPI, se devuelven todas sus funciones.
- Los siguientes KPI siempre devuelven: usuarios, eCPI y costo.
- Selecciona un KPI adicional por llamada.
| Funciones | ||||||
|---|---|---|---|---|---|---|
| Predeterminado/ Opcional | KPI (nombre de dimensiones) | Recuento | CVR (tasa de conversión) | Calificación | Suma | Usuarios únicos |
| Cantidad | Porcentaje | Porcentaje | Cantidad | Cantidad | ||
| Siempre | usuario(s) | Y | - | - | - | - |
| Siempre | eCPI | - | - | Y | - | - |
| Siempre | costo | - | - | - | Y | - |
| OPCIONAL | "event_name"(4) |
Y | Y | - | Y (3) | Y |
| OPCIONAL | ingresos | Y | - | - | Y | - |
| OPCIONAL | ROAS | - | - | Y | - | - |
| OPCIONAL | roi | - | - | Y | - | - |
| OPCIONAL | Sesiones | Y | - | Y | - | Y(1) |
| OPCIONAL | uninstalls (2) | Y | - | Y | - | - |
|
(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 denomina (4) Nota: Los nombres de eventos distinguen entre mayúsculas y minúsculas. |
||||||
|
Parámetro |
Valores | Parámetro obligatorio |
|---|---|---|
|
KPIs |
Selecciona un KPI de los KPI disponibles. En el futuro, planeamos permitir la selección de múltiples KPI.
|
Sí |
Presentación de las funciones de los KPI
Los siguientes parámetros de formato de KPI establecen el formato de los KPI devueltos.
|
Parámetro |
Valores | Obligatorio |
|---|---|---|
|
preferred_currency |
Divisa de los ingresos de KPI
|
No |
|
preferred_timezone |
Zona horaria de rangos de datos
|
No |
|
aggregation_type |
|
Sí |
|
per_user |
Divide la función KPI por el número de usuarios de la aplicación. Aplica únicamente a los KPI relevantes.
|
No |
Lista de dimensiones de agrupamiento y filtro
|
Nombre de la dimensión |
Valor de API de la dimensión |
Agrupaciones |
Filtros |
|---|---|---|---|
|
Anuncio |
af_ad |
Y |
Y |
|
ID de anuncio |
af_ad_id |
Y |
Y |
|
Campaña |
C |
Y |
Y |
|
ID de campaña |
af_c_id |
Y |
Y |
|
Canal |
af_channel |
Y |
Y |
|
Fuente de medios |
PID |
Y |
Y |
|
Subparámetro 1 |
af_sub1 |
Y |
Y |
|
Palabras clave |
af_keywords |
Y |
Y |
|
Agencia |
af_prt |
Y |
Y |
|
Tipo de conversión (1) |
cohort_type |
Y |
Y |
|
ID de sitio |
site_id |
Y |
Y |
|
Tipo de ingresos (2) |
revenue_type |
x |
Y |
|
Tipo de toque atribuido (3) |
attributed_touch_type |
Y |
Y |
|
Conjunto de anuncios |
af_adset |
Y |
Y |
|
ID de conjunto de anuncios |
af_adset_id |
Y |
Y |
|
País |
geolocalización |
Y |
Y |
|
Fecha (fecha de instalación/reatribución/re-engagement en el contexto del cohort_type seleccionado) |
fecha |
Y |
x |
|
Periodo |
period
|
X |
Y |
|
Notas: Opciones de dimensión: (1) Tipo de conversión:
(2) Tipo de ingresos: click, impression, TV, pre-installed
|
|||
Ejemplo de curl
Este ejemplo contiene una llamada a la API completa.
curl -L -X POST 'https://hq1.appsflyer.com/api/cohorts/v1/data/app/<insert your app_id here>?format=<insert results format here>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <cohort_api_token_placeholder. Note the token has more than 700 characters.>' \
-H 'Accept: application/json' \
--data-raw '{
"cohort_type": "user_acquisition",
"min_cohort_size": 1,
"preferred_timezone": false,
"from": "2020-01-01",
"to": "2020-01-31",
"filters": {
"period": [
0,
1,
2,
10,
30,
60
],
"geo": [
"US",
"CN"
],
"pid": [
"Meta ads",
"googleadwords_int"
]
},
"preferred_currency": true,
"aggregation_type": "on_day",
"per_user": false,
"groupings": [
"pid",
"date"
],
"kpis": [
"sessions"
]
}'
Ejemplo de Python
import http.client
import mimetypes
conn = http.client.HTTPSConnection("hq1.appsflyer.com")
payload = "{\r\n \"cohort_type\": \"user_acquisition\",\r\n \"min_cohort_size\": 1,\r\n \"preferred_timezone\": false,\r\n \"from\": \"2020-05-01\",\r\n \"to\": \"2020-05-10\",\r\n \"preferred_currency\": true,\r\n \"aggregation_type\": \"cumulative\",\r\n \"per_user\": false, \r\n \"groupings\": [\r\n \"pid\",\r\n \"date\"\r\n ],\r\n \"kpis\": [\r\n \"roas\"\r\n ]\r\n}"
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer [Enter token here]',
'Accept': 'application/json',
'Content-Type': 'application/json'
}
conn.request("POST", "/api/cohorts/v1/data/app/[My App ID here]?format=csv", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Ejemplos de casos de uso
Ejemplo 1: Retención
Retención de fuentes de medios (sesiones) de los usuarios que instalaron la aplicación durante enero los días 7, 14 y 28
{
"per_user": false,
"groupings": [
"pid"
],
"filters": {
"period": [
7, 14, 28
]
},
"partial_data": false,
"aggregation_type": "on_day",
"min_cohort_size": 1,
"cohort_type": "user_acquisition",
"from": "2021-01-01",
"to": "2021-01-30",
"kpis": [
"sessions"
]
}Ejemplo 2: Compras de campaña
Ingresos post-instalación el día 3 de la cohorte por campaña
{
"per_user": false,
"groupings": [
"c"
],
"filters": {
"period": [
3
],
"c":[
"example_campaign_name"
]
},
"partial_data": false,
"aggregation_type": "cumulative",
"min_cohort_size": 1,
"cohort_type": "user_acquisition",
"from": "2021-01-01",
"to": "2021-01-30",
"kpis": [
"Checkout Start"
]
}Ejemplo 3: Actividad de ayer
¿Qué actividad realizaron ayer los usuarios que convirtieron (instalaron, volvieron a participar, re-atribuyeron) durante un período de conversión determinado?
Utiliza los datos disponibles a través de Cohorte para Data Locker. El período de conversión se limita a los 360 días anteriores.
Información adicional
Códigos de respuesta y resolución de problemas
|
Código de respuesta |
Mensaje |
Observaciones |
|---|---|---|
| 200 | OK |
Datos válidos devueltos |
| 200 | OK |
|
| 401 | No autorizado |
|
| 404 | No se encuentra |
|
| 422 | Entidad no procesable |
Las razones comunes de este código de error son:
|
Estructura de nombres de archivos CSV
El nombre asignado a un archivo CSV que se devuelve se genera a partir de la consulta a la API. La estructura es la que se detalla en la tabla que sigue.
Ejemplo de nombre de archivo CSV
cohort_aggregation_type_per_user_kpi_report_app_id_from_to_timezone_currency_hash.csv| Variable | Valores posibles |
|---|---|
| aggregation_type |
|
| per_user |
|
| KPI | Ejemplo: sessions |
| app_id | El ID de aplicación solicitado |
| desde | Fecha from: formato aaaa-mm-dd |
| a | Fecha to: formato aaaa-mm-dd |
| Zona horaria | Zona horaria por defecto UTC |
| currency | Código de divisa por defecto USD |
| hash |
Cadena hash alfanumérica, longitud=5 |
Uso de filtros de período
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 igual manera, un usuario que instala el 11 de enero, este es el período 0. Una compra realizada el 14 de enero sería 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 revenue.
- 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": "on_day",
"per_user": false,
"groupings": [
"pid"
],
"kpis": [
"revenue"
]
}
Raw Data
Resultados
Asignación de la interfaz de usuario a parámetros de API
Las cifras que siguen asignan la interfaz de usuario de las analíticas de cohorte a los parámetros de la API. Las dos soluciones: API e interfaz de usuario son similares pero no idénticas.
La versión de la API tiene las siguientes opciones adicionales:
- Selección de divisa
- Selección de zona horaria
- Filtrado por período
Diferencia entre tipos de agregación
Rasgos y limitaciones
| Característica | Observaciones |
|---|---|
| Acceso a la red de publicidad |
No. Los partners de gestión de campañas pueden usar la API si el anunciante otorga permiso. |
| Acceso de agencias | No |
| Transparencia de Agencias | No se admite |
| Zona horaria específica de la aplicación | Sí |
| Moneda específica de la aplicación | Sí |
| Limitaciones de tamaño | Ninguna |
| Limitación de velocidad |
Límite de tasa de llamadas a la API: 60 llamadas por minuto por cuenta |
| datos orgánicos | Disponible |
| Datos no orgánicos | Disponible |
| Limitación de datos de costos |
|
| Actualización de los datos |
La actualización de los datos depende de partial_data de la siguiente manera:
|
| Historial de datos | Cohorte diaria: 2 años |
| Acceso de usuario a la cuenta | El token de autorización está disponible para los usuarios administradores en el panel de control. |
| Ingresos por anuncios |
Para eventos af_ad_revenue, la métrica de usuarios únicos no está disponible cuando el tipo de agregación es "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 panel de control de cohortes. |
| API de cohortes |
|