Когортный API

Премиум
Для:
маркетологов
Последнее обновление:

Краткий обзор: Когортный API (Cohort API) предоставляет рекламодателям программный способ получения данных когорт. Используйте API для интеграции данных по когортам в системы бизнес-аналитики и автоматизации маркетинга.

Когортный API

Когортный API используется для получения когортных данных об эффективности кампаний с платформы AppsFlyer. Функционально он эквивалентен когортному дэшборду. 

Чтобы использовать когорты и удержание, вы определяете данные, которые хотите просмотреть. Необходимо выбрать пользователей из приложения и сегментировать их по времени конверсии. Доступны такие метрики когортного анализа, как доход, ROI и коэффициент конверсии событий. Для сравнения когорта может быть разбита по таким показателям, как кампания и медиа-источник. Результат возвращается в виде файла CSV или JSON. Вы можете использовать эти результаты, чтобы обнаруживать закономерности или изменения эффективности в течение жизненного цикла пользователя или кампании.

См. Сценарии когортного анализа. 

Как использовать Когортный API:

  1. AppsFlyerAdmin_us-en.png Получите токен API. Получить токен должен администратор.
  2. Передайте своему разработчику токен API, который будет использоваться в заголовке аутентификации.
  3. Предоставьте разработчикам параметры, которые они должны ввести при вызове API, как описано в следующих разделах. Параметры определяют, что содержится в отчёте, как он организован, а также устанавливают временные рамки отчётности.
  4. Попросите своего разработчика следовать инструкциям для Когортного API в разделе для разработчиков.

Параметры когортного API

Для получения необходимых данных используйте следующие параметры. 

Название параметра Описание Обязательно? 
bearer Токен API, используемый в заголовке аутентификации API. Да
cohort _type Тип атрибуции когорты (конверсии) один из следующих:user_acquisition, retargeting, unified
  • Объединённая: объединённая эффективность кампаний по привлечению пользователей и ретаргетингу.
  • Если событие атрибутировано и к ретаргетингу, и к кампаниям по привлечению пользователей, то в возвращаемые KPI включается только событие ретаргетинга, что означает is_primary=true.
  • Формат: Строка
  • Например: "cohort_type": "user_acquisition"
Да
min_cohort_size Минимальный размер когорты используется для уменьшения количества возвращаемых записей за счёт исключения когорт с небольшим количеством пользователей. Это означает, что значение KPI «пользователи» должно быть равно или больше указанного. 
  • Формат: Целое число
  • Минимально допустимое значение: 1. Не отправлять 0 (ноль)
  • По умолчанию: 1 
  • Например: "min_cohort_size": 50
Нет
from  Нижняя граница диапазона дат атрибуции LTV. Самая ранняя дата: 720 дней до текущей даты.  
  • Формат: строка гггг-мм-дд
  • Пример: "from": "2020-01-02"
Да
to Верхняя граница диапазона дат атрибуции LTV
  • Количество дней в диапазоне: 1-31 дней
  • За один день: значения from и to идентичны. 
  • Формат: гггг-мм-дд
  • Пример: "from": "2020-01-01", "to": 2020-01-31 составляет 31 день.
 Да
granularity

Почасовая детализация для предыдущих 72 часов, если задать "granularity": "hour" и установить диапазон from и to по времени суток.

  • Формат: гггг-мм-дд чч:мм:сс
  • Пример:

"granularity": "hour", "from": "2021-12-01 14:00:00", "to": "2021-12-03 11:00:00",

 Нет
partial_data

Во избежание искажения и неверной интерпретации данных, в когорту возвращаются данные за полные дни. Однако данные о неполных днях могут быть также полезны. 

Количество полных дней когорты для запроса рассчитывается как разница между сегодняшней датой и датой to (до).

  • [По умолчанию] Если выбрано «false», то возвращаются полные дни.
  • Если «true», то возвращается до 180 дней когорты, включая дни с неполными данными.  
  • Формат: логический
  • Версия пользовательского интерфейса платформы: false

Пример: 10 мая количество полных дней когорты для пользователей, совершивших конверсию в период с 1 по 30 апреля, равно 10.  

  • Если выбрано «false» [по умолчанию], то возвращаются дни когорты 0-9. Это количество дней (10) между последней датой конверсии и сегодняшним днем.  
  • Если выбрано «true», то возвращаются дни когорты 1-40. Дни 11-40 содержат неполные данные и не возвращаются. Например, с 20 апреля прошло всего 20 дней и т.д.

Примечание: Частичные данные допускаются только в том случае, если выбран кумулятивный тип агрегирования данных.

  Нет
filters Фильтрация возвращаемых данных и дней выбранного периода. Выберите фильтры из списка фильтров для показателей.
  • Формат: Строки в вложенном JSON. Значения должны быть в массиве.
  • Пример ограничения по определённым регионам: "filters": {"geo": ["US"]} включает только пользователей, атрибутированных в США. 
  • Пример периода (когорты) в днях: Фильтр period устанавливает дни, по которым возвращаются меры. Возможные значения: 0-180 
  • По умолчанию: Если фильтр периодов не установлен, то возвращаются дни 0-30, 60, 90 и 180.  Пример фильтра с периодом
 Нет
