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

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

PullAPIAverage_us-en.png

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

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

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

  • Отчеты возвращаются в виде файлов CSV.
  • Показатели актуальности данных такие же, как в аналогичном отчете на странице «Экспорт данных».
  • Фильтр по параметрам такой же, как на странице «Экспорт данных»: медиа-источник, диапазон дат, имя события в приложении. 
  • Дополнительные возможности в Pull API:
    • Возможность фильтрации по каналу атрибуции
    • Возможность выбора часового пояса 
  • Pull API подходит для использования членами команды и разработчиками BI;
    • Члены команды  получают отчеты, вставляя URI в их браузер. Шаблоны URI доступны на панели инструментов. 
    • Разработчики 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 и диапазона дат, которые вам необходимо отредактировать.
  • Часть URI справа от знака вопроса (?) содержит параметры. Каждый параметр начинается с амперсанда (&).  Параметры используются для установки фильтров, указания дополнительных полей, которые необходимо включить, валюты и часового пояса. Например, в агрегированных отчетах для ограничения (фильтрации по) конкретному источнику мультимедиа используйте параметр media_source: &media_source=facebook
  • Чтобы лучше понимать Pull API, выполните следующее задание.

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

Прежде чем начать:
  • Попросите администратора предоставить вам Pull API токен,  доступный в дэшборде.

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

  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.В примерах вызовов отображается как <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);
    }
  }
}

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

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

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

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

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

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

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

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

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

Ограничения на размер Да
  • Вызов 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
  • Токен не соответствует приложению. Вы используете правильный токен?
Была ли эта статья полезной?