Usando dados agregados da Pull API

Visão geral: use URIs para obter seus relatórios agregados da AppsFlyer em arquivos CSV.

PullAPIAverage_us-en.png

  Procurando dados brutos da Pull API?

Dados brutos da Pull API

Características dos dados agregados da Pull API

  • Os relatórios retornam como arquivos CSV.
  • As taxas de atualização dos dados são iguais às do relatório equivalente na página Exportar Dados.
  • Filtrar por opções disponíveis: fonte de mídia e intervalo de datas.
  • Os recursos adicionais da Pull API são:
    • Capacidade de filtrar por tipo de toque de atribuição
    • Fuso horário selecionável 
  • A API Pull é adequada para uso por membros da equipe e desenvolvedores de BI;
    • Membros da equipe obtêm relatórios ao colar URIs em seu navegador. Os templates de URI estão disponíveis no dashboard. Vá para Integração > Acesso à API.
    • Desenvolvedores de BI obtêm relatórios ao incorporar os URIs em scripts. 

Exemplo de template de URI TemplateURL_us-en.jpg

Categoria  UA Retargeting* Protect360
Parceiros (fonte de mídia)

Parceiros por data

Diariamente

Geolocalização

Geolocalização por data

* Para relatórios de redirecionamento, adicione &reattr=true ao URI. 

Relatórios de desempenho agregados disponíveis na Pull API

 Leitura relacionada:

Terminologia

Termo Descrição
Pull API

Solução para baixar relatórios CSV usando URIs.

Chamada de API ou chamada 

Enviando o URI à AppsFlyer colando-o na barra de endereços do navegador ou usando scripts.

URI
  • Identificador de recurso uniforme às vezes semelhante a um endereço da Web (URL) que contém a especificação do relatório.
  • Templates de URI estão disponíveis na página da API no Painel.

Guia para membros da equipe

