Aggregate data via Pull API in real-time

At a glance: Use URIs to get aggregate reports in CSV files.

PullAPIAggregateDate_us-en.jpg

 Are you looking for Pull API raw data?

Pull API raw data

Pull API aggregate data characteristics

  • 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 atribuído
    • 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. 

Example URI template TemplateURL_us-en.jpg

Categoria UA agregado (desempenho) e 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. 

** Recurso premium. 

Aggregate reports, LTV based

 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:
  •  Ask the admin to provide you with the Pull API token available in the dashboard.

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. Replace the token placeholder with the Pull API token provided by the admin.
      Example: Replace the token placeholder so that &api_token=12345678-1234-1234-1234-123456789012 Note! There are no spaces or other punctuation. 
    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.

Aggregate data Pull API parameters

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.

  • Example:media_source=facebook
 attributed_touch_type

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

Example: attribution_touch_type=impression

currency

Moeda de receita e custo

Aggregate Pull API reports always use the app-specific currency. 

reattr

Obter retargeting de dados de atribuição.

  • [Padrão] Se falso, as campanhas de dados de aquisição de usuários (UA) serão retornadas.
  • Se verdadeiro, o redirecionamento dos dados de atribuição será retornado.
  • 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
 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.
  • You can use the parameter with any of the aggregate reports available. Just copy the URI from the user interface, and append the &attributed_touch_type=impression
  • 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&aattribution_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 Symtom/message solução
OK 200 Arquivo CSV vazio

addtional_fieldsaparece mais de uma vez no URI

OK

200

Arquivo CSV vazio

Ensure that both from and to dates have the format yyyy-mm-dd

Bad request

400

Raw Reports historical lookback is limited to 90 days.

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

Bad request

400

Your API calls limit has been reached for report type

-
Não autorizado

401

O token da API fornecido é inválido 

Ask the admin for the current token
Não autorizado

401

A conta pode ser suspensa.

Log in to the dashboard and check the account status. 

Not found

404

 

The token doesn't match the app. Ask the admin to give you the current token. 

Este artigo foi útil?