Краткий обзор. API для создания когортных отчетов (Cohort API) предоставляет рекламодателям программный способ получения данных когорт. Используйте API для интеграции данных по когортам в системы бизнес-аналитики и автоматизации маркетинга.
API для создания когортных отчетов
API для создания когортных отчетов используется для получения когортных данных об эффективности кампаний с платформы AppsFlyer. Функционально он эквивалентен дэшборду когорт.
Примечания для разработчиков
- Даты: Даты или диапазоны дат относятся к датам жизненного цикла клиента (LTV), то есть к дате атрибуции (конверсии) пользователя, а не к дате самой активности.
- Логические значения: true или false (с учетом регистра).
- Прозрачный и непрозрачный трафик агентств: Медиа-источником трафика, привлеченного агентством, всегда является агентство, а не оригинальный медиа-источник. В настоящее время версия когорт в интерфейсе пользователя ведет себя по-другому.
- Одно приложение: Cohort API представляет собой решение для одного приложения. Это отличается от дэшборда когорт, который поддерживает работу с несколькими приложениями в рамках одного вызова.
- Обновление данных: См. характеристики и ограничения.
Инструкции по API
Разделы содержат информацию, необходимую для создания и использования Cohort API.
Факты о Cohort API
| Обзор | Вызов API состоит из пути, заголовков и JSON, содержащего запрос данных. По умолчанию данные возвращаются в CSV-файле. |
| Маршрут |
|
| Параметры пути (обязательные) |
|
|
Параметры запроса (необязательно) |
Результаты возвращаются в формате CSV или JSON. Структура файла CSV является табличной, а структура JSON ориентирована на записи. |
| HTTP-метод | POST |
| Принятые типы контента | application/json |
| Авторизация |
|
| Ограничения по датам |
|
| Ограничение предоставления данных |
|
| Логические значения | Всегда в нижнем регистре: true, false |
Заголовки запросов
|
Ключ |
Значение | Обязательно/Не обязательно |
|---|---|---|
| Content-Type | application/json |
Да |
| Authorization | Bearer api_token_placeholder |
Да |
| Принять | application/json |
Да |
Параметры фильтрации и группировки
Для получения необходимых данных используйте следующие параметры фильтрации.
|
Имя параметра |
Описание | Обязательно/Не обязательно |
|---|---|---|
|
cohort _type |
Тип атрибуции когорты (конверсии) один из следующих:
|
Да |
|
min_cohort_size |
Минимальный размер когорты используется для уменьшения количества возвращаемых записей путем исключения когорт с небольшим количеством пользователей. Это означает, что KPI пользователей имеет значение, равное или большее указанного.
|
Нет |
|
from |
Нижняя граница диапазона дат атрибуции LTV. Самая ранняя дата: 720 дней с текущей даты.
|
Да |
|
to (по) |
Верхняя граница диапазона дат атрибуции LTV
|
Да |
|
granularity |
Почасовая детализация для предыдущих 72 часов, если задать
"granularity": "hour",
"from": "2021-12-01 14:00:00", "to": "2021-12-03 11:00:00",
|
Нет |
|
partial_data |
Во избежание искажения и неверной интерпретации данных в когорту возвращаются данные за полные дни. Однако данные о неполных днях могут быть также полезны. Количество полных дней когорты для запроса рассчитывается как разница между сегодняшней датой и датой to (до).
Пример: На 10 мая количество полных дней когорты для пользователей, совершивших конверсию в период с 1 по 30 апреля, равно 10.
Примечание. Частичные данные допускаются только в том случае, если выбран кумулятивный тип агрегирования данных. |
Нет |
|
Фильтры |
Отфильтруйте возвращаемые данные и дни периода. Выберите фильтры из списка фильтров для показателей.
|
Нет |
Чтобы включить дополнительные столбцы и сделать отчеты менее детализированными, используйте следующие параметры группировки.
|
Параметр |
Значения | Обязательно/Не обязательно |
|---|---|---|
|
groupings |
|
Да |
Выбор и форматирование KPI
- В таблице перечислены доступные KPI и связанные с ними функции. При вызове KPI возвращаются все его функции.
- Всегда возвращаются следующие KPI: пользователи, ecpi и затраты
- Выберите один дополнительный KPI для каждого вызова.
| Функции | ||||||
|---|---|---|---|---|---|---|
| По умолчанию/ Необязательно | KPI (название показателя) | Количество | cvr (коэффициент конверсии) | Коэффициент | Сумма | Уникальные пользователи |
| Число | Процент | Процент | Число | Число | ||
| Всегда | польз. | Y | - | - | - | - |
| Всегда | ecpi | - | - | Y | - | - |
| Всегда | затраты | - | - | - | Y | - |
| Необязательно | "event_name"(4) |
Y | Y | - | Y (3) | Y |
| Необязательно | доход | Y | - | - | Y | - |
| Необязательно | ROAS (доход от вложений в рекламу) | - | - | Y | - | - |
| Необязательно | roi | - | - | Y | - | - |
| Необязательно | сессии | Y | - | Y | - | Y(1) |
| Необязательно | uninstalls (2) | Y | - | Y | - | - |
|
(1) Уникальные сессии возвращаются для aggregation_type = on_day (2) Недоступно, если cohort_type=unified (тип когорты объединенная) (3) Сумма означает общий доход, принесенный событием. В отчете это обозначается (4) Важно! Названия событий чувствительны к регистру |
||||||
|
Параметр |
Значения | Обязательный параметр |
|---|---|---|
|
KPI's |
Выберите один KPI из доступных. В будущем мы планируем разрешить выбор нескольких KPI.
|
Да |
Представление функций KPI
Следующие параметры формата KPI задают формат возвращаемых KPI.
|
Параметр |
Значения | Обязательно/Не обязательно |
|---|---|---|
|
preferred_currency |
Валюта дохода KPI
|
Нет |
|
preferred_timezone |
Часовой пояс диапазонов дат
|
Нет |
|
aggregation_type |
|
Да |
|
per_user |
Разделите функцию KPI на количество пользователей приложения. Применяется только к соответствующим KPI.
|
Нет |
Список показателей фильтрации и группировки
|
Название показателя |
Значение API показателя |
Группировки |
Фильтры |
|---|---|---|---|
|
Реклама |
af_ad |
Y |
Y |
|
ID рекламы |
af_ad_id |
Y |
Y |
|
Кампания |
c |
Y |
Y |
|
ID кампании |
af_c_id |
Y |
Y |
|
Канал |
af_channel |
Y |
Y |
|
Медиа-источник |
pid |
Y |
Y |
|
Cубпараметр 1 |
af_sub1 |
Y |
Y |
|
Ключевые слова |
af_keywords |
Y |
Y |
|
Агентство |
af_prt |
Y |
Y |
|
Тип конверсий (1) |
cohort_type |
Y |
Y |
|
ID сайта |
site_id |
Y |
Y |
|
Тип дохода (2) |
revenue_type |
x |
Y |
|
Атрибутированный тип взаимодействия (3) |
attributed_touch_type |
Y |
Y |
|
Блок рекламы |
af_adset |
Y |
Y |
|
ID блока рекламы |
af_adset_id |
Y |
Y |
|
Страна |
geo |
Y |
Y |
|
Дата (дата установки / реатрибуции / повторного вовлечения в контексте выбранного типа когорты) |
дата |
Y |
x |
|
Период |
период
|
X |
Y |
|
Примечания: Опции показателей: (1) Тип конверсии:
(2) Тип дохода: click (клик), impression (показ), TV, pre-installed (предустановка)
|
|||
Пример curl
Данный пример содержит полный вызов API.
curl -L -X POST 'https://hq1.appsflyer.com/api/cohorts/v1/data/app/<insert your app_id here>?format=<insert results format here>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <cohort_api_token_placeholder. Note the token has more than 700 characters.>' \
-H 'Accept: application/json' \
--data-raw '{
"cohort_type": "user_acquisition",
"min_cohort_size": 1,
"preferred_timezone": false,
"from": "2020-01-01",
"to": "2020-01-31",
"filters": {
"period": [
0,
1,
2,
10,
30,
60
],
"geo": [
"US",
"CN"
],
"pid": [
"Meta ads",
"googleadwords_int"
]
},
"preferred_currency": true,
"aggregation_type": "on_day",
"per_user": false,
"groupings": [
"pid",
"date"
],
"kpis": [
"sessions"
]
}'
Пример Python
import http.client
import mimetypes
conn = http.client.HTTPSConnection("hq1.appsflyer.com")
payload = "{\r\n \"cohort_type\": \"user_acquisition\",\r\n \"min_cohort_size\": 1,\r\n \"preferred_timezone\": false,\r\n \"from\": \"2020-05-01\",\r\n \"to\": \"2020-05-10\",\r\n \"preferred_currency\": true,\r\n \"aggregation_type\": \"cumulative\",\r\n \"per_user\": false, \r\n \"groupings\": [\r\n \"pid\",\r\n \"date\"\r\n ],\r\n \"kpis\": [\r\n \"roas\"\r\n ]\r\n}"
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer [Enter token here]',
'Accept': 'application/json',
'Content-Type': 'application/json'
}
conn.request("POST", "/api/cohorts/v1/data/app/[My App ID here]?format=csv", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Примеры использования
Пример 1: Удержание
Удержание пользователей (сессии) из медиа-источника, установивших приложение в январе, на 7, 14 и 28 день
{
"per_user": false,
"groupings": [
"pid"
],
"filters": {
"period": [
7, 14, 28
]
},
"partial_data": false,
"aggregation_type": "on_day",
"min_cohort_size": 1,
"cohort_type": "user_acquisition",
"from": "2021-01-01",
"to": "2021-01-30",
"kpis": [
"sessions"
]
}Пример 2: Покупки в результате кампании
Доходы когорты на 3-й день после установки на одну кампанию
{
"per_user": false,
"groupings": [
"c"
],
"filters": {
"period": [
3
],
"c":[
"example_campaign_name"
]
},
"partial_data": false,
"aggregation_type": "cumulative",
"min_cohort_size": 1,
"cohort_type": "user_acquisition",
"from": "2021-01-01",
"to": "2021-01-30",
"kpis": [
"Checkout Start"
]
}Пример 3: Активность за вчерашний день
Какие действия совершили вчера пользователи, чья конверсия (установка, повторное вовлечение, реатрибуция) произошла в течение заданного периода конверсии?
Используйте данные, доступные через когорту для Data Locker. Период конверсии ограничен предыдущими 360 днями.
Дополнительные сведения
Коды ответов и поиск неисправностей
|
Код ответа |
Сообщение |
Примечание |
|---|---|---|
| 200 | OK |
Возвращаются действительные данные |
| 200 | OK |
|
| 401 | Не авторизовано |
|
| 404 | Not found |
|
| 422 | Объект не может быть обработан |
Частыми причинами появления этого кода ошибки являются:
|
Структура имени файла CSV
Имя, присваиваемое возвращаемому CSV-файлу, который формируется на основе запроса API. Структура представлена в следующей таблице.
Пример имени файла CSV
cohort_aggregation_type_per_user_kpi_report_app_id_from_to_timezone_currency_hash.csv| Переменная | Возможные значения |
|---|---|
| aggregation_type |
|
| per_user |
|
| KPI | Пример: сессии |
| app_id | Запрашивается идентификатор приложения |
| from (от) | Дата from (с): формат гггг-мм-дд |
| to (по) | Дата to (по): формат гггг-мм-дд |
| timezone (часовой пояс) | Часовой пояс по умолчанию UTC |
| currency (валюта) | Код валюты по умолчанию USD |
| hash |
Строка хэша буквенно-цифровая длина=5 |
Использование фильтров периодов
Период относится к дню после атрибуции, где период 0 — это день атрибуции. Например, пользователь устанавливает приложение 1 января. Это день атрибуции. Покупка, совершенная в период 0, означает, что она была совершена 1 января. Покупка, совершенная в периоде 3, означает, что она была совершена 4 января. Аналогично, если пользователь установил приложение 11 января, то это период 0. Покупка, совершенная 14 января, будет относиться к периоду 3.
Если диапазон дат отчета с 1 по 11 января, то в отчет попадают пользователи, атрибутированные (установившие приложение) в этот период. Другие данные не включаются.
- Значение периода может быть одним или несколькими из следующих 0-180. Например, 0, 1, 2, 30, 180.
- Если период не указан, то по умолчанию возвращаются значения 0, 1, 2 и так далее до 30, 60, 90 и 180.
Пример фильтра периодов
- Этот пример содержит параметры запроса JSON, сырые данные и итоговый CSV-файл.
- В запросе фильтруются периоды 0, 1 и 2, а в качестве KPI выбирается доход.
- В результате возвращаемые данные содержат:
- Показатели пользователей, затрат и ecpi, которые всегда возвращаются
- Показатели дохода, состоящие из суммы и количества для каждого периода, под которыми понимаются периоды 0, 1 и 2.
Запрос
{
"cohort_type": "user_acquisition",
"min_cohort_size": 1,
"preferred_timezone": false,
"from": "2019-12-01",
"to": "2020-01-01",
"filters": {
"period": [
0,
1,
2
]
},
"aggregation_type": "on_day",
"per_user": false,
"groupings": [
"pid"
],
"kpis": [
"revenue"
]
}
Сырые данные
Результаты
Сопоставление пользовательского интерфейса с параметрами API
На следующих схемах пользовательский интерфейс когортной аналитики сопоставлен с параметрами API. Два решения — API и пользовательский интерфейс — похожи, но не идентичны.
Версия API имеет следующие дополнительные опции:
- Выбор валюты
- Выбор часового пояса
- Фильтрация по периодам
Различие между типами агрегирования данных
Ограничения и особенности
| Специфика | Заметки |
|---|---|
| Доступ рекламной сети |
Нет. Партнеры по управлению кампаниями могут использовать API, если рекламодатель дает на это разрешение. |
| Доступ агентств | Нет |
| Прозрачность агентства | Не поддерживается |
| Часовой пояс приложения | Да |
| Валюта приложения | Да |
| Ограничения на размер | Нет |
| Ограничение предоставления данных |
Ограничение вызовов API: до 60 вызовов в минуту на один аккаунт |
| Органические данные | Доступно |
| Неорганические данные | Доступно |
| Ограничение по данным о затратах |
|
| Актуальность данных |
Обновление данных зависит от partial_data следующим образом:
|
| Исторические данные | Ежедневная когорта: 2 года |
| Доступ пользователей аккаунта | Токен авторизации доступен пользователям-администраторам на дэшборде |
| Доходы от рекламы |
Для событий af_ad_revenue метрика уникальных пользователей недоступна при типе агрегирования данных "on day," для дат с 5 октября 2022 года по 16 февраля 2023 года. |
| Группировки по неделям и месяцам |
Группировка по параметрам недели и месяцы недоступна в Cohort API. Используйте дэшборд когорт. |
| Cohort API |
|