Master API — метрики привлечения пользователей через API

Премиум

Для:

маркетологов разработчиков

Последнее обновление: 12/09/2024 09:05

Краткий обзор. Выбранные KPI для LTV, активности, удержания, когорты и эффективности кампании Protect360 по API, в формате CSV или JSON. Выберите 1 или несколько приложений.

Master API — метрики привлечения пользователей через API

Master API:

Позволяет получить выбранные ключевые показатели эффективности для LTV, активности, удержания, когорты и эффективности кампании Protect360. Доступные KPI эквивалентны KPI, которые можно найти на дэшбордах Обзорный, Активность, Удержание, Когорта и Protect360.
Рассчитываются ежедневно. Обновленные данные будут доступны вам в течение 24–48 часов, в зависимости от часового пояса вашего приложения.
Это инфраструктура, на которой построена сводная таблица AppsFlyer.

Чтобы использовать Master API, вы определяете данные, которые хотите просмотреть (аналогично реализации Pull API). Результат возвращается в виде файла CSV или JSON.

Чтобы использовать Мастер API:

Получите токен API. Получить токен должен админ.
Дайте разработчику токен API, который будет использоваться в заголовке аутентификации.
Предоставьте разработчикам параметры, которые они должны ввести при вызове API, как описано в следующем разделе. Параметры определяют, что содержится в отчете, как он организован, а также устанавливают временные рамки отчетности.
Попросите своего разработчика следовать инструкциям для Master API в Центре разработчиков.

Параметры API

Параметр	Значение	Обязательно/Не обязательно
app_id (идентификатор приложения)	Идентификатор приложения, указанный в AppsFlyer. Вставьте идентификатор приложения точно как он указан в AppsFlyer. Для приложений iOS необходим префикс id Используйте все идентификаторы приложений для запроса всех ваших приложений.	Да
from (от)	Нижняя граница диапазона дат атрибуции LTV. Формат: строка гггг-мм-дд Пример: `from: 2020-01-02`	Да
to (по)	Верхняя граница диапазона дат атрибуции LTV Количество дней в диапазоне: 1-31 дней За один день: значения `from` и `to` идентичны. Формат: гггг-мм-дд Пример: `from: 2021-01-01, to: 2021-01-31` составляет 31 день.	Да
Группировки	Группировка по параметрам, через запятую. Доступный список см. в таблице группировок. Например: `groupings=pid,geo`	Да
KPI	Список KPI, которые необходимо включить, каждый отделяется запятой. Список KPI приведен в таблице KPI. Пример: `kpis=installs,clicks, impressions,sessions,retention_day_7`	Да
Фильтры	Данные можно фильтровать с помощью одного или нескольких параметров фильтра.	Нет
Валюта	Чтобы получать данные с использованием валюты приложения, установите currency=preferred	Нет
Часовой пояс	Чтобы получать данные с использованием часового пояса приложения, установите timezone=preferred. Посмотреть правила локализации	Нет
Формат	По умолчанию данные ответа приходят в формате CSV. Если вы предпочитаете получать данные в формате JSON, выберите `format=json`.	Нет

Группировки

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

Группировать по Имя API	Группировать по отображаемому имени	KPI для LTV	KPI удержания	KPI активности	Protect360	Когорта
app_id (идентификатор приложения)	Идентификатор приложения	Да	Да	Да	Да	Да
pid	Медиа-источник	Да	Да	Да	Да	Да
af_prt	Агентство	Да	Да	Да	Да	Нет
c	Кампания	Да	Да	Да	Да	Да
af_adset	Группа объявлений	Да	Да	Да	Нет	Нет
af_ad	Реклама	Да	Да	Да	Нет	Нет
af_channel	Канал	Да	Да	Да	Да	Нет
af_siteid	Идентификатор издателя	Да	Да	Да	Да	Да
af_keywords	Ключевые слова	Да	Да	Да	Нет	Нет
is_primary	Is Primary Attribution (Основная атрибуция)	Да	Нет	Да	Да	Нет
af_c_id	ID кампании	Да	Нет	Да	Да	Нет
af_adset_id	ID блока рекламы	Да	Нет	Да	Нет	Нет
af_ad_id	ID рекламы	Да	Нет	Да	Нет	Нет
install_time	Время установки	Да	Да	Да*	Да	Да
attributed_touch_type (атрибутированный тип взаимодействия)	Тип взаимодействия	Да	Да	Да	Да	Нет
geo (гео)	Геоданные	Да	Да	Да	Да	Да
* В контексте KPI активности считайте время установки временем события.