Sobre templates de URI

  • Os templates de URI disponíveis no painel são preenchidos com a ID do aplicativo e o tipo de relatório.
  • Eles possuem espaços reservados (placeholders) para o token da API V1.0 e para datas de/até (from/to) que você deve editar.
  • A parte do URI à direita do ponto de interrogação (?) contém parâmetros. Cada parâmetro começa com um "e" comercial ((&). Os parâmetros são usados para definir filtros, especificar campos adicionais a serem incluídos, moeda e fuso horário. Por exemplo, em relatórios agregados para limitar (filtrar por) uma fonte de mídia específica, use o parâmetro media_source: &media_source=facebook
  • Para entender melhor a Pull API, termine o tutorial a seguir.

Como obter seu primeiro tutorial de relatório da Pull API

Antes de começar:
  •  Peça ao administrador para que ele ofereça o token V1.0.

Para fazer o download de um relatório do painel: 

  1. Vá para Integração > Acesso à API.
    A página de acesso à API é aberta. PullAPIPartnersReport_us-en.jpg
  2. Selecione um tipo de relatório. Por exemplo, Relatórios de desempenhoRelatório diário de parceiros. 
    O template de URI é exibido. 
  3. Copie o URI clicando nele.
  4. Abra uma nova guia no seu navegador e cole o URI.
  5. Edite o URI:
    1. Substitua o placeholder do token pelo token da Pull API fornecido pelo administrador.
      Exemplo: substitua o placeholder do token de modo que &api_token=12345678-1234-1234-1234-123456789012 Atenção! Não há espaços ou qualquer outra pontuação. 
    2. Substitua os placeholders from/to por datas.
      Exemplo: &from=2020-01-20&to=2020-01-31 Atenção! Não há espaços. Não exclua o &. 
  6. Clique em <Enter> para enviar a chamada da API. 
    O relatório é baixado.
    Parâmetros adicionais podem ser definidos para personalizar relatórios, por exemplo, selecionar uma fonte de mídia específica, retornar dados de retargeting etc. A seção a seguir contém a lista de parâmetros disponíveis. 

Parâmetros dos dados agregados da Pull API

URI e parâmetros do relatório agregado

Parâmetros obrigatórios do URI agregado 
Parâmetro Descrição
api_token V1.0 API token. Nas chamadas de exemplo, isso é mostrado como <API TOKEN HERE>. 
from (a partir de)
  • O intervalo de datas consiste em um parâmetro fromto. O intervalo é o período de LTV (instalação).
  • Formato: yyyy-mm-dd, 
  • Exemplo: 2010-01-01-2010 ou 2010-01-01
to (até) Data final. Quanto a from
Filtragem opcional de dados agregados e parâmetros de exibição, excluindo relatórios Protect360
Parâmetro Descrição
media_source

Use para limitar (filtrar) uma fonte de mídia específica.

  • Exemplo:media_source=facebook
attribution_touch_type

Defina este parâmetro como mostrado no exemplo para obter KPIs de atribuição de visualização (VTA). 

Exemplo: attribution_touch_type=impression

currency

Moeda de receita e custo.

Relatórios agregados de Pull API sempre usam a moeda específica do aplicativo. 

reattr

Obtenha dados de conversões de retargeting.

  • [Padrão] Se falso, as campanhas de dados de aquisição de usuários (UA) serão retornadas.
  • Se verdadeiro, a conversão de retargeting irá retornar.
  • Exemplo:reattr=true
Fuso horário

[Padrão] Os dados retornam usando UTC.

  • Os templates de URIs são preenchidos com o parâmetro de fuso horário definido para o fuso horário específico do aplicativo. 
  • [Padrão] Se o parâmetro não for enviado, os dados retornarão usando UTC.
  • Se você enviar timezone=[Joda-Time], os dados retornarão usando o fuso horário específico do aplicativo.

Observações sobre a seleção de fusos horários

  • O formato de fuso horário Joda-Time considera o horário de verão.
  • O valor de Joda-Time deve ser idêntico ao valor definido na página de definições do aplicativo. Por exemplo, se o fuso horário definido é o de Paris, o valor do fuso horário na URL da Pull API deve ser timezone=Europe%2fParis.
  • Extrair dados no fuso horário selecionado está disponível somente a partir da data em que a configuração do fuso horário foi feita. Qualquer dado anterior à data da mudança usa UTC como fuso horário. 

Relatório filtrado do Google Ads

https://hq.appsflyer.com/export/com.greatapp/partners_report/v5?api_token=xxxx
&from=2018-04-09&to=2018-05-09&media_source=googleadwords_int

Relatório filtrado do Facebook

https://hq.appsflyer.com/export/com.greatapp/partners_report/v5?api_token=xxxx
&from=2018-04-09&to=2018-05-09&media_source=facebook
Parâmetros opcionais para relatórios do Protect360
Parâmetro Descrição
URI
  • Obtenha a URI do Protect360 no painel.
  • Modifique a URI conforme descrito aqui. 
PID

Para filtrar o relatório por uma fonte de mídia específica, use o parâmetro  pid. Por exemplo, para obter os dados de abc_net,  pid=abc_net.

Fuso horário

Seleciona o fuso horário usado para retornar dados.

Se timezone não for enviado, os dados serão retornados usando UTC.

Templates incluindo o parâmetro timezone

Exemplo: timezone=preferred: use para obter dados usando o fuso horário específico do aplicativo.

KPIs

Os parâmetros Protect360 são os mesmos na Pull API e na Master API.

KPIs de atribuição de exibição (VTA)

  • Para obter os KPIs do VTA, adicione o parâmetro attribution_touch_type=impression ao URI do relatório agregado da Pull API, conforme detalhado no exemplo.
  • Você pode usar o parâmetro com qualquer um dos relatórios agregados disponíveis. Basta copiar a URI da interface do usuário e anexar o parâmetro.
  • Você também pode adicionar o parâmetro &media_source para limitar o relatório a uma fonte de mídia específica, conforme ilustrado no exemplo a seguir.
  • Alguns KPIs de VTA, como cliques, impressões e APIs de custo, não têm valores associados a eles e exibem o valor N/A. 
Exemplo Exemplo de URI
Somente VTA  https://hq.appsflyer.com/export/{app_id}/partners_report/v5?api_token={API token}&from=yyyy-mm-dd&to=yyyy-mm-dd&attribution_touch_type=impression

VTA e fonte de mídia

https://hq.appsflyer.com/export/{app_id}/partners_report/v5?api_token={API token}&from=yyyy-mm-dd&to=yyyy-mm-dd&attribution_touch_type=impression&media_source=example_ad_network

Pull API para desenvolvedores

Princípios de implementação

Pré-requisito:

Familiarize-se com o guia da Pull API para membros da equipe.

Considere:

  • Para cada tipo de relatório disponível, há um template de URI no dashboard. Vá para Integração > Acesso à API.
  • Modifique o template para obter os dados necessários. Por exemplo, definindo períodos e filtrando por parâmetros.
  • Os parâmetros para dados brutos e relatórios de dados agregados diferem e são detalhados nas seções do relatório.
Noções básicas da Pull API
Path

https://hq.appsflyer.com/export/app_id/report_type/v5

Parâmetros do path

app_id

  • Identificador de aplicativo como encontrado na AppsFlyer.
  • Insira a ID do aplicativo exatamente como encontrado na AppsFlyer.
  • Prefixe aplicativos iOS com id

report_type 

  • Define o tipo de relatório. A lista de relatórios e os URIs associados estão no painel. Vá para Integração > Acesso à API. 
Método HTTP

GET

Parâmetros de consulta obrigatórios
Parâmetro Descrição
Exemplo de URI

GET 'https://hq.appsflyer.com/export/app_id/installs_report/v5? from=2020-01-01?&to=2020-01-10&api_token=api_token&currency=preferred

api_token

api_token: token da Pull API para autenticação

  • Obtenha o token da API no Painel
  • Se você alterar o administrador da conta, o token será alterado e você deverá atualizar os scripts com o novo token.
  • api_token=
Outros parâmetros

Os parâmetros diferem dependendo 

 Exemplo

O exemplo de chamada de URI inclui parâmetros adicionais: 

https://hq.appsflyer.com/export/example.app.com/installs_report/v5?
        api_token={Account owner API key should be used}&from=yyyy-mm-dd
&to=yyyy-mm-dd&additional_fields=keyword_id,store_reinstall,
deeplink_url,oaid,install_app_store,contributor1_match_type,
contributor2_match_type,contributor3_match_type,match_type

Scripts de exemplo

Integre a Pull API nos scripts para recuperar dados.

  • Conforme necessário, edite os scripts em termos de tipo de relatório, período e filtros. 
  • Estes exemplos usam o relatório instalar.
JavaNode JSPythonC#PHP
import okhttp3.*;

import java.io.BufferedWriter;
import java.io.FileWriter;

import java.util.concurrent.TimeUnit;

public class PullApi {
  public static void main(String[] args){

    String appID = "<APP_ID>";
    String reportType = "<REPORT_TYPE>";
    String apiToken = "<API_TOKEN>";
    String from = "<FROM_DATE>";
    String to = "<TO_DATE>";
    String requestUrl = "https://hq.appsflyer.com/export/" + appID + "/" + reportType + "/v5?api_token=" + apiToken + "&from=" + from + "&to=" + to;

    OkHttpClient client = new OkHttpClient.Builder()
        .connectTimeout(30, TimeUnit.SECONDS)
        .readTimeout(30, TimeUnit.SECONDS)

        .build();

    Request request = new Request.Builder()
        .url(requestUrl)
        .addHeader("Accept", "text/csv")
        .build();

    try {
      Response response = client.newCall(request).execute();

      if(response.code() != 200) {
        if(response.code() == 404) {
          System.out.println("There is a problem with the request URL. Please make sure it is correct");
        }
        else {
          assert response.body() != null;
          System.out.println("There was a problem retrieving the data: " + response.body().string());
        }
      } else {
        assert response.body() != null;
        String data = response.body().string();
        BufferedWriter writer;

        writer = new BufferedWriter(new FileWriter(appID + "-" + reportType + "-" + from + "-to-" + to + ".csv"));
        writer.write("");
        writer.write(data);
        writer.close();
      }
      System.exit(0);
    } catch (Exception e) {
      e.printStackTrace();
      System.exit(1);
    }
  }
}

Informações adicionais

Diferenças entre a Pull API V4 e V5. 

Dados brutos: API V4 ainda está disponível para uso. Nenhuma alteração é feita nos formatos e nos cabeçalhos dos arquivos.

Dados agregados (V5):

Na V5.0, os seguintes campos adicionais são fornecidos quando media_source=facebook:

  • ID da campanha
  • Nome do conjunto de anúncios
  • ID do conjunto de anúncios
  • Nome do anúncio (grupo de anúncios)
  • ID do anúncio (grupo de anúncios)

Características e limitações

Característica
Característica Comentários 
Tipo de token de API necessário AppsFlyerAdmin_us-en.pngV1.0 token
Acesso da ad network N
Acesso das agências S
Transparência da agência S
Moeda específica do aplicativo S
Fuso horário específico do aplicativo S
Atualização de dados tempo real
Dados históricos S
Dados não orgânicos S
Dados orgânicos S
Limitações de taxa

Limitação

Limitações de tamanho
  • As chamadas de API retornam no máximo 200 mil linhas.
  • Se um relatório tiver exatamente 200 mil linhas, assuma que estão faltando linhas.
  • Faça múltiplas chamadas de API usando os parâmetros from/to que incluem a hora do dia.  
Alterações de nome da campanha Os relatórios de Pull API não são compatíveis com alterações no nome da campanha

Erro da API e solução de problemas

Códigos e soluções de erro
Status Código Sintoma/mensagem solução
OK 200 Arquivo CSV vazio
  • addtional_fieldsaparece mais de uma vez no URI
  • Certifique-se de que as datas de e para tenham o formato aaaa-mm-dd
OK

200

 

Nenhum token de API encontrado na URI

Erro na solicitação

400

O histórico de lookback dos relatórios de dados brutos é limitado a 90 dias

Use to e from para limitar o período a 3 meses ou menos.

Erro na solicitação

400

Seu limite de chamadas de API foi atingido para o tipo de relatório fornecido

-
Não autorizado

401

O token da API fornecido é inválido 

Peça o token atualizado ao administrador.
Não autorizado

401

A conta pode ser suspensa

Faça login no painel e verifique o status da conta. 

Não encontrado

404

A página com a mensagem de erro 404 da AppsFlyer é exibida

  • Certifique-se de que o ID do aplicativo está correto. Os aplicativos iOS devem começar com id.
  • O token não corresponde ao aplicativo. Você está usando o token correto? 
Este artigo foi útil?