Usando dados agregados da Pull API

Visão geral: use URIs para obter relatórios agregados 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.
  • O filtro por opções é o mesmo da página Exportar Dados, sendo: fonte de mídia, período, nome do evento in-app. 
  • 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 painel. 
    • 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 e para datas (from/to) que você precisa 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:

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 Token de autorização da API.No exemplo, chamar 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 painel.
  • 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 Status Comentários 
Acesso à ad network   
Acesso das agências  
Transparência da agência  
Moeda específica do aplicativo  
Fuso horário específico do aplicativo  
Atualização de dados tempo real  
Dados históricos  
Dados não orgânicos  
Dados orgânicos  
Limitação de taxa

Limitações da API para dados agregados e dados brutos

Limitações de tamanho Sim
  • 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.  
Acesso de membro da equipe

Somente o administrador pode obter um token da Pull API.

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 registro de lookback dos relatórios 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 da API foi atingido para o tipo de relatório

-
Não autorizado

401

O token da API fornecido é inválido 

Peça ao administrador o token atualizado
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 a ID do aplicativo está correta. 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?

Artigos nessa seção