KPI

KPI — это метрики, используемые для получения информации о поведении вашего приложения. KPI сгруппированы по типам на следующих вкладках.

Суммарная прибыль от пользователя (LTV) — агрегированные данные о событиях, сегментированные по дням установки и до сегодняшнего дня.

Имя API для KPI	Описание
impressions (показы)	Количество показов за выбранный промежуток времени
clicks (клики)	Количество кликов за выбранный промежуток времени
installs (установки)	Количество установок за выбранный промежуток времени
cr	Коэффициент конверсии
sessions (сеансы)	Количество сессий от пользователей, установивших приложение, за выбранный промежуток времени
loyal_users	Количество лояльных пользователей, установивших приложение, за выбранный промежуток времени
loyal_users_rate	Лояльные пользователи / Установки
cost (затраты)	Общие затраты за выбранный период времени. См. ограничения.
revenue (доход)	Доход от пользователей в течение их жизненного цикла, которые установили приложение в выбранный промежуток времени.
roi	Рентабельность инвестиций за определенный период времени
arpu_ltv	Средний доход от пользователя, для пользователей, которые установили приложение в выбранный промежуток времени.
average_ecpi	Эффективная цена за установку (eCPI) в течение определенного периода времени. Доступно только в том случае, если в вызов включены затраты и установки.
uninstalls (удаления)	Пользователи, удалившие приложение, которые установили приложение в выбранный промежуток времени.
uninstalls_rate	Процент удалений
event_counter_[event_name]	Сколько раз произошло событие
unique_users_[event_name]	Количество уникальных пользователей, выполнивших событие
sales_in_usd_[event_name]	Доход, отраженный как часть отчетных событий

Удержание является метрикой того, насколько существующие пользователи активны в вашем приложении.

Примечание.

Максимальное количество дней для удержания составляет 30 дней после установки, где день 0 — это день установки. Это означает, что значение [x] не может превышать 30.
Если вы запрашиваете retention_day_1 до того, как данные за этот день станут доступны, возвращаемая метрика будет относиться к пользователям, установившим приложение в предыдущий день. Например, 2 января вы запрашиваете retention_day_1 для пользователей, установивших 1 января. Поскольку метрика еще недоступна, возвращаемая метрика относится к пользователям, которые установили приложение 31 декабря.

KPI	Описание
retention_day_[x]	Количество удержанных пользователей в день X
retention_rate_day_[x]	Количество удержанных пользователей в день X из всего числа установивших пользователей

Активность приложения за выбранный диапазон дат.

KPI	Описание
activity_average_dau	Среднесуточное количество активных пользователей (DAU) за выбранный период времени
activity_average_mau	Среднемесячное количество активных пользователей за выбранный период времени (один день MAU представляет собой количество уникальных пользователей за предшествующие 30 дней)
activity_average_dau_mau_rate	Среднее соотношение DAU/MAU
activity_average_arpdau	Средний доход на одного активного пользователя в день — средний доход за определенный день от всех уникальных пользователей
activity_sessions	Количество сессий за выбранный промежуток времени
activity_revenue	Доход, сообщенный за выбранный промежуток времени
activity_event_counter_[event_name]	Количество событий, сгенерированных пользователями за выбранный промежуток времени
activity_sales_in_usd_[event_name]	Доход, сообщенный как часть отчетных событий за выбранный промежуток времени
activity_average_unique_users_[event_name]	Среднее количество уникальных пользователей, совершивших данное событие за выбранный промежуток времени

