Cohort API

Premium
Para:
Profissionais de marketing
Última atualização:

Resumo: a Cohort 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.

Cohort API

A Cohort API é usada para coletar dados de performance de campanhas de cohort na plataforma da AppsFlyer. Funcionalmente, ela equivale ao dashboard de Cohort.  

Para usar cohort e retenção, você escolhe os dados que deseja visualizar. Você seleciona usuários de um aplicativo e os segmenta pela hora da conversão. Métricas de cohort como receita, ROI e taxas de conversão de eventos estão disponíveis. Para comparação, separe o cohort em dimensões como campanha ou fonte de mídia. O resultado é um arquivo CSV ou JSON.  Você pode usar os resultados para descobrir padrões ou mudanças na performance ao longo dos ciclos de vida dos usuários ou da campanha.

Consulte Casos de uso de cohort. 

Para usar a Cohort API

  1. AppsFlyerAdmin_us-en.pngAcesse o token da API. Um administrador precisa solicitar o token.
  2. Forneça ao seu desenvolvedor o token da API para ser usado no header de autenticação.
  3. Forneça aos seus desenvolvedores os parâmetros a serem inseridos quando eles fizerem a chamada de API, conforme descrito nas seções a seguir. Os parâmetros determinam o foco do relatório, como está organizado e fornecem um período para o relatório.
  4. Diga ao seu desenvolvedor para seguir as instruções da Master API no developer hub.

Parâmetros da Cohort API

Use os parâmetros de filtro a seguir para obter os dados necessários. 

Nome do parâmetro Descrição Obrigatório 
bearer Token da API usado no header de autenticação da API. Sim
cohort _type O tipo de atribuição de cohort (conversão) é um dos seguintes: user_acquisition, retargeting, unified
  • Unified combina a performance de campanhas de aquisição de usuários e retargeting.
  • Se um evento for atribuído a campanhas de retargeting e de aquisição de usuários, somente o evento de retargeting será incluído nos KPIs retornados, o que significa is_primary=true.
  • Formato: String
  • Exemplo: "cohort_type": "user_acquisition"
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 "usuários" tem um valor igual ou maior do que o especificado. 
  • Formato: Inteiro
  • Valor mínimo permitido: 1. Não envie 0 (Zero)
  • Padrão: 1 
  • Exemplo: "min_cohort_size": 50
Não
from  Limite inferior do período de atribuição de LTV. A data mais antiga disponível é 720 dias antes da data atual. 
  • Formato: String aaaa-mm-dd
  • Exemplo: "from": "2020-01-02"
Sim
to Limite superior do período de atribuição de LTV
  • Número de dias no intervalo: 1 a 31 dias
  • Para um único dia: os valores from e to são idênticos. 
  • Formato: aaaa-mm-dd
  • Exemplo: "from": "2020-01-01", "to": 2020-01-31 é 31 dias.
 Sim
granularity

Granularidade horária para as últimas 72 horas, com a configuração "granularity": "hour" e a configuração do intervalo from e to para incluir o horário do dia.

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

"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).

  • [Padrão] Se for "false", retorna dias completos.
  • Se for "true", retorna até 180 dias de cohort, incluindo dias com dados incompletos.  
  • Formato: Booleano
  • Versão da UI da plataforma: false

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.   

  • Se for "false" [padrão], com dias de cohort de 0-9 são retornados. Esse é o número de dias (10) entre a última data de conversão e hoje.  
  • Se for "true", os dias de coorte 1 a 40 são retornados. Os dias 11 a 40 contêm dados parciais e não retornam. Por exemplo, desde 20 de abril, se passaram apenas 20 dias, e assim por diante.

Atenção: : dados parciais só são permitidos quando o tipo de agregação é cumulativo.

  Não
filters Filtre os dados e os dias do período retornados. Selecione filtros na lista de dimensões de filtro.
  • Formato: Strings em um nested JSON. Os valores precisam estar em array.
  • Exemplo de limite para áreas geográficas específicas: "filters": {"geo": ["US"]}: inclui apenas usuários atribuídos aos Estados Unidos.  
  • Exemplo de período (cohort) em dias: O filtro period define os dias para os quais as métricas são retornadas. Os valores possíveis são: 0-180.  
  • Padrão: se nenhum filtro de "period" for definido, os dias 0 a 30, 60, 90 e 180 serão retornados.   Exemplo de filtro com "period"
 Não
