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

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

4409_Push_API_V2-01.pngPush API V2.0

 Описание Push API

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

Объем данных, отправляемый на конечные точки, можно уменьшить, ограничив:

  • Тему сообщения и выбранные типы внутренних событий
  • Выбранные поля.

Другие решения AppsFlyer для доставки данных, которые могут вас заинтересовать:

Типы сообщений о событиях

Доступные типы сообщений о событиях
(✓ = доступно, - = не применимо)

Тип атрибуции

Тема

Поле conversion_type

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

(поле campaign_type)

Органический (поле campaign_type)
Привлечение пользователей Установка(*) установка UA Органика
Привлечение пользователей  События внутри приложения при установке установка UA Органика

Ретаргетинг

повторное вовлечение повторное вовлечение Ретаргетинг -
Ретаргетинг События повторного вовлечения внутри приложения повторное вовлечение Ретаргетинг -
Ретаргетинг Реатрибуция Повторные установки Ретаргетинг -
Привлечение пользователей  Повторные установки Повторные установки UA Органика
Ретаргетинг События реатрибуции внутри приложения Повторные установки Ретаргетинг -
* Некоторые установки, связанные с атрибуцией по просмотрам, атрибутируются ограниченному медиа-источнику.

Структура сообщения и уникальные поля

Сообщение Push API зависит от используемого HTTP-метода:

  • GET: параметры данных добавляются в строку URL
  • POST: параметры данных содержатся в теле сообщения в формате JSON
  • Примеры ниже содержат пустые поля. В будущем мы планируем прекратить отправку пустых полей. 

Доступные поля

  • Сообщения Push API содержат описанные здесь поля.
  • Дополнительные поля будут добавляться время от времени, по мере того, как они добавляются в платформу AppsFlyer. Ваши механизмы импорта/парсинга должны это принимать во внимание. 

Формат полей меток времени:

  • Для полей меток времени в UTC формат таков: yyyy-mm-dd hh:mm:ss.sss. К примеру, время отображается как 2019-09-17 00:09:25.123 Событие произошло в 14:00 по токийскому времени. Время события преобразуется в UTC, которое равно 05:00. Записанное время является временем UTC. 
  • Для полей меток времени в выбранном часовом поясе формат таков: yyyy-mm-dd hh:mm:ss.±th:tm. Например, 2019-01-20 04:51:16.000+0000 Событие произошло в 14:00 по токийскому времени. Показанное время события записывается как 14:00+09:00. 09:00 — это часовой пояс Токио. 
Уникальные поля Push API (по сравнению с другими инструментами доставки данных)
Отображаемое имя V2.0 имя Заметки 
Выбранная валюта selected_currency Это настройка уровня предложения, действующая на момент отправки сообщения API.
Выручка в выбранной валюте 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.

Настройка Push API

 Внимание

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

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

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

Список действий Push API
№ действия  Чтобы настроить новую конечную точку
1

Заполните чек-лист требований на стороне сервера

2

Запланируйте настройки конечной точки в соответствии с чек-листом планирования

3

Настройте конечную точку

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

Убедитесь, что ваш сервер соответствует перечисленным здесь требованиям.

Требования к серверу
URL-адрес конечной точки
  • Действительное доменное имя
  • Одну и ту же конечную точку можно использовать для каждого приложения только один раз. 
  • Максимальное количество конечных точек на приложение: 6
Ответный код конечной точки После получения сообщения конечная точка должна вернуть код состояния HTTP 200.
Список одобренных серверов AppsFlyer

Для обеспечения связи с конечной точкой занесите IP-адреса серверов AppsFlyer в разрешенный список ваших межсетевых экранов и систем безопасности.

Версии TLS
Порты 

Порты: 80, 443

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

  • Используйте этот чек-лист для планирования настроек конечной точки. Цифры на рисунке соответствуют номерам строк в чек-листе.

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

PushAPI_us-en.png

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

Нет.

Настройки

Детали Ваши настройки
1

Метод

POST или GET  

2

