Использование 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

Прежде чем начать:
  •  Попросите у администратора токен V1.0.

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

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

Параметры агрегированных данных 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 шаблона. Выберите в разделе Интеграция пункт Доступ к API.
  • Модифицируйте шаблон, чтобы получить необходимые данные, например, задав диапазоны дат и фильтры по параметрам.
  • Параметры для сырых данных и отчетов об агрегированных данных различаются и подробно описаны в разделах отчета.
Основы 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
Актуальность данных Непрерывно
Исторические данные Y
Неорганические данные Y
органические данные Y
Ограничение предоставления данных

Ограничения

Ограничения на размер
  • Вызов API возвращает максимум 200 тысяч строк.
  • Если в отчете ровно 200 тысяч строк, стоит предположить, что какие-то строки отсутствуют.
  • Сделайте несколько API-вызовов, используя параметры from/to с указанием времени.  
Изменения названия кампании Отчеты через 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.
  • Токен не соответствует приложению. Вы используете правильный токен?
Была ли эта статья полезной?