Потоковая передача сырых данных через Push API

Премиум

Для:

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

Последнее обновление: 24/08/2023 15:20

Краткий обзор. Отправляйте сырые данные о событиях атрибуции на серверные конечные точки.

Материал по теме: Сравнение инструментов доставки сырых данных | Настройка Push API с помощью API

Push API

Push API передает сырые данные, создаваемые средствами атрибуции AppsFlyer и SKAdNetwork, в виде сообщений на ваши серверы. Вы можете выбрать типы и контент сообщений и задать конечные точки.

Доступные типы сообщений, частота обновления данных и поля зависят от выполняющей атрибуцию инфраструктуры (AppsFlyer или SKAN), как описано в следующих разделах.

Сообщения атрибуции AppsFlyer

Характеристики сообщения

Характеристика	Детали
Разделение сообщений на типы	Сообщения могут разделяться по конечных точкам (до 6 конечных точек на приложение), или тип сообщения можно определять по значениям следующих полей: event_name conversion_type campaign_type Значения полей по каждому типу сообщений указаны в следующей таблице. Пример: Сообщение содержит следующие данные: conversion_type=install campaign_type=organic event_name=install Используя таблицу, определяем, что оно является событием установки, выполненной органическим пользователем.
Актуальность данных	Сообщения отправляются вскоре после регистрации события на платформе AppsFlyer. Обычно в течение нескольких минут.
Содержание сообщения (поля)	Сообщения имеют структуру `ключ:значение`. См. доступные поля Push API для атрибуции AppsFlyer. Каждый ключ представляет собой поле с сырыми данными. См. описание полей с сырыми данными в AppsFlyer. Пустые ключи и ключи со значением null не отправляются. Примеры содержат пустые поля и поля с нулевым значением. В реальных постбэках нет пустых или нулевых полей. В приведенном примере используется формат JSON. iOS. Android;
Формат полей меток времени	Метки времени UTC: `гггг-мм-дд чч:мм:сс.ссс`. Например, `2019-09-17 00:09:00.123`. Событие произошло в 18:00 по токийскому времени. Время события преобразуется в UTC: 09:00. Регистрируется время UTC. Временные метки выбранного часового пояса (для конкретного приложения): `гггг-мм-дд чч:мм:сс.ссс±th:tm`. Например, `2019-09-17 18:00:16.000+0900`. Событие произошло в 18:00 по токийскому времени. Показанное время события регистрируется как 18:00+09:00. 09:00 — обозначение часового пояса Токио.

Доступные типы сообщений

Контекст атрибуции	Тип сообщения	Поле conversion_type	Поле campaign_type	Поле event_name	Поле event_type
Привлечение пользователей	Установка*	установка	Неорганический: UA Органические: organic	установка	установка organic-install
Привлечение пользователей	События внутри приложения при установке	установка	Неорганический: UA Органические: organic	Имена событий, определяемые рекламодателем	install-in-app-event organic-install-in-app-event
Ретаргетинг	повторное вовлечение	повторное вовлечение	retargeting	повторное вовлечение	повторное вовлечение
Ретаргетинг	События повторного вовлечения внутри приложения	повторное вовлечение	retargeting	Имена событий, определяемые рекламодателем	re-engagement-in-app-event
Ретаргетинг	Реатрибуция	Повторные установки	retargeting	Реатрибуция	Реатрибуция
Привлечение пользователей	Повторные установки	Повторные установки	Неорганический: UA Органические: organic	Повторные установки	Повторные установки organic-reinstall
Ретаргетинг	События реатрибуции внутри приложения	Повторные установки	retargeting	Имена событий, определяемые рекламодателем	re-attribution-in-app-event
* Некоторые установки, связанные с атрибуцией по просмотрам, атрибутируются ограниченному медиа-источнику.

Уникальные поля

Отображаемое имя	Название Push API
Выбранная валюта*	selected_currency
Выручка в выбранной валюте	revenue_in_selected_ валюта
Затраты в выбранной валюте	cost_in_selected_ валюта
Время загрузки на устройство согласно выбранному часовому поясу	device_download_time_selected_timezone
Время атрибутированного взаимодействия согласно выбранному часовому поясу	attributed_touch_time_selected_timezone
Время установки согласно выбранному часовому поясу	install_time_selected_ часовой пояс
Время события согласно выбранному часовому поясу	event_time_selected_ часовой_пояс
Выбранный часовой пояс(*)	selected_timezone
*Это настройка уровня приложения, действующая на момент отправки сообщения API.

