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

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

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

6970_Push_API_image.png

Push API

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

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

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

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

Характеристика Подробности
Разделение сообщений на типы
  • Сообщения могут разделяться по конечных точкам (до 6 конечных точек на приложение), или тип сообщения можно определять по значениям следующих полей:
    • event_name (название события)
    • conversion_type (тип конверсии)
    • тип_кампании
  • Значения полей по каждому типу сообщений указаны в следующей таблице.

Пример:

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

  • conversion_type=install
  • campaign_type=organic
  • event_name=install

Используя таблицу, определяем, что это событие является событием установки, выполненной органическим пользователем. 
Обновление данных Сообщения отправляются вскоре после регистрации события на платформе AppsFlyer. Обычно это происходит в течение нескольких минут. 
Содержание сообщения (поля)
  • Сообщения имеют структуру key:value.
  • См. доступные поля Push API для атрибуции AppsFlyer.
  • Каждый ключ представляет собой поле с сырыми данными. См. описание полей с сырыми данными в AppsFlyer.
  • Пустые ключи и ключи со значением null не отправляются.
  • Примеры содержат пустые поля и поля с нулевым значением. В реальных постбэках нет пустых или нулевых полей. В приведенном примере используется формат JSON.
Формат полей меток времени
  • Временные метки UTC: yyyy-mm-dd hh:mm:ss.sss. Например, 2019-09-17 00:09:00.123. Событие произошло в 18:00 по токийскому времени. Время события преобразуется в UTC: 09:00. Записанное время является временем UTC.
  • Выбранные временные метки (для конкретного приложения): yyyy-mm-dd hh:mm:ss.sss±th:tm. Например: Событие произошло в 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
Ретаргетинг повторное вовлечение повторное вовлечение ретаргетинг повторное вовлечение повторная атрибуция
Ретаргетинг  События повторного вовлечения внутри приложения повторное вовлечение ретаргетинг Имена событий, определяемые рекламодателем re-engagement-in-app-event
Ретаргетинг  Повторная атрибуция  Повторные установки ретаргетинг повторная атрибуция повторная атрибуция
Привлечение пользователей  Переустановка Повторные установки

Неорганические: UA

Органические: organic

 Повторные установки
  • Повторные установки
  • organic-reinstall
Ретаргетинг События реатрибуции внутри приложения Повторные установки ретаргетинг Имена событий, определяемые рекламодателем re-attribution-in-app-event
* Некоторые установки, связанные с атрибуцией по просмотрам, атрибутируются ограниченному медиа-источнику.

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

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

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

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

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

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

Характеристика Подробности
Разделение сообщений на типы
  • Все сообщения отправляются на одну заданную вами конечную точку.
  • Чтобы определить тип сообщения, используйте поле event_type.
    Примечание. Используя поле event_type, вы также можете определить поле event_name и поле skad_redownload.
  • Значения поля event_ type указаны в следующей таблице.

Пример:

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

  • event_type: skad-re-download

Исходя из этого, мы можем определить, что:

  • Это событие повторной загрузки
  • event_name: install
  • skad_redownload: true
Обновление данных
  • Установки, повторные загрузки и внутренние события приложения:
    • Обрабатываются ежедневно
    • Отправляются на вашу конечную точку на следующий день после получения AppsFlyer постбэка iOS
    • Ожидайте сообщения о событиях с 08:00 до 11:00 UTC (точное время может меняться)
    • Пример: постбэки, полученные в понедельник, отправляются, начиная с 08:00 UTC вторника
  • Постбэки от iOS и копии постбэков: сообщения отправляются вскоре после поступления в AppsFlyer
Примеры сообщений Файл содержит примеры сообщений. В приведенном примере используется формат JSON. Пример сообщений SKAN.

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

Тип сообщения  Поле event_name Поле skad_redownload Поле event_type
Установки  Установить
  • Возможные значения: false, blank, null.
  • Если поля нет в сообщении, значением считается false. 
 skad-install