URL-адрес конечной точки

-  
3 Типы сообщений о событиях
  • Выберите хотя бы один тип сообщения о событии.
  • Чтобы выбрать сообщения о событиях в приложении, необходимо зарегистрировать внутреннее событие. Без этого вы не можете выбрать сообщения о событиях в приложении.

InappSelectionDisabled_us-en.png

 

4

Поля

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

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

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

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

 

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

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

 

Настройка и управление конечными точками

  • В этом разделе описаны процедуры, позволяющие добавлять, тестировать, изменять и удалять конечные точки.
  • Только администратор может изменять настройки API, члены команды могут их просматривать.
AppsFlyerAdmin_us-en.pngЧтобы добавить конечную точку Push API:
  1. Перейдите в раздел Интеграция > Доступ к API. Прокрутите вниз до раздела Push 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. Проверьте конечную точку в соответствии с описанной ниже процедурой.
  10. Если вы хотите получать события, атрибутированные Facebook, нужно принять  условия пользования Facebook. 

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

  1. Нажмите Send Test (Отправить тест). 
    Тестовое сообщение о результате будет показано под кнопкой Send Test (Отправить тест) 
    Тестовое сообщение отправлено на конечную точку. Если тест пройдет неудачно, проверьте, что вы внесли IP-адреса AppsFlyer в разрешенный список
  2. Проверьте, что конечная точка получила тестовое сообщение.
    Затем следует копия отправленного сообщения

Проверьте сообщения POST и GET API

В качестве тестового отправляется следующее сообщение POST