groupings
  • Use parâmetros de agrupamento para incluir colunas adicionais e tornar seus relatórios menos granulares.
  • Selecione de 1 a 7 agrupamentos na lista de dimensões.
  • Formato: Strings em array
  • Exemplo: "groupings": ["af_ad", "c", "af_c_id", "af_prt"]
Sim
kpis KPIs são as métricas usadas para obter insights sobre o comportamento dos usuários no seu aplicativo. Aprenda a selecionar e formatar KPIs Sim
preferred_currency Um parâmetro que define o formato dos KPIs retornados. Aprenda a formatar KPIs Não
preferred_timezone Um parâmetro que define o formato dos KPIs retornados. Aprenda a formatar KPIs Não
aggregation_type Um parâmetro que define o formato dos KPIs retornados. Aprenda a formatar KPIs Sim
per_user Um parâmetro que define o formato dos KPIs retornados. Aprenda a formatar KPIs Não

Selecionando e formatando KPIs

  • A tabela abaixo 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: users, ecpi e cost  
  • Selecione um KPI adicional por chamada.
  • Para cada KPI solicitado, todas as funções são retornadas.  
  • Formato: Strings em array 
    • Exemplo A: "kpis": ["sessions"]
    • Exemplo B: "kpis": ["event_name"]
    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 users S - - - -
Sempre ecpi - - - S -
Sempre cost - - - S -
Opcional "event_name"(4)  S S - S (3) S
Opcional revenue S - - S -
Opcional roas - - S - -
Opcional roi - - S - -
Opcional sessions S - S - S(1)
Opcional uninstalls (2) S - S - -

(1) Sessões únicas retornam quando agregation_type=on_day

(2) Indisponível quando cohort_type=unified  

(3) Soma significa a receita total gerada pelo evento. No relatório, isso é indicado por sum_event_name"

(4) Atenção! Os nomes dos eventos diferenciam maiúsculas de minúsculas

Formatando funções de KPI

Os seguintes parâmetros definem o formato dos KPIs retornados. 

Parâmetro Valores Obrigatório 
preferred_currency Moeda de receita do KPI
  • Quando "true", a receita será retornada usando a moeda específica do aplicativo definida na plataforma.  
  • [Padrão] Quando "false", os resultados serão retornados em USD.
  • Formato: Booleano 
  • Versão da interface da plataforma: true
  Não
preferred_timezone Fuso horário dos intervalos de dados
  • Quando "true", os horários serão exibidos usando o fuso horário específico do aplicativo definido na plataforma.
  • [Padrão] Quando "false", os horários serão exibidos usando o fuso horário UTC.
  • Formato: Booleano 
  • Versão da interface da plataforma: true
  Não
aggregation_type
  • cumulative
  • on_day

"aggregation_type": "cumulative"

Format: String

 Sim
per_user Divida a função KPI pelo número de usuários do aplicativo. Aplica-se apenas a KPIs relevantes.
  • Quando "true", os valores de KPI serão divididos pelo número de usuários na cohort.
  • Quando "false", os valores de KPI não serão divididos pelo número de usuários.
  • Formato: Booleano 
  • Exemplo em caso de "false": a receita total é de US$ 1000, o número de usuários do aplicativo é 500, o valor retornado é de US$ 2.  
  Não

Agrupar por e filtrar dimensões

Nome da dimensão   Valor da API de dimensão Agrupamentos Filtros
Ad af_ad S S
Ad ID af_ad_id S S
Campaign c S S
Campaign ID af_c_id S S
Channel af_channel S S
Media Source pid S S
Sub Param 1 af_sub1 S S
Keywords af_keywords S S
Agency af_prt S S
Conversion Type (1)  cohort_type S S
Site ID site_id S S
Revenue Type (2) revenue_type x  S
Attributed Touch Type (3) attributed_touch_type S S
Adset af_adset S S
Adset ID af_adset_id S S
Country geo S S
Date (data de instalação/reatribuição/reengajamento no contexto do cohort_type selecionado)   date S x 
Period