Когорты AppsFlyer предоставляют рекламодателям возможность просматривать и сравнивать различные метрики для нескольких когорт за разные периоды времени.

Примечание.

Ошибки округления: KPI когорты на пользователя рассчитываются с использованием четырех десятичных знаков. Это означает, что если рассчитанное значение для каждого пользователя <0,0001, оно отображается как 0. Например, количество пользователей — 100 000, а общий доход — 9 долларов. Доход на одного пользователя составляет 9/100000=0,00009. При 0,00009<0,0001 отображаемое значение будет равно 0.
Дни когорты: Максимальное количество дней в когорте составляет 90 дней после установки, где день 0 — это день установки. Значение дня когорты [x] должно находиться в диапазоне 1–90. Примечание. cohort_day_0 не поддерживается в Master API, хотя поддерживается на дэшборде когорт.
Master API, API когорты и дэшборд когорты: Результаты могут отличаться из-за различной обработки повторных установок и проблем со временем.

Сеансы

KPI

Описание

cohort_day_[x]_total_sessions_per_user

День когорты x — совокупное количество сессий на пользователя до дня x (включая день x)

cohort_day_[x]_sessions_per_user

День когорты x — сессии в день x только из когорты

cohort_[x]_days_total_sessions_per_user

Заменяет указание KPI Cohort_day_1_total_sessions_per_user на Cohort_day_x_total_sessions_per_user в URL-адресе.

Например: cohort_3_days_total_sessions_per_user (всего сессий на пользователя за три дня когорты) в URL-адресе создает 3 столбца отчета:
Cohort_day_1_total_sessions_per_user+ Cohort_day_2_total_sessions_per_user+Cohort_day_3_total_sessions_per_user

Доход

KPI	Описание
cohort_day_[x]_total_revenue_per_user	День когорты x — совокупный доход на пользователя до дня x (включая день x)
cohort_day_[x]_revenue_per_user	День когорты x — ARPU, полученный в день x только из когорты
cohort_[x]_days_total_revenue_per_user	Заменяет Cohort_day_1_total_revenue_per_user, определяющее KPI, на Cohort_day_x_total_revenue_per_user. Например: cohort_3_days_total_revenue_per_user (общий доход на пользователя за три дня когорты) в URL-адресе создает 3 столбца отчета: Cohort_day_1_total_revenue_per_user+ Cohort_day_2_total_revenue_per_user+Cohort_day_3_total_revenue_per_user
cohort_day_[x]_total_event_[eventname]_revenue_per_user	Совокупный доход на пользователя в день когорты x в зависимости от конкретного события в приложении.
cohort_day_[x]_event_[eventname]_revenue_per_user	Доход на пользователя в день когорты х в зависимости от конкретного события в приложении

События

KPI

Описание

cohort_day_[x]_total_event_[eventname]_per_user

День когорты x — совокупное количество событий на пользователя до дня x (включая день x)

cohort_day_[x]_event_[eventname]_per_user

День когорты x — события, полученные в день x только из когорты

cohort_[x]_days_total_event_[eventname]_per_user

Заменяет события, определяющие KPI, на Cohort_day_x_total_events_per_user.

Например: cohort_3_days_total_events_per_user (всего событий пользователя за три дня когорты) в URL-адресе создает 3 столбца отчета:
Cohort_day_1_total_events_per_user+ Cohort_day_2_total_events_per_user+Cohort_day_3_total_events_per_user

KPI Protect360

