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

  • Отчеты возвращаются в виде файлов CSV.
  • Показатели актуальности данных такие же, как в аналогичном отчете на странице «Экспорт данных».
  • Фильтр по параметрам такой же, как на странице «Экспорт данных»: медиа-источник, диапазон дат, имя события в приложении. 
  • Дополнительные возможности в Pull API:
    • Возможность фильтрации по атрибутированному типу касания
    • Возможность выбора часового пояса 
  • Pull API подходит для использования членами команды и разработчиками BI;
    • Члены команды  получают отчеты, вставляя URI в их браузер. Шаблоны URI доступны на панели инструментов. 
    • Разработчики BI получают отчеты, встраивая URI в сценарии.

Example URI template TemplateURL_us-en.jpg

Категория Сводные отчеты (об эффективности) и ретаргетинг* Protect360**
Партнеры (медиаисточник)

Партнеры — по датам

Ежедневно

Геоданные

Геоданные — по датам 

* Для отчетов по ретаргетингу добавьте в URI атрибут &reattr=true

** Функция Премиум. 

Aggregate reports, LTV based

Связанные сведения:

Терминология

Термин Описание
Pull API

Решение для загрузки отчетов CSV с использованием URI.

Вызов API или вызов 

Отправьте URI в AppsFlyer, вставив его в адресную строку браузера или используя сценарии.

URI
  • Унифицированный идентификатор ресурса иногда похож на веб-адрес (URL), содержащий спецификацию отчета.
  • Шаблоны URI доступны на странице API в дэшборде.

Руководство для членов команды

О шаблонах URI

  • Шаблоны URI, доступные на дэшборде, заполняются идентификатором приложения и типом отчета.
  • У них есть заполнители для токена API и диапазона дат, которые вам необходимо отредактировать.
  • Часть URI справа от знака вопроса (?) содержит параметры. Каждый параметр начинается с амперсанда (&).  Параметры используются для установки фильтров, указания дополнительных полей, которые необходимо включить, валюты и часового пояса. Например, в сводных отчетах для ограничения (фильтрации по) конкретному источнику мультимедиа используйте параметр media_source: &media_source=facebook
  • Чтобы лучше понимать Pull API, выполните следующее задание.

Ваш первый отчет с Pull API

Прежде чем начать:
  •  Ask the admin to provide you with the Pull API token available in the dashboard.

Чтобы скачать отчет с дэшборда: 

  1. Выберите в разделе Integration (Интеграция) пункт API Access (Доступ к API).Откроется окно доступа к API. PullAPIPartnersReport_us-en.jpg
  2. Выберите тип отчета. Например, Отчеты об эффективности>Ежедневный отчет партнеров.
    Отображается шаблон URI.
  3. Скопируйте URI, нажав на него.
  4. Откройте новую вкладку в вашем браузере, вставьте URI.
  5. Отредактируйте 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. Замените маркеры-заполнители from/to на даты.
      Пример: &from=2020-01-20&to=2020-01-31 Внимание! Там нет пробелов. Не удаляйте &. 
  6. Нажмите <Enter>, чтобы отправить вызов API. 
    Отчет будет скачан.

Aggregate data Pull API parameters

URI и параметры агрегированного отчета

Обязательные параметры URI агрегированного отчета.
Параметр Описание
api_token Токен авторизации API.В примерах вызовов отображается как <API TOKEN HERE>. 
from
  • Диапазон дат задается параметрами fromи to . Под диапазоном понимается диапазон дат LTV (установки).
  • Формат: yyyy-mm-dd, 
  • Пример: 2010-01-01 или 2010-01-01
to Дата окончания. Так же, как и параметр from
Необязательные параметры фильтрации и отображения сводных данных, кроме отчетов Protect360.
Параметр Описание
media_source

Используйте для ограничения (фильтрации) по определенному медиа-источнику.

  • Example:media_source=facebook
 attributed_touch_type

Установите этот параметр, как показано в примере, чтобы получить ключевые показатели эффективности атрибуции (VTA). 

Example: attribution_touch_type=impression

currency

Валюта выручки и стоимость

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

reattr

Получить данные по атрибуции ретаргетинга.

  • [По умолчанию] Если установлено значение false, возвращаются кампании с данными о пользователях (UA).
  • Если установлено значение true, возвращаются данные по атрибуции ретаргетинга.
  • Пример:reattr=true
Time Zone (Часовой пояс)

[По умолчанию] Данные предоставляются по часовому поясу UTC.

  • Шаблоны URI заполняются с помощью параметра часового пояса, установленного для часового пояса приложения. 
  • [По умолчанию] Если параметр не передан, данные предоставляются по часовому поясу UTC.
  • Если вы отправляете timezone=[Joda-Time], данные предоставляются с использованием часового пояса приложения.

