Visão geral: a API de relatórios de cohort, ou Cohort reporting API, permite que os anunciantes acessem dados de cohort de forma programática.Use a API para integrar dados de cohort em sistemas de BI e de automação de marketing.
API de relatórios de cohort
A API de relatórios de cohort é usada para obter dados de performance de campanhas de cohort na plataforma da AppsFlyer. É funcionalmente equivalente ao dashboard de Cohort.
Observações para desenvolvedores
- Datas: datas ou intervalos de datas referem-se às datas de lifetime value (LTV), ou seja, a data na qual o usuário foi atribuído (converteu) e não a data da atividade em si.
- Valores booleanos: que podem ser true (verdadeiros) ou false (falsos) (com distinção de maiúsculas e minúsculas).
- Tráfego de agência transparente e não transparente: o canal de mídia responsável pelo tráfego direcionado pela agência é sempre a agência e não o canal de mídia original. Atualmente, a versão da UI do cohort se comporta de maneira diferente.
- Aplicativo único: a Cohort API é uma solução de aplicativo único. Isso contrasta com o dashboard de Cohort, que oferece suporte a vários aplicativos em uma única chamada.
- Atualização de dados: veja características e limitações.
Instruções da API
As seções contêm as informações necessárias para que você gere e use a Cohort API.
Fatos da Cohort API
| Visão geral | A chamada da API consiste da URL de requisição, do cabeçalho e de um JSON contendo os parâmetros de consulta. Por padrão, os dados são retornados em um arquivo CSV. |
| URL de requisição |
|
| Parâmetros da requisição (obrigatórios) |
|
|
Parâmetros de consulta (opcional) |
Os resultados retornam como CSV ou JSON. A estrutura do arquivo CSV é tabular, enquanto a do registro JSON é orientada.
|
| Método HTTP | POST |
| Tipos de conteúdo aceitos | application/json |
| Autorização |
|
| Limitações de data |
|
| Limitação de taxa |
|
| Valores booleanos | Sempre em minúsculas: true, false |
Solicitar cabeçalhos
|
Chave |
Valor | Obrigatório |
|---|---|---|
| Tipo de conteúdo | application/json |
Sim |
| Authorization | Portador api_token_placeholder |
Sim |
| Aceitar | application/json |
Sim |
Parâmetros de filtragem e agrupamento
Use os parâmetros de filtro a seguir para obter os dados necessários.
|
Nome do parâmetro |
Descrição | Obrigatório |
|---|---|---|
|
cohort _type |
O tipo de atribuição (conversão) do cohort é um dos seguintes:
|
Sim |
|
min_cohort_size |
O tamanho mínimo do cohort é usado para reduzir o número de registros retornados, excluindo cohorts com poucos usuários. Isso significa que o KPI do usuário possui um valor igual ou superior ao valor especificado.
|
Não |
|
from |
Limite inferior do período de atribuição de LTV. A data mais antiga suportada é 720 dias antes da data atual.
|
Sim |
|
to |
Limite superior do período de atribuição de LTV
|
Sim |
|
granularidade |
Granularidade horária para as 72 horas anteriores definindo
"granularity": "hour",
"from": "2021-12-01 14:00:00", "to": "2021-12-03 11:00:00",
|
Não |
|
partial_data |
Para evitar distorção e má interpretação dos dados, o cohort retorna dados de dias completos. No entanto, os dados de dias parciais podem ser úteis. O número de dias de cohort completos para uma consulta é calculado como a diferença entre a data de hoje e a data final (to).
Exemplo: em 10 de maio, o número de dias de cohort completos para usuários que realizaram conversões entre 1 e 30 de abril é 10.
Observação: dados parciais só são permitidos quando o tipo de agregação é cumulativo. |
Não |
|
Filtros |
Filtre os dados e os dias do período retornados. Selecione filtros na lista de dimensões de filtro.
|
Não |
Use os parâmetros de agrupamento a seguir para incluir colunas adicionais e reduzir a granularidade dos seus relatórios.
|
Parâmetro |
Valores | Obrigatório |
|---|---|---|
|
agrupamentos |
|
Sim |
Selecionando e formatando KPIs
- A tabela lista os KPIs disponíveis e suas funções associadas. Quando você chama um KPI, todas as suas funções retornam.
- Os seguintes KPIs sempre retornam: usuários, ecpi e custo
- Selecione um KPI adicional por chamada.
| Funções | ||||||
|---|---|---|---|---|---|---|
| Padrão/Opcional | KPI (nome das dimensões) | Contagem | cvr (taxa de conversão) | Taxa | Soma | Usuários únicos |
| Número | Percentual | Percentual | Número | Número | ||
| Sempre | usuários | S | - | - | - | - |
| Sempre | eCPI | - | - | S | - | - |
| Sempre | custo | - | - | - | S | - |
| Opctional | "event_name"(4) |
S | S | - | S (3) | S |
| Opctional | receita | S | - | - | S | - |
| Opctional | ROAS | - | - | S | - | - |
| Opctional | roi | - | - | S | - | - |
| Opctional | sessões | S | - | S | - | S (1) |
| Opctional | desinstalações (2) | S | - | S | - | - |
|
(1) Sessões únicas retornam quando agregation_type=on_day (2) Não disponível quando cohort_type=unified (3) Soma significa a receita total gerada pelo evento. No relatório, isso é indicado por (4) Atenção! Os nomes dos eventos diferenciam maiúsculas de minúsculas |
||||||
|
Parâmetro |
Valores | Parâmetro obrigatório |
|---|---|---|
|
kpis |
Selecione um KPI dentre os KPIs disponíveis. No futuro, permitiremos a seleção de vários KPIs.
|
Sim |
Apresentação de funções de KPI
Os seguintes parâmetros de formato de KPI definem o formato dos KPIs retornados.
|
Parâmetro |
Valores | Obrigatório |
|---|---|---|
|
preferred_currency |
Moeda de receita do KPI
|
Não |
|
preferred_timezone |
Fuso horário dos intervalos de dados
|
Não |
|
aggregation_type |
|
Sim |
|
per_user |
Divida a função KPI pelo número de usuários do aplicativo. Aplica-se apenas a KPIs relevantes.
|
Não |
Lista de dimensões agrupar e filtrar por
|
Nome da dimensão |
Valor da API de dimensão |
Agrupamentos |
Filtros |
|---|---|---|---|
|
Anúncio |
af_ad |
S |
S |
|
ID do anúncio |
af_ad_id |
S |
S |
|
Campanha |
C |
S |
S |
|
ID da campanha |
af_c_id |
S |
S |
|
Canal |
af_channel |
S |
S |
|
Fonte de mídia |
pid |
S |
S |
|
Subparâmetro 1 |
af_sub1 |
S |
S |
|
Palavras-chave |
af_keywords |
S |
S |
|
Agência |
af_prt |
S |
S |
|
Tipo de conversão (1) |
cohort_type |
S |
S |
|
Site ID |
site_id |
S |
S |
|
Tipo de receita (2) |
revenue_type |
x |
S |
|
Tipo de toque atribuído (3) |
attributed_touch_type |
S |
S |
|
Conjunto de anúncios |
af_adset |
S |
S |
|
Adset ID |
af_adset_id |
S |
S |
|
País |
geolocalização |
S |
S |
|
Data (data de instalação/reatribuição/reengajamento no contexto do cohort_type selecionado) |
data |
S |
x |
|
Período |
período
|
X |
S |
|
Observações: Opções de dimensão: (1) Tipo de conversão:
(2) Tipo de receita: clique, impressão, TV, pré-instalado
|
|||
Exemplo de ondulação
Este exemplo contém uma chamada de 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"
]
}'
Exemplo 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"))
Exemplos de casos de uso
Exemplo 1: Retenção
Retenção de fontes de mídia (sessões) de usuários que instalaram o aplicativo em janeiro, nos dias 7, 14 e 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"
]
}Exemplo 2: compras feitas em uma campanha
Receita pós-instalação do dia 3 da cohort, por campanha
{
"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"
]
}Exemplo 3: atividades de ontem
Quais foram as atividade que os usuários que converteram (instalaram, reengajaram, foram reatribuídos) realizaram durante um determinado período de conversão no dia anterior?
Use os dados disponíveis via Cohort para Data Locker. O período de conversão é limitado aos 360 dias anteriores.
Informações adicionais
Códigos de resposta e identificação e solução de problemas
|
Código de resposta |
Mensagem |
Observação |
|---|---|---|
| 200 | OK |
Dados válidos retornados |
| 200 | OK |
|
| 401 | Não autorizado |
|
| 404 | Não encontrado |
|
| 422 | Entidade não processável |
Os motivos comuns para esse erro são:
|
Estrutura de nome de um arquivo CSV
O nome de um arquivo CSV retornado é gerado a partir da consulta da API. A estrutura está detalhada na tabela a seguir.
Exemplo de nome de um arquivo CSV
cohort_aggregation_type_per_user_kpi_report_app_id_from_to_timezone_currency_hash.csv| Variável | Valores possíveis |
|---|---|
| aggregation_type |
|
| per_user |
|
| KPI | Exemplo: sessões |
| app_id | O ID do aplicativo solicitado |
| a partir de | data de (from): formato aaaa-mm-dd |
| to | data até (to): formato aaaa-mm-dd |
| fuso horário | Fuso horário padrão UTC |
| currency | Código de moeda padrão USD |
| hash |
Comprimento da string anonimizada alfanumérica = 5 |
Usando filtros de período
O período refere-se ao dia pós-atribuição, onde o período 0 é o dia da atribuição. Por exemplo, um usuário instala o aplicativo em 1 de janeiro. Esse é o dia da atribuição. Uma compra feita no período 0 significa que ela foi feita em 1 de janeiro. Uma compra feita no período 3 significa que ela foi feita em 4 de janeiro. Da mesma forma, quando um usuário instala o app em 11 de janeiro, esse passa a ser seu período 0 específico. Assim, uma compra feita em 14 de janeiro seria o período 3.
Se o intervalo de datas do seu relatório for de 1 a 11 de janeiro, os usuários que atribuíram (instalaram) durante esse período serão incluídos no relatório. Nenhum outro dado está incluído.
- O valor do período pode ser um ou mais de 0-180. Por exemplo, 0, 1, 2, 30, 180.
- Se nenhum período for especificado, os valores padrão de 0, 1, 2 até 30, 60, 90 e 180 serão retornados.
Exemplo de filtro de período
- Este exemplo contém os parâmetros de consulta JSON, dados brutos e arquivo CSV resultante.
- A consulta filtra o período de 0, 1 e 2 e o KPI selecionado é receita.
- Como resultado, os dados retornados contêm:
- As métricas de usuários, custo e ecpi, que sempre retornam
- Métricas de receita que consistem em soma e contagem para cada período, significando os períodos 0, 1 e 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"
]
}
Dados brutos
Resultados
Mapeamento da interface do usuário para parâmetros de API
As imagens abaixo mapeiam a interface do usuário da análise de cohort para os parâmetros da API. As duas soluções – API e interface do usuário são semelhantes, mas não idênticas.
A versão da API possui as seguintes opções adicionais:
- Seleção de moeda
- Seleção de fuso horário
- Filtrar por período
Diferença entre tipos de agregação
Características e limitações
| Característica | Observações |
|---|---|
| Acesso à ad network |
Não. Os parceiros de gerenciamento de campanha podem usar a API se o anunciante conceder permissão. |
| Acesso das agências | Não |
| Transparência da agência | Não compatível |
| Fuso horário específico do aplicativo | Sim |
| Moeda específica do aplicativo | Sim |
| Limitações de tamanho | Nenhum |
| Limitação de taxa |
Limite de taxa de chamadas de API: 60 chamadas por minuto por conta |
| Dados orgânicos | Disponível |
| Dados não orgânicos | Disponível |
| Limitação de dados de custo |
|
| Atualização de dados |
A atualização dos dados depende de parcial_data da seguinte forma:
|
| Dados históricos | Cohort diária: 2 anos |
| Acesso do usuário da conta | O token de autorização está disponível no dashboard para administradores. |
| Receita de anúncios |
Para eventos af_ad_revenue, a métrica de usuários únicos não está disponível quando o tipo de agregação é "no dia", para datas entre 5 de outubro de 2022 e 16 de fevereiro de 2023. |
| Agrupamentos semanais e mensais |
Os agrupamentos de dimensões semanais e mensais não estão disponíveis com a Cohort API. Use o dashboard Cohort. |
| Cohort API |
|