Краткий обзор. Использование схем URI для получения агрегированных отчетов AppsFlyer в виде файлов CSV.
Вам нужны сырые данные Pull API?
Характеристики агрегированных данных Pull API
- Отчеты возвращаются в виде файлов CSV.
- Показатели актуальности данных такие же, как в аналогичном отчете на странице «Экспорт данных» и на обзорном дэшборде. Обратите внимание, что затраты могут обновляться с задержкой в несколько часов, и это зависит от партнера, предоставляющего данные о затратах.
- Доступна фильтрация по медиа-источнику и диапазону дат.
- Дополнительные возможности в Pull API:
- Возможность фильтрации по каналу атрибуции
- Возможность выбора часового пояса
- Pull API подходит для применения пользователями аккаунта и разработчиками BI;
- Пользователи аккаунта получают отчеты, указывая в браузере URI. Шаблоны URI доступны на дэшборде. Выберите в разделе Интеграция пункт Доступ к API.
- Разработчики BI получают отчеты, встраивая URI в сценарии.
Сводный отчет об эффективности доступен через Pull API
Категория | UA | Ретаргетинг* | Protect360 |
---|---|---|---|
Партнеры (медиаисточник) | ✓ | ✓ | ✓ |
Партнеры — по датам |
✓ | ✓ | ✓ |
Ежедневно |
✓ | ✓ | ✓ |
Геоданные |
✓ | ✓ | ✓ |
Отчеты по геоданным — по датам |
✓ | ✓ | ✓ |
* Для отчетов по ретаргетингу добавьте в URI атрибут |
Связанные сведения:
- Описания и примеры агрегированных отчетов
- Выбор подходящего инструмента доставки данных для агрегированных данных
Терминология
Термин | Описание |
---|---|
Pull API |
Решение для загрузки отчетов CSV с использованием URI. |
Вызов API или вызов |
Отправьте URI в AppsFlyer, вставив его в адресную строку браузера или используя сценарии. |
URI |
|
Руководство для пользователей аккаунта
О шаблонах URI
- В шаблонах URI, доступных в хабе разработчиков, надо указать идентификатор приложения и тип отчета.
- Они содержат заполнители для диапазона дат, которые вам необходимо отредактировать.
- Часть URI справа от знака вопроса (?) содержит параметры. Каждый параметр начинается с амперсанда (&). Параметры используются для установки фильтров, указания дополнительных полей, которые необходимо включить, валюты и часового пояса. Например, в агрегированных отчетах для ограничения (фильтрации по) конкретному источнику мультимедиа используйте параметр media_source:
&media_source=facebook
- Чтобы лучше понимать Pull API, выполните следующее задание.
Ваш первый отчет с Pull API
Прежде чем начать:- Попросите у админа токен Pull API.
Чтобы скачать отчет из хаба разработчиков:
-
В AppsFlyer перейдите в справочник API в хабе разработчиков.
-
Выберите тип отчета в меню слева.
Например, Отчеты по сырым данным (неорганическим) > Установки.
Список всех типов отчетов приведен в таблице ниже. - Заполните все обязательные поля
- Шаблон URI отображается справа.
- Скопируйте URI, нажав на значок копирования.
- Откройте новую вкладку в вашем браузере и вставьте URI.
- Нажмите <Enter>, чтобы отправить вызов API.
Отчет будет скачан.
Отчет | Описание | Частота обновления |
---|---|---|
Отчеты по сырым данным (неорганические) | ||
Установки | Регистрирует неорганические установки. Запись создается, когда пользователь впервые открывает приложение. |
В реальном времени |
Внутренние события приложений | Регистрирует события, выполненные пользователями. |
В реальном времени |
Удаления | Регистрирует, когда пользователь удаляет приложение. |
Ежедневно |
Повторные установки |
Регистрирует пользователей, которые после удаления приложения взаимодействуют с медиа-источником UA и повторно устанавливают приложение во время окна реатрибуции. | В реальном времени |
Отчеты по сырым данным (органические) |
||
Органические установки |
Регистрирует момент первого открытия приложения пользователем. |
Непрерывно |
Органические события внутри приложения |
Регистрирует сведения о событиях, совершенных пользователями. |
Непрерывно |
Органические удаления |
Регистрирует пользователей, удаливших приложение. |
Ежедневно |
Органические повторные установки |
Регистрирует доходы от рекламы от пользователей, атрибутированных медиа-источнику ретаргетинга во время окна повторного вовлечения. |
Ежедневно |
Сырые данные по доходу от рекламы |
||
Атрибутированный доход от рекламы |
Регистрирует доходы от рекламы от пользователей, атрибутированных медиа-источнику. | Ежедневно |
Органический доход от рекламы | Регистрирует доходы от рекламы от пользователей, не атрибутированных медиа-источнику. | Ежедневно |
Защита от мошенничества Protect360 | ||
Установки | Регистрирует установки, признанные мошенническими и не атрибутированные какому-либо медиа-источнику. | В реальном времени |
Установки после атрибуции | Регистрирует внутренние события, происходящие из мошеннических установок и поэтому не атрибутированные. | В реальном времени |
Внутренние события приложений | Регистрирует внутренние события, признанные мошенническими в Protect360. | Ежедневно |
Внутренние события после атрибуции | Регистрирует внутренние события, происходящие из установок, которые признаны мошенническими после их атрибуции медиа-источнику, или считающиеся мошенническими независимо от установки. | Ежедневно |
Clicks (Клики) | Регистрирует клики от пользователей, заблокированных Protect360. | Ежедневно |
Постбэки по заблокированным установкам | Регистрирует копии постбэков, отправленных в медиа-источник, в результате чего установка была заблокирована. | В реальном времени |
Постбэки | ||
Постбэки по установкам | Регистрирует события установки, возникающие, когда пользователь впервые открывает приложение. | Ежедневно |
Постбэки внутренних событий приложений. | Регистрирует постбэки по внутренним событиям, отправленные в медиа-источник. | Ежедневно |
Постбэки о внутренних событиях в рамках ретаргетинга | Регистрирует внутренние события приложения, выполненные пользователями во время окна повторного вовлечения. | В реальном времени |
Постбэки по конверсиям ретаргетинга | Регистрирует внутренние события приложения, выполненные пользователями во время окна повторного вовлечения. | В реальном времени |
Параметры агрегированных данных Pull API
URI и параметры агрегированного отчета
Обязательные параметры URI агрегированного отчета
Параметр | Описание |
---|---|
api_token | Токен авторизации предъявителя API. |
from |
|
to |
Дата окончания. Так же, как и параметр from
|
Необязательные параметры фильтрации и отображения агрегированных данных, кроме отчетов Protect360.
Параметр | Описание |
---|---|
media_source |
Используйте для ограничения (фильтрации) по определенному медиа-источнику.
|
attribution_touch_type |
Установите этот параметр, как показано в примере, чтобы получить ключевые показатели эффективности атрибуции (VTA). Например: |
currency |
Валюта дохода и затрат. Агрегированные отчеты Pull API всегда используют валюту приложения. |
reattr |
Получить данные по конверсии ретаргетинга.
|
Time Zone (Часовой пояс) |
[По умолчанию] Данные предоставляются по часовому поясу UTC.
Примечания о выборе часового пояса
|
Отфильтрованный отчет Google Ads
https://hq.appsflyer.com/export/com.greatapp/partners_report/v5?
from=2018-04-09&to=2018-05-09&media_source=googleadwords_int
Отфильтрованный отчет Facebook
https://hq.appsflyer.com/export/com.greatapp/partners_report/v5?
from=2018-04-09&to=2018-05-09&media_source=facebook
Параметр | Описание |
---|---|
URI |
|
pid |
Чтобы отфильтровать отчет по определенному медиа-источнику, используйте параметр |
Time Zone (Часовой пояс) |
Выбирает часовой пояс, используемый для возврата данных. Если параметр timezone не передан, данные предоставляются по часовому поясу UTC. Шаблоны, включающие параметр timezone . Пример: |
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?from=yyyy-mm-dd&to=yyyy-mm-dd&attribution_touch_type=impression |
VTA и медиа-источник |
https://hq.appsflyer.com/export/{app_id}/partners_report/v5?from=yyyy-mm-dd&to=yyyy-mm-dd&attribution_touch_type=impression&media_source=example_ad_network |
Pull API для разработчиков
Принципы реализации
Необходимые условия:
Ознакомьтесь с руководством по Pull API для пользователей аккаунта.
Рассмотрим:
- Для каждого доступного типа отчетов в хабе разработчиков есть URI шаблона. Выберите тип отчета в меню слева.
- Модифицируйте шаблон, чтобы получить необходимые данные, например, задав диапазоны дат и фильтры по параметрам.
- Параметры для сырых данных и отчетов об агрегированных данных различаются и подробно описаны в разделах отчета.
Маршрут |
|
Параметры пути |
|
HTTP-метод |
|
Параметр | Описание |
---|---|
Пример URI |
|
api_token |
|
Другие параметры |
Параметры различаются в зависимости |
Пример
Пример вызова URI включает дополнительные параметры:
https://hq.appsflyer.com/export/example.app.com/installs_report/v5?
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 в скрипты для извлечения данных.
- По мере необходимости настройте в скриптах типы отчетов, диапазон данных и фильтры.
- Эти примеры используют отчет об установке.
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 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);
}
}
}
request = require('request');
const fs = require('fs');
const appID = '<APP_ID>';
const reportType = '<REPORT_TYPE>';
const from = '<FROM_DATA>';
const to = '<T0_DATE>';
const requestUrl = `https://hq.appsflyer.com/export/${appID}/${reportType}/v5?api_token=${apiToken}&from=${from}&to=${to}`;
request(requestUrl, (error, response, body) => {
if (error) {
console.log('There was a problem retrieving data:', error);
}
else if (response.statusCode != 200) {
if (response.statusCode === 404) {
console.log('There is a problem with the request URL. Make sure that it is correct');
} else {
console.log('There was a problem retrieving data:', response.body);
}
} else {
fs.writeFile(`${appID}-${reportType}-${from}-to-${to}.csv`, response.body, (err) => {
if (err) {
console.log('There was a problem writing to file: ', err);
} else {
console.log('File was saved');
}
});
}
});
import requests
app_id = '<APP_ID>'
report_type = '<REPORT_TYPE>'
params = {
'from': 'FROM_DATE',
'to': 'TO_DATE'
}
request_url = 'https://hq.appsflyer.com/export/{}/{}/v5'.format(app_id, report_type)
res = requests.request('GET', request_url, params=params)
if res.status_code != 200:
if res.status_code == 404:
print('There is a problem with the request URL. Make sure that it is correct')
else:
print('There was a problem retrieving data: ', res.text)
else:
f = open('{}-{}-{}-to-{}.csv'.format(app_id, report_type, params['from'], params['to']), 'w', newline='', encoding="utf-8")
f.write(res.text)
f.close()
using System;
using RestSharp;
using System.Text;
using System.Net;
using System.IO;
namespace Pull_API
{
class PullAPi
{
static void Main(string[] args)
{
var appID = "<APP_ID>";
var reportType = "<REPORT_TYPE>";
var from = "<FROM_DATE>";
var to = "<TO_DATE>";
var requestUrl = "https://hq.appsflyer.com/export/" + appID + "/" + reportType + "/v5?api_token=" + apiToken + "&from=" + from + "&to=" + to;
var client = new RestClient(requestUrl);
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "text/csv; charset=UTF-8");
IRestResponse response = client.Execute(request);
HttpStatusCode statusCode = response.StatusCode;
int numericStatusCode = (int)statusCode;
if(numericStatusCode != 200){
if(numericStatusCode == 404){
Console.WriteLine("There is a problem with the request URL. Make sure that it is correct.");
} else {
Console.WriteLine("There was a problem retrieving data: " + response.Content);
}
} else {
System.IO.File.WriteAllText(@"" + appID + "-" + reportType + "-" + from + "-to-" + to + ".csv", response.Content);
Console.WriteLine("Data retrieved succesfully");
}
}
}
}
<?
$appID = '<APP_ID>';
$reportType = '<REPORT_TYPE>';
$from = '<FROM_DATE>';
$to = '<TO_DATE>';
$query = http_build_query([
'from' => $from,
'to' => $to
]);
$requestUrl = 'https://hq.appsflyer.com/export/' . $appID . '/' . $reportType . '/v5?'.$query;
$report = $appID . '-' . $report . '-' . $from . '-to-' . $to;
$curl = curl_init($requestUrl);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_ENCODING, "");
curl_setopt($curl, CURLOPT_NOSIGNAL, true);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($curl, CURLOPT_MAXREDIRS, 10);
curl_setopt($curl, CURLOPT_FAILONERROR, true);
curl_setopt($curl, CURLOPT_TIMEOUT, 100);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($curl, CURLOPT_HTTPHEADER, array(
"cache-control: no-cache",
"Accept: text/csv; charset=UTF-8"
));
$response = curl_exec($curl);
$info = curl_getinfo($curl);
$err = curl_error($curl);
curl_close($curl);
var_dump($response);
if ($err) {
echo $info['http_code'];
echo "cURL Error #: " . $err . '. ';
if ($info['http_code'] == 404) {
echo 'There is a problem with the request URL. Make sure that it is correct';
}
if ($info['http_code'] == 401) {
echo 'There was a problem retrieving data: authentication failed.';
}
echo PHP_EOL;
} else {
$fp = fopen($report, 'w+');
fwrite($fp, $response);
fclose($fp);
echo $response;
}
?>
Дополнительные сведения
Ограничения и особенности
Специфика | Комментарии |
---|---|
Необходимый тип токена API |
![]() |
Доступ рекламной сети | N |
Доступ агентств | Y |
Прозрачность агентства | Y |
Валюта приложения | Y |
Часовой пояс приложения | Y |
затраты | Данные о затратах доступны только по кампаниям UA и не доступны по ретаргетинговым и неактивным кампаниям (кампаниям без установок). |
Актуальность данных | Непрерывно |
Исторические данные | Y |
Неорганические данные | Y |
органические данные | Y |
Ограничение предоставления данных | |
Ограничения на размер |
Внимание! Pull API поддерживает до 1 млн строк сырых данных. Отчеты с агрегированными данными ограничены 200 тыс. строк. |
Изменения названия кампании | Отчеты через Pull API не поддерживают изменения названия кампании |
Коды ошибок API и устранение неисправностей
Статус | Код | Симптом/сообщение | Решение |
---|---|---|---|
OK | 200 | Пустой файл CSV |
|
OK |
200 |
|
В схеме URI не найден токен API |
Bad request |
400 |
Ретроспективный обзор в отчетах по сырым данным ограничен 90 днями. |
Используйте |
Bad request |
400 |
Вы исчерпали лимит на вызовы API для этого типа отчета |
- |
Не авторизовано |
401 |
Указанный токен API недействителен |
Попросите у администратора действующий токен. |
Не авторизовано |
401 |
Аккаунт может быть заморожен |
Войдите в систему и проверьте на дэшборде статус аккаунта. |
Not found |
404 |
Отображается страница AppsFlyer с ошибкой 404 |
|