Повторные загрузки   Установить True skad-re-download
Внутренние события приложения  Название события, заданное рекламодателем Название события, заданное рекламодателем skad-in-app-event
Постбэки от iOS Недоступно в этом сообщении Иногда доступно skad_postback
Копии постбэков Недоступно в этом сообщении Иногда доступно skad-postback-copy

 

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

 Предупреждение

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

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

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

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

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

Шаг №  Атрибуция Appsflyer Атрибуция SKAdNetwork 
1

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

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

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

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

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

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

Важно! Действует механизм тайм-аута со временем ожидания 4 секунды. Если за это время AppsFlyer не получит сообщение OK, AppsFlyer будет считать это сбоем отправки сообщения. 

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

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

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

PushAPI_us-en.png

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

Нет. Настройка Подробности Используйте этот столбец для записи планируемых настроек
1 Метод POST или GET  
2 URL-адрес конечной точки -  
3 Типы сообщений о событиях
  • Выберите хотя бы один тип сообщения о событии.
  • Чтобы выбрать сообщения о событиях в приложении, необходимо зарегистрировать внутреннее событие. Без этого вы не можете выбрать сообщения о событиях в приложении. 

InappSelectionDisabled_us-en.png 

  
4
  • Поля
  • Список полей является общим для всех типов сообщений

Предупреждение

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

Выберите нужные поля.

  • Наиболее часто используемые поля уже выбраны по умолчанию.
  • Мы не отправляем пустые поля
  
5

Типы внутренних событий

 

Фильтруйте по внутренним событиям, чтобы уменьшить трафик, отправляемый на вашу конечную точку.

  • Выберите один или несколько типов событий внутри приложения. Примечание! Если событие не отображается в списке, задайте его поиск.
  • Внутреннее событие можно выбрать только после того, как оно будет зарегистрировано хотя бы один раз. При необходимости используйте S2S, чтобы инициировать событие.
  • mceclip1.png
  

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

Все члены команды, имеющие права доступа к API, могут вносить изменения в настройки Push API . Другие пользователи аккаунта могут только просматривать эти настройки.

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

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

Проверить конечную точку:

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

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

Все члены команды, имеющие права доступа к API, могут вносить изменения в настройки Push API . Другие пользователи аккаунта могут только просматривать эти настройки.

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

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

Настройка токена аутентификации

Используя токен аутентификации Push API, клиенты могут бесшовно интегрировать и защитить свои сообщения Push-API, добавив пользовательский заголовок авторизации с запрашиваемым токеном.
Вы можете настроить заголовок авторизации, который будет отправляться вместе с вашими сообщениями Push-API, определив имя и значение токена, связанные с каждым идентификатором приложения. Это гарантирует, что ваши сообщения будут не только безопасны, но и настроены под ваши конкретные требования.
 

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

Все члены команды, имеющие права доступа к API, могут вносить изменения в настройки Push API . Другие пользователи аккаунта могут только просматривать эти настройки.

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

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

  1. В AppsFlyer, на боковой панели, откройте Экспорт > Доступ к API. Прокрутите вниз до раздела Push API.
  2. Найдите конечную точку, которую нужно изменить.
  3. Внесите изменения.
  4. Нажмите Сохранить.

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

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

  1. В AppsFlyer, на боковой панели, откройте Экспорт > Доступ к API. Прокрутите вниз до раздела Push API access (Доступ к Push API). 
  2. Нажмите Удалить конечную точку.
  3. Нажмите Сохранить.
    Конечная точка удалена. 

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

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

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

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

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

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

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

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

 

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

InappSelectionDisabled_us-en.png

  • Событие приложения можно выбрать только после того, как было зарегистрировано хотя бы одно такое событие.
  • Используйте тестовое устройство, чтобы сгенерировать внутреннее событие, или 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, но не могут их изменять.
Токен аутентификации в тестовых сообщениях Заголовки тестовых сообщений не содержат токен аутентификации.

Могу ли я включить пользовательские заголовки в запрос Push API?

Нет. Push API поддерживает использование заголовка Authorization только для токенов аутентификации. Дополнительные пользовательские заголовки, такие как consumer-key, не поддерживаются.

Если вам нужно передать дополнительные параметры, включите их в URL-адрес. Например:

https://your.server.com?consumer_key=abc456

См. также