Сообщения атрибуции SKAN

В этом разделе описаны сообщения (типы отчетов), доступные для SKAN, и способы их идентификации. Ознакомившись с содержимым этого раздела, переходите к теме Настройка конечной точки для атрибуции SKAN.

Материал по теме: Поля сырых данных SKAN. Сообщения Push API имеют аналогичную структуру и поля.

Характеристики сообщений

Характеристика

Детали

Разделение сообщений на типы

Все сообщения отправляются на одну заданную вами конечную точку.
Чтобы определить тип сообщения, используйте следующие поля:
- event_name
- skad_redownload
Значения полей по каждому типу сообщений указаны в следующей таблице.

Пример:

Сообщение содержит следующие данные:

event_name: install
skad_redownload: true

По skad_redownload: true можно определить, что это событие повторной загрузки.

Актуальность данных

Установки, повторные загрузки и внутренние события приложения:
- Обрабатываются ежедневно
- Отправляются на вашу конечную точку на следующий день после получения AppsFlyer постбэка iOS
- Ожидайте сообщения о событиях с 05:00 до 08:00 UTC (точное время может меняться)
- Пример: постбэки, полученные в понедельник, отправляются, начиная с 05:00 UTC вторника
Постбэки от iOS и копии постбэков: сообщения отправляются вскоре после поступления в AppsFlyer

Примеры сообщений

Файл содержит примеры сообщений. В приведенном примере используется формат JSON. Примеры сообщений SKAN.

Типы сообщений для атрибуции SKAN

Тип сообщения	Поле event_name	Поле skad_redownload	Поле event_type
Установки	установка	Возможные значения: false, blank, null. Если поля нет в сообщении, значением считается false.	Установки SKAD
Повторные загрузки	установка	true	Повторные загрузки SKAD
In-App Events (Внутренние события приложения)	Имя события, заданное рекламодателем	Имя события, заданное рекламодателем	События в приложении SKAD
Постбэки от iOS	Недоступно в этом сообщении	Иногда доступно	Постбэки SKAD
Копии постбэков	Недоступно в этом сообщении	Иногда доступно	Копии постбэков SKAD

Определение типа сообщения атрибуции SKAN

Примечание. Это не относится к сообщениям постбэков, которые поступают непосредственно из iOS.

Настройка конечных точек Push API

Внимание

Не используйте Push API для отправки данных атрибуции AppsFlyer третьим сторонам, поскольку:

Вы можете нарушить законы о конфиденциальности, такие как GDPR, если пользователь сообщил о своем нежелании передавать данные третьим сторонам.
Некоторые медиа-источники ограничивают использование предоставляемых ими данных уровня пользователя, передачу таких данных третьим сторонам, или и то, и другое. Убедитесь, что вы соблюдаете условия использования медиа-источников,
например, Twitter, Snapchat, Pinterest.

Примечание. Это предупреждение не распространяется на данные SKAN. Для отправки данных SKAN на сторонние конечные точки используйте Push API.

Чтобы настроить Push API, выполните следующий список действий.

Чек-лист по настройке Push API

Шаг

Атрибуция Appsflyer

Атрибуция SKAdNetwork

Если у вас уже есть активная конечная точка Push API, этот шаг можно пропустить.

Заполните требования к серверу.

Для атрибуции AppsFlyer планируйте настройки конечных точек с помощью чек-листа для планирования Push API.

Не применимо

Настройка конечной точки для атрибуции AppsFlyer

Настройка конечной точки для атрибуции SKAdNetwork

Требования к серверу (ваш сервер)

Убедитесь, что ваш сервер соответствует следующим требованиям:

Требования к серверу