groupings
  • Чтобы включить дополнительные столбцы и сделать отчеты менее детализированными, используйте параметры группировки.
  • Выберите 1-7 группировок из списка группировки показателей.
  • Формат: Строки в массиве
  • Пример: "groupings": ["af_ad", "c", "af_c_id", "af_prt"]
Да
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"]
    Функции
По умолчанию/ Необязательно   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) Сумма означает общий доход, принесённый событием. В отчете это обозначается как sum_event_name"

(4) Важно! Названия событий чувствительны к регистру.

Форматирование функций KPI

Следующие параметры задают формат возвращаемых KPI.  

Параметр Значения Обязательный 
preferred_currency Валюта дохода KPI
  • Если true, то доход возвращается с использованием валюты приложения, заданной на платформе. 
  • [По умолчанию] Если false, то результаты возвращаются в долларах США.
  • Формат: логический 
  • Версия пользовательского интерфейса платформы: true
  Нет
preferred_timezone Часовой пояс диапазонов дат
  • Если true, то время будет выражаться с использованием часового пояса приложения, заданного на платформе.
  • [По умолчанию] Если false, то время выражается с использованием часового пояса UTC.
  • Формат: логический 
  • Версия пользовательского интерфейса платформы: true
  Нет
aggregation_type
  • cumulative
  • on_day

"aggregation_type": "cumulative"

Format: String

 Да
per_user Функция KPI делится на количество пользователей приложения. Применяется только к соответствующим KPI.
  • Если true, то значения KPI делятся на количество пользователей в когорте.
  • Если значение false, то значения KPI не делятся на количество пользователей.
  • Формат: логический 
  • Пример, если true: общий доход составляет $1000, количество пользователей приложения – 500, возвращаемое значение – $2.  
  Нет

Группировка по и фильтрация

Название параметра  Значение 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) Тип конверсии:  user_acquisition, retargeting(re-engagement и re-attribution), unified

  • При экспорте:
    • re-engagement будет отображаться как retargeting
    • re-attribution будет отображаться как reattr

(2) Тип дохода: regular, ad_monetization

(3) Атрибутированный тип взаимодействия: click, impression, TV, pre-installed

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

Использование фильтров периодов

Период относится к дню после атрибуции, где период 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"
    ]
}

Сырые данные

mceclip1.png

Результаты

mceclip0.png

Характеристики и ограничения

Специфика Замечания 
Доступ к рекламной сети  Нет
Доступ агентств Нет
Часовой пояс конкретного приложения Да
Валюта приложения  Да
Ограничения по размеру Нет
Ограничение предоставления данных
  • Лимит частоты вызовов API: 60 вызовов в минуту и 50 000 вызовов в день на один аккаунт.
  • Запросы возвращают до 30 000 строк.
Органические данные Доступно
Неорганические данные Доступно
Ограничение по данным о затратах
  • Данные о затратах приводятся только для кампаний, в которых зарегистрирована хотя бы одна установка.
  • AppsFlyer не предоставляет данные о затратах для ключевых слов, содержащих заглавные буквы, в когортном отчёте или когортном API
  • Нельзя объединить некоторые комбинации группировок с затратами. Например, Meta Ads может предоставить группировку либо по региону, либо по каналу, но не по обоим параметрам сразу. Точная комбинация группировок зависит от рекламной сети.
Обновление данных Обновление данных зависит от partial_data следующим образом:  
Исторические данные Ежедневные когорты: 2 года
Доступ для пользователей аккаунта Токен авторизации доступен пользователям-администраторам на дэшборде
Доход от рекламы Для событий af_ad_revenue метрика уникальных пользователей недоступна при указанном ниже типе агрегации данных:
  • «Кумулятивный» (Cumulative).
  • «В день» (On day) для дат между 5 октября 2022 года и 16 февраля 2023 года.
Группировки по неделям и месяцам Группировка по параметрам недели и месяца недоступна в когортном API. Используйте дэшборд когорт.
Период когортного API
  • Период конверсии обозначается как 0 (час 0 или день 0). Следующий период после конверсии обозначается как 1 (час 1 или день 1) и т.д.
  • В AppsFlyer период когорты не учитывает конкретную временную метку установки. Часы работы когорты округляются до ближайшего часа, а дни работы когорты определяются на основе календарного дня. Это может привести к расхождениям при сравнении данных когорты AppsFlyer с данными других сетей, где все периоды когорты определяются по конкретной временной метке установки (то есть час – это 60 минут после установки, а день – это 24 часа после установки и т.д.). 
Даты
  • Даты или диапазоны дат относятся к датам жизненного цикла клиента (LTV), то есть к дате атрибуции (конверсии) пользователя, а не к дате самой активности.
  • Самая ранняя поддерживаемая дата: За 730 дней до текущей даты. То есть 2 года.
  • Максимальный диапазон запроса: 60 дней.
Повторные установки
  • Если события после переустановки считаются неатрибутированными органическими:
    • Они включены только с 26 мая 2024 года. Узнать больше
    • Время установки определяется на основе поля device_download_time.
    • Они не учитываются в подсчётах уникальных пользователей и показателях удержания.
  • Если события после переустановки отнесены к первой установке, они всегда учитываются. Узнать больше
Когортный API для партнёров Доступ к когортному API для маркетинговых партнёров прекращён с 15 сентября 2024 года. Маркетинговым партнёрам рекомендуется активировать Data Locker, чтобы обеспечить постоянный доступ к данным клиентов.