Описание	KPI
Установки
Всего	protect360_total_installs
Заблокировано	blocked_installs
% заблокированных	blocked_installs_rate
После атрибуции	post_attribution_installs
% после атрибуции	post_attribution_installs_rate
Общее число мошеннических установок	total_fraudulent_installs
% мошеннических установок	fraudulent_installs_rate
Ложные установки
Блокировка в реальном времени	real_time_fake_installs
Пост-атрибуционное мошенничество	post_attribution_fake_installs
Перехваченные установки
Блокировка в реальном времени	real_time_hijacked_installs
Пост-атрибуционное мошенничество	post_attribution_installs_hijacked_installs
Правила проверки
Заблокированные установки	validation_rules_blocked_installs
Заблокированная атрибуция	validation_rules_blocked_attribution
Разбивка заблокированных фальшивых установок
Черный список заблокированных идентификаторов сайтов	blocked_installs_siteid_blacklist
Пост-атрибуционный черный список идентификаторов сайтов	post_attribution_installs_siteid_blacklist
Заблокированные боты	blocked_installs_bots
Пост-атрибуционные боты	post_attribution_installs_bots
Заблокированные поведенческие аномалии	blocked_installs_behavioral_anomalies
Post-attribution behavioral anomalies (Пост-атрибуционные поведенческие аномалии)	post_attribution_installs_behavioral_anomalies
Установки, заблокированные при проверке	blocked_installs_install_validation
Разбивка заблокированных перехватов установок
Заблокированные перехваты установок	blocked_installs_install_hijacking
Перехваты установок, выявленные после атрибуции	post_attribution_installs_installs_hijacking
Заблокированные из-за отклонения CTIT	blocked_installs_ctit_anomalies
Пост-атрибуционные отклонения CTIT	post_attribution_installs_ctit_anomalies
Блокировка клик-флудинга	blocked_installs_click_flood
Клик-флудинг после атрибуции	post_attribution_installs_click_flood
Клики
Всего	protect360_total_clicks
Заблокировано	blocked_clicks
%	blocked_clicks_rate
Внутренние события приложений
Всего	protect360_total_in_apps
Заблокировано	blocked_in-app-events
%	blocked_in-app-events_rate
Признаки фермы устройств — новые устройства
Установки	install_fraud_new_devices_total
% установок	install_fraud_new_devices_total_installs_rate
% лояльных пользователей	install_fraud_new_devices_total_loyal_user_rate
Признаки фермы устройств — устройства, использующие ограничение отслеживания рекламы
Установки	install_fraud_lat_devices_total
% установок	install_fraud_lat_devices_total_installs_rate
% лояльных пользователей	install_fraud_lat_devices_total_loyal_user_rate
Признаки клик-флудинга
Коэффициент конверсии	conversion_rate
Признаки клик-флудинга — CTIT
Больше 60 минут	click_flood_over_1_hour_rate
Больше 5 часов	click_flood_over_5_hours_rate

Рассчитанные KPI

В дополнение к описанным ранее KPI в отчеты по Master API можно добавлять рассчитанные KPI. Это позволяет включать собственные отчеты в отчеты Master API.

В вычисляемые формулы KPI можно вставлять любое количество встроенных объектов KPI. Каждый объект расчета KPI включает в себя ключ и значение. Ключ — это имя, которое вы даете KPI, а значение — это формула KPI.

Поддерживаются стандартные арифметические операторы: сложение (+), закодированное как %2b, вычитание (-), умножение (*), деление (/), закодированное как %2f.

Ключи полей рассчитываемых KPI должны начинаться с «calculated_kpi_», за которым следует любая допустимая строка, например «calculated_kpi_purchaserate».

Пример

Совокупное удержание в первые три дня

kpis=installs,loyal_users_rate&calculated_kpi_3days_retention=
retention_day_1%2Bretention_day_2%2Bretention_day_3

Средний доход от показа

kpis=installs&calculated_kpi_rev_per_impression=revenue%2Fimpression

ROI за день когорты 7

kpis=installs,roi,arpu_ltv,cost,revenue&calculated_kpi_roi_day_7=
(cohort_day_7_total_revenue_per_user-average_ecpi)%2Faverage_ecpi

Фильтры (необязательно)