URL-адрес конечной точки	Действительное доменное имя Максимальное количество уникальных конечных точек на приложение: AppsFlyer: 6 конечных точек SKAdNetwork: 3 конечные точки
Ответный код конечной точки	После получения сообщения конечная точка должна вернуть код состояния HTTP 200.
Список одобренных серверов AppsFlyer	Для обеспечения связи с конечной точкой занесите IP-адреса серверов AppsFlyer в разрешенный список ваших межсетевых экранов и систем безопасности.
Версии TLS	TLS 1.1 TLS 1.2+. См. поддерживаемые шифры
Порты	Порты: 80, 443

Чек-лист планирования Push API для атрибуции AppsFlyer

Используйте этот чек-лист для планирования настроек конечных точек AppsFlyer. Цифры на рисунке соответствуют номерам строк в чек-листе.
Этот раздел неактуален для атрибуции SKAdNetwork. См. раздел Настройка атрибуции SKAdNetwork.

Конечная точка

Таблица планирования конечных точек

Нет.	Настройки	Детали
1	Метод	POST или GET
2	URL-адрес конечной точки	-
3	Типы сообщений о событиях	Выберите хотя бы один тип сообщения о событии. Чтобы выбрать сообщения о событиях в приложении, необходимо зарегистрировать внутреннее событие. Без этого вы не можете выбрать сообщения о событиях в приложении.
4	Поля Список полей является общим для всех типов сообщений	Предупреждение Если отметить пункт Выбрать все, то вновь добавленные поля также будут автоматически выбраны. Во избежание проблем убедитесь, что вы можете поддерживать все автоматически добавляемые в схему новые поля. Выберите нужные поля. Наиболее часто используемые поля уже выбраны по умолчанию. Мы не отправляем пустые поля
5	Типы внутренних событий	Фильтруйте по внутренним событиям, чтобы уменьшить трафик, отправляемый на вашу конечную точку. Выберите один или несколько типов событий внутри приложения. Внимание! Если событие не отображается в списке, задайте его поиск. Если вы выберете все, новые внутренние события приложения будут добавляться автоматически. Внутреннее событие можно выбрать только после того, как оно будет зарегистрировано хотя бы один раз. При необходимости используйте S2S, чтобы инициировать событие.

Настройка конечной точки для атрибуции AppsFlyer

Примечание. Только владелец аккаунта AppsFlyer может изменять настройки Push API. Другие пользователи аккаунта могут только просматривать эти настройки.

Чтобы добавить конечную точку атрибуции AppsFlyer:

Перейдите в раздел Интеграция > Доступ к API. Прокрутите вниз до раздела Push API.
Нажмите Добавить конечную точку.
Выберите метод HTTP: POST или GET
Введите URL-адрес конечной точки. Если вы получили сообщение «Этот URL-адрес небезопасен», свяжитесь со службой поддержки AppsFlyer.
Выберите один или несколько типов событий. Примечание. Если сообщения о внутренних событиях отключены, значит, пока не было записано ни одного внутреннего события.
Выберите поля, которые нужно включить в сообщение Push API. Внимание:
- Всегда отправляются обязательные поля: идентификатор приложения, имя события, время события, IDFA (iOS) или Advertising ID (Android)
- Чтобы выбрать дополнительные поля, используйте элементы управления, изображенные на рисунке ниже.
  - Наиболее часто используемые поля уже выбраны по умолчанию. Вы можете отменить их выбор.
  - Выберите нужные вам дополнительные поля.
  - Выберите Очистить все , чтобы очистить все дополнительные поля.
  - Мы не отправляем пустые поля и связанный с ними ключ. Просим учесть это при планировании ваших процессов импорта/анализа.
Выберите одно или несколько (до 52) событий или Все события в приложении.
- Список заполняется типами событий, которые уже зарегистрированы. Если какое-то событие отсутствует, отправьте событие такого типа с помощью тестового устройства.
Нажмите Сохранить.
Push API активен. Данные о конверсиях отправляются на конечную точку.
Проверьте конечную точку в соответствии с описанной ниже процедурой.

Чтобы проверить конечную точку:

Нажмите Отправить тест.
Сообщение с результатом теста появится под кнопкой Отправить тест.
Тестовое сообщение отправлено на конечную точку. Если тест пройдет неудачно, проверьте, внесены ли IP-адреса AppsFlyer в список разрешенных.
Внимание! Действует механизм тайм-аута со временем ожидания 2 секунды. Если за это время AppsFlyer не получит сообщение OK, AppsFlyer будет считать это сбоем отправки сообщения.
Проверьте, получено ли тестовое сообщение конечной точкой.
Смотреть копию отправленного сообщения.