period

Explicação detalhada

 

 x S

Observações: 

Opções de dimensão:

(1) Tipo de conversão:  user_acquisition, retargeting(re-engagement e re-attribution), unified

  • Ao exportar:
    • re-engagement será exibido como retargeting
    • re-attribution será exibido como reattr

(2) Tipo de receita: regular, ad_monetization

(3) Tipo de toque atribuído: click, impression, TV, pre-installed

Informações adicionais

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, para um usuário que instala em 11 de janeiro, o período é 0. 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 é incluso.  

  • 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

  • Esse exemplo contém os parâmetros de consulta JSON, dados brutos e arquivo CSV resultante.
  • A consulta filtrar o período de 0, 1 e 2 e o KPI selecionado é receita.
  • A consulta especifica o tipo de agregação como "cumulativa". Mude para "on_day" se você quiser acessar os dados do dia.
  • 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": "cumulative",
    "per_user": false,
    "groupings": [
        "pid"
    ],
    "kpis": [
        "revenue"
    ]
}

Dados brutos

mceclip1.png

Resultados

mceclip0.png

Características e limitações

Caraterística Observações 
Acesso da ad network  Não
Acesso da agência Não
Fuso horário específico do aplicativo Sim
Moeda específica da aplicação  Sim
Limitações de tamanho -
Limitação de taxa
  • Limite de taxa de chamadas da API: 60 chamadas por minuto e 50.000 chamadas por dia, por conta
  • As consultas retornam até 30.000 linhas
Dados orgânicos Disponível
Dados não orgânicos Disponível
Limitação de dados de custo
  • Os dados de custo referem-se apenas a campanhas com pelo menos uma instalação registrada.
  • A AppsFlyer não informa dados de custo para palavras-chave que contenham letras maiúsculas no relatório de cohort ou na API de cohort
  • Você não pode mesclar algumas combinações de agrupamentos com custo. Por exemplo, o Meta Ads pode ter agrupamentos por geolocalização ou por canal, mas não ambos. A combinação exata de agrupamentos depende da ad network.
Atualização dos dados A atualização dos dados depende de parcial_data da seguinte forma:  
  • [Padrão] Quando "false", Diariamente
  • Quando "true", Contínuo (tempo real)
  • As métricas de custo e desinstalação são atualizadas diariamente em todas as instâncias
Dados históricos Cohorts diárias: 2 anos
Acesso do usuário à 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 é:
  • Cumulativo.
  • "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.
Período da Cohort API
  • O período de conversão é definido como 0 (Hora 0 ou Dia 0). O próximo período após a conversão é definido como 1 (Hora 1 ou Dia 1) e assim por diante.
  • Na AppsFlyer, um período de cohort não leva em consideração o timestamp de data/hora específico da instalação. Em vez disso, as horas da cohort são arredondadas para a hora mais próxima e os dias da cohort se baseiam no dia do calendário. Isso pode causar discrepâncias na comparação entre os dados de cohort da AppsFlyer e os dados de cohort de outras ad networks, onde todos os períodos de cohort são determinados pelo timestamp de data/hora de instalação específico (ou seja, uma hora equivale a 60 minutos após o timestamp de data/hora da instalação e um dia é o período de 24 horas após a instalação depois do timestamp de data/hora da instalação).  
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.
  • Data mais antiga disponível: 730 a 5 dias antes da data atual. (ou seja, 2 anos).
  • Intervalo máximo de consulta: 60 dias
Reinstalações
  • Se os eventos após reinstalação forem considerados orgânicos não atribuídos:
    • Estão incluídos apenas a partir de 26 de maio de 2024. Saiba mais
    • O tempo de instalação baseia-se no campo device_download_time.
    • Não são contabilizados para medições de usuários únicos e de retenção.
  • Se os eventos após reinstalação forem atribuídos à primeira instalação, são sempre incluídos. Saiba mais
Cohort API para parceiros O acesso à Cohort API por parceiros foi desativado em 15 de setembro de 2024. Recomendamos que os parceiros ativem o Data Locker para garantir o acesso contínuo aos dados dos clientes.