{                  
  "idfv": "123456789",
  "device_category": "phone",
  "af_sub1": "sub1-12345",
  "customer_user_id": "Customer User ID",
  "is_lat": null,
  "contributor_2_af_prt": "attributionagency",
  "bundle_id": "bundleIdentifier_test",
  "gp_broadcastreferrer": "",
  "contributor_2_touch_time": "2019-12-31 00:05:42.805",
  "contributor_3_touch_type": "click",
  "event_source": "SDK",
  "af_cost_value": "10",
  "contributor_1_match_type": "id_matching",
  "app_version": "app_version",
  "contributor_3_af_prt": "attributionagency",
  "custom_data": null,
  "contributor_2_touch_type": "click",
  "gp_install_begin": "2019-12-31 00:07:14.000",
  "city": "Redmond",
  "amazon_aid": "9173fe74-0578-4658-a461-ebb0b4fce6d6",
  "gp_referrer": "af_tranid=000712-31122019254604&pid=pdsagency_int&c=pushapi_v2",
  "af_cost_model": "CPI",
  "af_c_id": "cid12345",
  "attributed_touch_time_selected_timezone": "2019-12-31 00:06:32.891+0000",
  "selected_currency": "EUR",
  "app_name": "com.pds.pushapi2.v2.transparent.com",
  "install_time_selected_timezone": "2019-12-31 00:07:14.961+0000",
  "postal_code": "98052",
  "wifi": false,
  "install_time": "2019-12-31 00:07:14.961",
  "operator": "ORANGE",
  "attributed_touch_type": "click",
  "af_attribution_lookback": "25d",
  "keyword_match_type": null,
  "af_adset_id": "adset12345",
  "device_download_time_selected_timezone": "2019-12-31 00:07:14.961+0000",
  "contributor_2_media_source": "contrib2",
  "contributor_2_match_type": "id_matching",
  "api_version": "2.0",
  "attributed_touch_time": "2019-12-31 00:06:32.891",
  "revenue_in_selected_currency": null,
  "is_retargeting": false,
  "country_code": "US",
  "gp_click_time": "2019-12-31 00:07:12.000",
  "contributor_1_af_prt": "attributionagency",
  "match_type": "id_matching",
  "appsflyer_id": "e126a3b3-3406-4196-a964-563c9ae44ff8",
  "dma": "819",
  "http_referrer": "https://www.amazon.com/gp/bestsellers/gift-cards/ref=sv_gc_0",
  "af_sub5": "sub5-12345",
  "af_prt": "attributionagency",
  "event_revenue_currency": null,
  "store_reinstall": null,
  "install_app_store": null,
  "media_source": "pdsagency_int",
  "deeplink_url": null,
  "campaign": "pushapi_v2",
  "af_keywords": "keywords12345",
  "region": "NA",
  "cost_in_selected_currency": "1000",
  "event_value": null,
  "ip": "20.168.174.166",
  "oaid": null,
  "event_time": "2019-12-31 00:07:14.961",
  "is_receipt_validated": null,
  "contributor_1_campaign": "camp1",
  "af_sub4": "sub4-12345",
  "imei": null,
  "contributor_3_campaign": "camp3",
  "event_revenue_usd": null,
  "af_sub2": "sub2-12345",
  "original_url": "https://app.appsflyer.com/com.pds.pushapi2.v2.transparent.com?c=pushapi_v2&pid=pdsagency_int&clickid=click12345&af_ref=000632-31122019&advertiserId=9173fe74-0578-4658-a461-ebb0b4fce6d6&android_id=3e06b4caebc19356&sha1_android_id=sha12345&af_siteid=136396&af_sub_siteid=sub_siteid12345&af_c_id=cid12345&af_adset=adset12345&af_adset_id=adset12345&af_ad=ad12345&af_ad_id=adid12345&af_ad_type=adtype12345&af_channel=channel12345&af_keywords=keywords12345&is_retargeting=False&af_dp=ebay%3A%2F%2Fshoppingcart&af_web_dp=www.dp.com&af_sub1=sub1-12345&af_sub2=sub2-12345&af_sub3=sub3-12345&af_sub4=sub4-12345&af_sub5=sub5-12345&af_cost_model=CPI&af_cost_value=10&af_cost_currency=EUR&sha1_advertising_id=sha12345&sha1_el=sha12345&af_installpostback=false&af_force_dp=true&af_chrome_lp=true&af_ec=1&af_click_lookback=25d&af_viewthrough_lookback=1h&af_reengagement_window=2d&af_prt=attributionagency",
  "contributor_2_campaign": "camp2",
  "android_id": "3e06b4caebc19356",
  "contributor_3_media_source": "contrib3",
  "af_adset": "adset12345",
  "af_ad": "ad12345",
  "state": "WA",
  "network_account_id": null,
  "device_type": "Samsung::SH-220",
  "idfa": null,
  "retargeting_conversion_type": null,
  "af_channel": "channel12345",
  "af_cost_currency": "EUR",
  "contributor_1_media_source": "contrib1",
  "keyword_id": null,
  "device_download_time": "2019-12-31 00:07:14.961",
  "contributor_1_touch_type": "click",
  "af_reengagement_window": "2d",
  "af_siteid": "136396",
  "language": "English",
  "app_id": "com.pds.pushapi2.v2.transparent.com",
  "contributor_1_touch_time": "2019-12-31 00:06:07.847",
  "event_revenue": null,
  "af_ad_type": "adtype12345",
  "carrier": "carrier",
  "event_name": "install",
  "af_sub_siteid": "sub_siteid12345",
  "advertising_id": "9173fe74-0578-4658-a461-ebb0b4fce6d6",
  "os_version": "6.0",
  "platform": "android",
  "af_sub3": "sub3-12345",
  "contributor_3_match_type": "id_matching",
  "selected_timezone": "UTC",
  "af_ad_id": "adid12345",
  "contributor_3_touch_time": "2019-12-31 00:05:17.757",
  "user_agent": "Dalvik/1.6.0 (Linux; U; Android 6.0; Redmi Note 4 Build/KOT49I.F320S22g",
  "is_primary_attribution": null,
  "sdk_version": "v4.8.0",
  "event_time_selected_timezone": "2019-12-31 00:07:14.961+0000"
}

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

AppsFlyerAdmin_us-en.png Чтобы изменить настройки конечной точки: 

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

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

AppsFlyerAdmin_us-en.pngЧтобы удалить конечную точку:

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