Параметр	Описание	Пример	Обязательно/Необязательно
pid	Используется для выбора строк, в которых отображаются указанные медиа-источники. Поддерживается множественный выбор через запятую.	pid=organic,applovin_int	Нет
c	Используется для фильтрации по названию кампании. Поддерживается множественный выбор через запятую.	c=my_sample_campaign	Нет
af_prt	Используется для фильтрации по названию агентства. Поддерживается множественный выбор через запятую.	af_prt=moburst	Нет
af_channel	Используется для фильтрации по названию канала. Поддерживается множественный выбор через запятую.	af_channel=Instagram	Нет
af_siteid	Используется для фильтрации по идентификатору издателя. Поддерживается множественный выбор через запятую.	af_siteid=12345678	Нет
geo (гео)	Используется для фильтрации по стране. Поддерживается множественный выбор через запятую.	geo=US,DE	Нет

Локальные настройки

Местная валюта и часовой пояс для конкретного приложения задаются на странице настроек приложения. Данные Master API могут извлекать данные, используя либо валюту и часовой пояс системы по умолчанию, либо часовой пояс и валюту приложения.

Применяется следующее:

Использование часового пояса/валюты конкретного приложения поддерживается только в том случае, если все приложения имеют одинаковый часовой пояс/валюту. В противном случае используются UTC и доллары США. Часовой пояс и валюта разделены. Это означает, что если валюта всех приложений одинакова, а часовые пояса — нет, то вы можете использовать валюту приложения, но не часовой пояс приложения.
Если предпочтительный часовой пояс был изменен на дэшборде в пределах запрошенного диапазона времени, созданный отчет будет содержать значения, начиная с самого последнего изменения часового пояса.

Используйте следующие параметры, чтобы выбрать настройку для конкретного приложения. Примечание. Если вы не используете предпочтительные параметры, вы получаете настройки по умолчанию: доллары США для валюты и UTC для часового пояса.

Параметр	Описание	Пример	Обязательно/Необязательно
currency (валюта)	Денежные значения указываются в валюте конкретного приложения	currency=preferred	Нет
timezone (часовой пояс)	Используемый часовой пояс соответствует часовому поясу приложения.	timezone=preferred	Нет

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

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

Специфика	Примечания
Данные о затратах	Доступность различных параметров затрат, то есть для группы объявлений, отдельного объявления, гео, канала и идентификатора сайта, зависит от рекламной сети. Чтобы получить eCPI: Если данные о затратах доступны, включите в вызов как установки, так и затраты. В целом, все источники, включая собственные медиа, которые используют ссылки AppsFlyer и содержат параметр затрат в ссылках, полностью поддерживают данные о затратах, независимо от запрошенных показателей. Сети с самостоятельной атрибуцией и собственными API обычно поддерживают данные о затратах только по некоторым доступным показателям. Например, Meta ads не поддерживает группировку по гео и каналу в одном вызове. Поддерживается группировка по любому из них отдельно. Кампании, в которых есть данные о затратах, но нет данных об установках за недавнее время (около 7 дней), недоступны через Master API.
Группировки	Конкретные группировки доступны только для KPI для LTV, активности или удержания. API возвращает значение N/A, если данные для определенного KPI недоступны. Например, запрос retention_rate_day_7 с группировкой по af_channel возвращает значение N/A.
Максимальное количество строк в отчете	200K
Название события	Master API в настоящее время не поддерживает имена событий, содержащие косую черту `/` . Чтобы преодолеть это ограничение, избегайте использования `/` в названиях событий.
Время обработки	Выбор более одного приложения увеличивает время обработки, и ответ может занять больше времени.
Диапазон дат	Детализация периода времени — ежедневно.
Агентства	Master API недоступен
Рекламные сети	Master API недоступен
Исторические данные	Данные LTV: 5 лет Данные когорты (ежедневная когорта): 2 года Данные об активности: 3 года
Ретаргетинг	Не поддерживается