Краткий обзор: Когортный API (Cohort API) предоставляет рекламодателям программный способ получения данных когорт. Используйте API для интеграции данных по когортам в системы бизнес-аналитики и автоматизации маркетинга.
Когортный API
Когортный API используется для получения когортных данных об эффективности кампаний с платформы AppsFlyer. Функционально он эквивалентен когортному дэшборду.
Чтобы использовать когорты и удержание, вы определяете данные, которые хотите просмотреть. Необходимо выбрать пользователей из приложения и сегментировать их по времени конверсии. Доступны такие метрики когортного анализа, как доход, ROI и коэффициент конверсии событий. Для сравнения когорта может быть разбита по таким показателям, как кампания и медиа-источник. Результат возвращается в виде файла CSV или JSON. Вы можете использовать эти результаты, чтобы обнаруживать закономерности или изменения эффективности в течение жизненного цикла пользователя или кампании.
См. Сценарии когортного анализа.
Как использовать Когортный API:
-
Получите токен API. Получить токен должен администратор.
- Передайте своему разработчику токен API, который будет использоваться в заголовке аутентификации.
- Предоставьте разработчикам параметры, которые они должны ввести при вызове API, как описано в следующих разделах. Параметры определяют, что содержится в отчёте, как он организован, а также устанавливают временные рамки отчётности.
- Попросите своего разработчика следовать инструкциям для Когортного API в разделе для разработчиков.
Параметры когортного API
Для получения необходимых данных используйте следующие параметры.
Название параметра | Описание | Обязательно? |
---|---|---|
bearer | Токен API, используемый в заголовке аутентификации API. | Да |
cohort _type | Тип атрибуции когорты (конверсии) один из следующих:user_acquisition , retargeting , unified
|
Да |
min_cohort_size | Минимальный размер когорты используется для уменьшения количества возвращаемых записей за счёт исключения когорт с небольшим количеством пользователей. Это означает, что значение KPI «пользователи» должно быть равно или больше указанного.
|
Нет |
from | Нижняя граница диапазона дат атрибуции LTV. Самая ранняя дата: 720 дней до текущей даты.
|
Да |
to | Верхняя граница диапазона дат атрибуции LTV
|
Да |
granularity |
Почасовая детализация для предыдущих 72 часов, если задать
|
Нет |
partial_data |
Во избежание искажения и неверной интерпретации данных, в когорту возвращаются данные за полные дни. Однако данные о неполных днях могут быть также полезны. Количество полных дней когорты для запроса рассчитывается как разница между сегодняшней датой и датой to (до).
Пример: 10 мая количество полных дней когорты для пользователей, совершивших конверсию в период с 1 по 30 апреля, равно 10.
Примечание: Частичные данные допускаются только в том случае, если выбран кумулятивный тип агрегирования данных. |
Нет |
filters | Фильтрация возвращаемых данных и дней выбранного периода. Выберите фильтры из списка фильтров для показателей.
|
Нет |
groupings |
|
Да |
kpis | KPI – это метрики, используемые для получения информации о работе вашего приложения. Узнайте, как выбирать и форматировать KPI | Да |
preferred_currency | Параметр, который устанавливает формат возвращаемых KPI. Подробнее о форматировании KPI | Нет |
preferred_timezone | Параметр, который устанавливает формат возвращаемых KPI. Подробнее о форматировании KPI | Нет |
aggregation_type | Параметр, который устанавливает формат возвращаемых KPI. Подробнее о форматировании KPI | Да |
per_user | Параметр, который устанавливает формат возвращаемых KPI. Подробнее о форматировании KPI | Нет |
Выбор и форматирование KPI
- В таблице перечислены доступные KPI и связанные с ними функции. При вызове KPI возвращаются все его функции.
- Всегда возвращаются следующие KPI: users (пользователи), ecpi, и cost (затраты)
- Выберите один дополнительный KPI для каждого вызова.
- Для каждого запрашиваемого KPI возвращаются все функции.
- Формат: Строки в массиве
- Пример A:
"kpis": ["sessions"]
- Пример B:
"kpis": ["event_name"]
- Пример A:
Функции | ||||||
---|---|---|---|---|---|---|
По умолчанию/ Необязательно | KPI (название параметра) | Количество | cvr (коэффициент конверсии) | Коэффициент | Сумма | Уникальные пользователи |
Число | Процент | Процент | Число | Число | ||
Всегда | users | Да | - | - | - | - |
Всегда | ecpi | - | - | - | Да | - |
Всегда | cost | - | - | - | Да | - |
Необязательно |
"event_name" (4) |
Да | Да | - | Да (3) | Да |
Необязательно | revenue | Да | - | - | Да | - |
Необязательно | roas | - | - | Да | - | - |
Необязательно | roi | - | - | Да | - | - |
Необязательно | sessions | Да | - | Да | - | Да (1) |
Необязательно | uninstalls (2) | Да | - | Да | - | - |
(1) Уникальные сессии возвращаются при aggregation_type = on_day (2) Недоступно, если cohort_type=unified (3) Сумма означает общий доход, принесённый событием. В отчете это обозначается как (4) Важно! Названия событий чувствительны к регистру. |
Форматирование функций KPI
Следующие параметры задают формат возвращаемых KPI.
Параметр | Значения | Обязательный |
---|---|---|
preferred_currency | Валюта дохода KPI
|
Нет |
preferred_timezone |
Часовой пояс диапазонов дат
|
Нет |
aggregation_type |
|
Да |
per_user | Функция KPI делится на количество пользователей приложения. Применяется только к соответствующим KPI.
|
Нет |
Группировка по и фильтрация
Название параметра | Значение API параметра | Группировки | Фильтры |
---|---|---|---|
Реклама | af_ad | Да | Да |
Идентификатор рекламы | af_ad_id | Да | Да |
Кампания | c | Да | Да |
Идентификатор кампании | af_c_id | Да | Да |
Канал | af_channel | Да | Да |
Медиа-источник | pid | Да | Да |
Cубпараметр 1 | af_sub1 | Да | Да |
Ключевые слова | af_keywords | Да | Да |
Агентство | af_prt | Да | Да |
Тип конверсий (1) | cohort _type | Да | Да |
Идентификатор сайта | site_id | Да | Да |
Тип дохода (2) | revenue_type | x | Да |
Атрибутированный тип взаимодействия (3) | attributed_touch_type | Да | Да |
Группа объявлений | af_adset | Да | Да |
Идентификатор группы объявлений | af_adset_id | Да | Да |
Страна | geo | Да | Да |
Дата (дата установки / повторной атрибуции / повторного вовлечения в контексте выбранного типа когорты (cohort_type)) | date | Да | x |
Период |
period
|
x | Да |
Примечания: Опции параметров: (1) Тип конверсии:
(2) Тип дохода: (3) Атрибутированный тип взаимодействия: |
Дополнительные сведения
Использование фильтров периодов
Период относится к дню после атрибуции, где период 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 выбирается доход.
- В запросе указывается тип агрегации как «кумулятивный». Измените на «on_day», если вы хотите получать данные день в день.
- В результате возвращаемые данные содержат:
- показатели пользователей, затрат и 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": "cumulative", "per_user": false, "groupings": [ "pid" ], "kpis": [ "revenue" ] }
Сырые данные
Результаты
Характеристики и ограничения
Специфика | Замечания |
---|---|
Доступ к рекламной сети | Нет |
Доступ агентств | Нет |
Часовой пояс конкретного приложения | Да |
Валюта приложения | Да |
Ограничения по размеру | Нет |
Ограничение предоставления данных |
|
Органические данные | Доступно |
Неорганические данные | Доступно |
Ограничение по данным о затратах |
|
Обновление данных | Обновление данных зависит от partial_data следующим образом:
|
Исторические данные | Ежедневные когорты: 2 года |
Доступ для пользователей аккаунта | Токен авторизации доступен пользователям-администраторам на дэшборде |
Доход от рекламы | Для событий af_ad_revenue метрика уникальных пользователей недоступна при указанном ниже типе агрегации данных:
|
Группировки по неделям и месяцам | Группировка по параметрам недели и месяца недоступна в когортном API. Используйте дэшборд когорт. |
Период когортного API |
|
Даты |
|
Повторные установки |
|
Когортный API для партнёров | Доступ к когортному API для маркетинговых партнёров прекращён с 15 сентября 2024 года. Маркетинговым партнёрам рекомендуется активировать Data Locker, чтобы обеспечить постоянный доступ к данным клиентов. |