Примечания о выборе часового пояса

  • Формат часового пояса Joda-Time учитывает переход на летнее время.
  • Значение Joda-Time должно совпадать со значением в настройках приложения. Например, если установлен часовой пояс Парижа, значение часового пояса в Pull API URL должно быть таким:  timezone=Europe%2fParis.
  • Данные в выбранном часовом поясе доступны для извлечения только с даты установки этого часового пояса. Данные, предшествующие дате изменения, отображаются в часовом поясе UTC. 

Отфильтрованный отчет 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

Отфильтрованный отчет 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
Необязательные параметры для отчетов Protect360
Параметр Описание
 pid

Чтобы отфильтровать отчет по определенному медиа-источнику, используйте параметр pid. Например, чтобы получить данные abc_net, используйте pid=abc_net.

Time Zone (Часовой пояс)

Выбирает часовой пояс, используемый для возврата данных.

Если параметр timezone не передан, данные предоставляются по часовому поясу UTC.

Шаблоны, включающие параметр timezone .

Пример: timezone=preferred: Используйте этот параметр, чтобы получить данные с использованием часового пояса конкретного приложения.

KPI.

Параметры Protect360 в Pull API и Master API одинаковы. 

Ключевые показатели атрибуции по просмотрам (VTA)

  • Чтобы получить ключевые показатели эффективности VTA, добавьте параметр attribution_touch_type=impression в URI сводного отчета Pull API, как подробно описано в примере.
  • 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
  • Вы также можете добавить параметр &media_source, чтобы ограничить отчет конкретным медиа-источником, как показано в следующем примере.
  • Некоторые ключевые показатели эффективности VTA, такие как клики, показы и API затрат, не имеют связанных значений и отображают значение N/A. 
Пример Пример URI
Только 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 и медиа-источник

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 для разработчиков

Принципы реализации

Необходимые условия:

Ознакомьтесь с руководством по Pull API для членов команд.

Рассмотрим:

  • Для каждого доступного типа отчетов в дэшборде есть URI шаблона.
  • Вы модифицируете шаблон, чтобы получить необходимые данные. Например, путем установки диапазонов дат и фильтрации по параметрам.
  • Параметры для необработанных данных и отчетов о совокупных данных различаются и подробно описаны в разделах отчета.
Основы Pull API
Маршрут

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

Параметры пути

app_id

  • Идентификатор приложения, указанный в AppsFlyer.
  • Вставьте идентификатор приложения точно как он указан в AppsFlyer.
  • Для приложений iOS необходим префикс id

report_type 

  • Определяет тип отчета. Список отчетов и связанных с ними URI находятся на дэшборде. Выберите в разделе Integration (Интеграция) пункт API access (Доступ к API). 
HTTP-метод

GET

Обязательные параметры запроса
Параметр Описание
Пример 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: токен Pull API для аутентификации

  • Получите токен API на дэшборде
  • Если вы меняете администратора аккаунта, токен тоже изменится, и вам нужно будет добавить в скрипты новый токен. 
  • api_token
Другие параметры

Параметры различаются в зависимости 

 Пример

Пример вызова URI включает дополнительные параметры: 

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

Примеры сценариев

Интегрируйте Pull API в скрипты для извлечения данных.

  • По мере необходимости настройте в скриптах типы отчетов, диапазон данных и фильтры. 
  • Эти примеры используют отчет об установке.
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);
    }
  }
}

Дополнительные сведения

Различия между Pull API V4 и V5. 

Необработанные данные: API V4 до сих пор доступен для использования. Форматы файлов и заголовки не менялись.

Сводные данные (V5):

В V5.0 предоставляются следующие дополнительные поля, для media_source=facebook:

  • ID кампании
  • Название блока рекламы
  • ID блока рекламы
  • Название (группы) объявления
  • Идентификатор (группы) объявления

Ограничения и особенности

Специфика
Специфика Статус Комментарии 
Доступ рекламной сети   
Доступ агентств  
Прозрачность агентства  
Валюта приложения  
Часовой пояс приложения  
Актуальность данных реальном времени  
Исторические данные  
Неорганические данные  
органические данные  
Ограничение предоставления данных

Ограничения API для сводных данных и необработанных данных

Ограничения на размер Да
  • Вызов API возвращает максимум 200 тысяч строк.
  • Если в отчете ровно 200 тысяч строк, стоит предположить, что какие-то строки отсутствуют.
  • Сделайте несколько API-вызовов, используя параметры from/to с указанием времени.  
Доступ члена команды

Только администратор может получить для вас токен Pull API.

Коды ошибок API и устранение неисправностей

Коды ошибок и решения
Статус Код Symtom/message Решение
OK 200 Пустой файл CSV

additional_fields появляется в URI больше одного раза

OK

200

Пустой файл CSV

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.

Используйте to и from, чтобы ограничить диапазон данных 3 месяцами или меньше.

Bad request

400

Your API calls limit has been reached for report type

-
Не авторизовано

401

Указанный токен API недействителен 

Ask the admin for the current token
Не авторизовано

401

Аккаунт может быть заморожен.

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. 

Была ли эта статья полезной?

Статьи в этом разделе