Настройка конечной точки для атрибуции SKAdNetwork

Чтобы добавить конечную точку SKAdNetwork для Push API:

Перейдите в раздел Интеграция > Доступ к API. Прокрутите вниз до раздела Push API.
Выберите SKAdNetwork в качестве субъекта, выполняющего атрибуцию.
Нажмите Добавить конечную точку.
Примечание. Можно задать 1–3 конечные точки SKAdNetwork на приложение.
Выберите метод HTTP: POST или GET
Введите URL-адрес конечной точки. Если вы получили сообщение «Этот URL-адрес небезопасен», свяжитесь со службой поддержки AppsFlyer.
Мы не отправляем пустые поля и связанный с ними ключ. Просим учесть это при планировании ваших процессов импорта/анализа.
Нажмите Сохранить.
Push API активен. Данные отправляются на конечную точку.

Дополнительные процедуры: управление конечными точками

Изменение конечной точки

Чтобы изменить настройки конечной точки:

Выберите в разделе Интеграция пунктДоступ к API.Прокрутите вниз до раздела Push API.
Найдите конечную точку, которую нужно изменить.
Внесите изменения.
Нажмите кнопку Save (Сохранить).

Удаление конечной точки

Чтобы удалить конечную точку:

Выберите в разделе Интеграция пункт Доступ к API. Прокрутите вниз до раздела «Доступ к Push API».
Нажмите Удалить конечную точку.
Нажмите кнопку Сохранить.
Конечная точка удалена.

Поиск и устранение неполадок, особенности и ограничения

Ошибка тестового сообщения

Если вы не получили тестовое сообщение, и доступ к вашим серверам органичен по IP-адресу, проверьте, что все IP-адреса AppsFlyer внесены в разрешенный список.

Повторяющиеся события ретаргетинга в приложении

События ретаргетинга в приложении дублируются, когда событие покупки происходит как часть кампании ретаргетинга во время окна повторного вовлечения UA. Это сделано, чтобы атрибутировать доход как медиа-источнику UA, так и медиа-источнику ретаргетинга.

Вы будете получать дублированные события, только если активированы одновременно:

События внутри приложения при установке
События ретаргетинга внутри приложений.

Выявление и дедупликация внутренних событий приложения

Выбор сообщений о событиях приложения отключен

Событие приложения можно выбрать только после того, как было зарегистрировано хотя бы одно такое событие.
Используйте тестовое устройство, чтобы сгенерировать внутреннее событие, или S2S API, чтобы сделать это вручную.

Отсутствующие push-сообщения и CloudFront

Вы используете Amazon CloudFront в качестве конечной точки? Если да, проверьте, не отклоняет ли CloudFront сообщение с кодом 421. Если это так, обратитесь к статье Как CloudFront отрабатывает запросы HTTPS.

Сообщения об ошибках конечных точек

Признак: сообщение этот URL-адрес небезопасен отображается при установке URL-адреса конечной точки.

Требуется действие: обратитесь в службу поддержки AppsFlyer; сообщите идентификатор приложения, URL-адрес конечной точки и приложите скриншот с сообщением об ошибке.

Спецификации и ограничения

Спецификация	Заметки
Рекламным сетям	Недоступно
Агентства	Не доступно
Часовой пояс приложения	Поддерживается
Валюта приложения	Поддерживается
Ограничения на размер	Не применимо
Органическая	Да
Неорганические	Да
Актуальность данных	Непрерывно
Исторические данные	Не поддерживаются. Если вам не хватает данных, используйте Pull API, чтобы получить нужные данные. В случае SKAN некоторые исторические данные можно получить через Data Locker (ограничено окном доступности Data Locker).
Доступ владельца аккаунта / пользователей	Только владелец аккаунта AppsFlyer может изменять настройки Push API. У каждого аккаунта AppsFlyer есть только один владелец аккаунта. Это первый пользователь AppsFlyer (созданный при открытии аккаунта). Другие пользователи аккаунта могут просматривать настройки Push API, но не могут их изменять.