Использование Pull API для агрегированных данных

Краткий обзор. Использование схем URI для получения агрегированных отчетов AppsFlyer в виде файлов CSV.

PullAPIAverage_us-en.png

 Вам нужны сырые данные Pull API?

Сырые данные Pull API

Характеристики агрегированных данных Pull API

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

Пример шаблона URI TemplateURL_us-en.jpg

Категория  UA Ретаргетинг* Protect360
Партнеры (медиаисточник)

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

Ежедневно

Геоданные

Отчеты по геоданным — по датам

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

Сводный отчет об эффективности доступен через Pull API

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

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

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

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

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

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

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

Руководство для пользователей аккаунта

О шаблонах URI

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

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

Прежде чем начать:

Чтобы скачать отчет из хаба разработчиков: 

  1. В AppsFlyer перейдите в справочник API в хабе разработчиков.

    API_Reference.jpg

  2. Выберите тип отчета в меню слева.
    Например, Отчеты по сырым данным (неорганическим) > Установки.
    Список всех типов отчетов приведен в таблице ниже.

  3. Заполните все обязательные поля 
  4. Шаблон URI отображается справа. 
  5. Скопируйте URI, нажав на значок копирования.
  6. Откройте новую вкладку в вашем браузере и вставьте URI.
  7. Нажмите <Enter>, чтобы отправить вызов API. 
    Отчет будет скачан.
Отчет Описание Частота обновления
Отчеты по сырым данным (неорганические)
Установки Регистрирует неорганические установки. Запись создается, когда пользователь впервые открывает приложение.
В реальном времени
Внутренние события приложений Регистрирует события, выполненные пользователями.
В реальном времени
Удаления Регистрирует, когда пользователь удаляет приложение.
Ежедневно
Повторные установки
Регистрирует пользователей, которые после удаления приложения взаимодействуют с медиа-источником UA и повторно устанавливают приложение во время окна реатрибуции. В реальном времени
Отчеты по сырым данным (органические)
Органические установки
Регистрирует момент первого открытия приложения пользователем.
Непрерывно
Органические события внутри приложения
Регистрирует сведения о событиях, совершенных пользователями.
Непрерывно
Органические удаления
Регистрирует пользователей, удаливших приложение.
Ежедневно
Органические повторные установки
Регистрирует доходы от рекламы от пользователей, атрибутированных медиа-источнику ретаргетинга во время окна повторного вовлечения.
Ежедневно
Сырые данные по доходу от рекламы
Атрибутированный доход от рекламы
Регистрирует доходы от рекламы от пользователей, атрибутированных медиа-источнику. Ежедневно
Органический доход от рекламы Регистрирует доходы от рекламы от пользователей, не атрибутированных медиа-источнику. Ежедневно
Защита от мошенничества Protect360
Установки Регистрирует установки, признанные мошенническими и не атрибутированные какому-либо медиа-источнику. В реальном времени
Установки после атрибуции Регистрирует внутренние события, происходящие из мошеннических установок и поэтому не атрибутированные. В реальном времени
Внутренние события приложений Регистрирует внутренние события, признанные мошенническими в Protect360. Ежедневно
Внутренние события после атрибуции Регистрирует внутренние события, происходящие из установок, которые признаны мошенническими после их атрибуции медиа-источнику, или считающиеся мошенническими независимо от установки. Ежедневно
Clicks (Клики) Регистрирует клики от пользователей, заблокированных Protect360. Ежедневно
Постбэки по заблокированным установкам Регистрирует копии постбэков, отправленных в медиа-источник, в результате чего установка была заблокирована. В реальном времени
Постбэки
Постбэки по установкам Регистрирует события установки, возникающие, когда пользователь впервые открывает приложение. Ежедневно
Постбэки внутренних событий приложений. Регистрирует постбэки по внутренним событиям, отправленные в медиа-источник. Ежедневно
Постбэки о внутренних событиях в рамках ретаргетинга Регистрирует внутренние события приложения, выполненные пользователями во время окна повторного вовлечения. В реальном времени
Постбэки по конверсиям ретаргетинга Регистрирует внутренние события приложения, выполненные пользователями во время окна повторного вовлечения. В реальном времени

Параметры агрегированных данных Pull API

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

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

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

  • Например:media_source=facebook
attribution_touch_type

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

Например: attribution_touch_type=impression

currency

Валюта дохода и затрат.

Агрегированные отчеты Pull API всегда используют валюту приложения.

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
Параметр Описание
URI
  • Получить Protect360 URI на дэшборде.
  • Измените схему URI, как описано здесь.
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, как подробно описано в примере.
  • Параметр можно использовать с любым из доступных агрегированных отчетов. Просто скопируйте URI из пользовательского интерфейса и добавьте параметр.
  • Вы также можете добавить параметр &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&attribution_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);
    }
  }
}

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

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

Специфика
Специфика Комментарии 
Необходимый тип токена API AppsFlyerAdmin_us-en.pngТокен V1.0
Доступ рекламной сети N
Доступ агентств Y
Прозрачность агентства Y
Валюта приложения Y
Часовой пояс приложения Y
затраты Данные о затратах доступны только по кампаниям UA и не доступны по ретаргетинговым и неактивным кампаниям (кампаниям без установок).
Актуальность данных Непрерывно
Исторические данные Y
Неорганические данные Y
органические данные Y
Ограничение предоставления данных

Ограничения

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

Внимание! Pull API поддерживает до 1 млн строк сырых данных. Отчеты с агрегированными данными ограничены 200 тыс. строк. 

Изменения названия кампании Отчеты через Pull API не поддерживают изменения названия кампании

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

Коды ошибок и решения
Статус Код Симптом/сообщение Решение
OK 200 Пустой файл CSV
  • additional_fields появляется в URI больше одного раза
  • Убедитесь, что даты начала и окончания имеют формат гггг-мм-дд
OK

200

 

В схеме URI не найден токен API

Bad request

400

Ретроспективный обзор в отчетах по сырым данным ограничен 90 днями.

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

Bad request

400

Вы исчерпали лимит на вызовы API для этого типа отчета

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

401

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

Попросите у администратора действующий токен.
Не авторизовано

401

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

Войдите в систему и проверьте на дэшборде статус аккаунта.

Not found

404

Отображается страница AppsFlyer с ошибкой 404

  • Убедитесь, что идентификатор приложения правильный. Для приложений iOS они должны начинаться с id.
  • Токен не соответствует приложению. Вы используете правильный токен?