Миграция конечной точки с версии 1.0 на версию 2.0

AppsFlyerAdmin_us-en.pngЧтобы перенести конечную точку с версии 1.0 на версию 2.0:

  1. Перейдите в раздел Интеграция > Доступ к API. Прокрутите вниз до раздела Push API.
    Откроется раздел Push API.
  2. Отметьте конечную точку для миграции.
  3. Выберите поля, которые нужно включить в сообщение Push API.
    • Всегда отправляются обязательные поля: идентификатор приложения, имя события, время события, IDFA (iOS) или Advertising ID (Android)
    • Чтобы выбрать дополнительные поля, используйте элементы управления, изображенные на рисунке ниже.

      PushAPIFieldSelect1.jpg

      • Наиболее часто используемые поля выбраны по умолчанию. Их можно убрать.
      • Выберите нужные вам дополнительные поля.
      • Выберите Очистить все , чтобы очистить все дополнительные поля.
      • В ближайшем будущем мы перестанем пересылать пустые поля и связанный с ними ключ. Просим учесть это при планировании ваших процессов импорта/анализа.
  4. Выберите одно или несколько (до 52) событий или Все события в приложении.
    • Список заполняется типами событий, которые уже зарегистрированы. Если какое-то событие отсутствует, отправьте событие такого типа с помощью тестового устройства.
  5. Нажмите кнопку Сохранить
    • Push API был мигрирован. 
    • Данные о конверсии по-прежнему отсылаются на конечную точку.

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

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

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

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

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

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

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

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

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

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

События в приложении, атрибутированные медиа-источнику UA (события установки в приложении) в рамках кампании ретаргетинга имеют значение поля is_primary_attribtuion=false. 

Пример

  • Пользователь устанавливает приложение example_app, которое атрибутируется сети ua_network
  • Затем пользователь повторно взаимодействует с ретаргетинговой кампанией example_app в сети retar_network и совершает покупку.

Событие покупки внутри приложения отправляется дважды со следующими параметрами:

Поля события ретаргетинга внутри приложения
Тип события Медиа-источник is_retargeting re_targeting conversion_type is_primary_
attribution
События внутри приложения при установке ua_network true повторное вовлечение или реатрибуция  false
События ретаргетинга внутри приложений. retar_network true повторное вовлечение или реатрибуция  true


Как идентифицировать дубликаты событий ретаргетинга?

Булево поле is_primary_attribution идентифицирует первичные и вторичные медиа-источники в кампаниях по ретаргетингу:

  • False: идентифицирует исходный медиа-источник UA. Примечание: Это единственный сценарий, в котором значение равно false.
  • True: идентифицирует медиа-источник повторного вовлечения 

Причина такова: если пользователь в результате кампании ретаргетинга участвует в кампании, открывается окно повторного вовлечения. Медиа-источник повторного вовлечения рассматривается как основной медиа-источник, когда окно повторного вовлечения открыто, а источник UA — как вторичный. После закрытия окна исходный медиа-источник UA вновь становится первичным. 

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

InappSelectionDisabled_us-en.png

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

Отсутствующие данные Facebook

По умолчанию Facebook не передает необработанные данные уровня пользователя, пока вы не примете Условия использования Facebook.

Когда вы примете условия, данные пользовательского уровня, поступающие от Facebook и других источников необработанных данных, отправляются через Push API.

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

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

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

Особенности
Специфика Заметки 
Рекламным сетям Не для использования в рекламных сетях. 
Агентства Не для использования агентствами
Часовой пояс приложения Поддерживается
Валюта приложения  Поддерживается
Ограничения на размер Не применимо
Органическая  Да
Неорганические Да
Актуальность данных Непрерывно 
Исторические данные Не поддерживается. Данные о событии отправляются после того, как будет сконфигурирован Push API. Если вам нужны исторические данные, используйте Pull API. 
Доступ члена команды Члены команды могут просматривать настройки Push API, но не могут их изменять.
Была ли эта статья полезной?