Push API V2.0 — отчеты о событиях атрибуции в реальном времени

Краткий обзор: Отправляйте данные о событиях атрибуции на конечные точки на стороне сервера в реальном времени. Используйте эти данные в ваших ИТ-системах.

4409_Push_API_V2-01.png Push API V2.0

Новости Push API

  • Push API V2.0 соответствует спецификации необработанных данных AppsFlyer V5.0.
    • Дополнительные поля: Добавлено более 40 новых полей. По мере добавления на платформу новых полей, они быстро добавляются в Push API V2.0.
    • Выбор полей: Выбирайте, какие поля нужно отправлять, чтобы сократить размер сообщений Push API.
    • Фильтрация событий в приложении: Выбирайте отправляемые внутренние события, чтобы облегчить обработку данных.
  • Push API V1.0 устарел и выводится из эксплуатации 31 августа 2020 года.
  • Руководство разработчика по миграции с Push API V1.0 на Push API V2.0

 Описание Push API

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

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

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

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

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

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

Тип кампании

Тип конверсий

значение is_
retargeting

значение retargeting_

conversion_

Тип

Неорганические Органика Ретаргетинг
Привлечение пользователей установка false    -
Привлечение пользователей  События внутри приложения при установке false    -

Ретаргетинг

повторное вовлечение true   - -
Ретаргетинг События повторного вовлечения внутри приложения true повторное вовлечение - -
Ретаргетинг Реатрибуция true Реатрибуция - -
Ретаргетинг События реатрибуции внутри приложения true Реатрибуция -

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

Сообщение 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_
выбранный_часовой_пояс
 
Часовой пояс времени установки install_time_selected_
часовой пояс
 
Часовой пояс времени события event_time_selected_
часовой_пояс
 
Выбранный часовой пояс selected_timezone Это настройка уровня предложения, действующая на момент отправки сообщения API.

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

Поле Push API V2.0 Отображаемое имя Push API Комментарии
advertising_id ID рекламы  
af_ad реклама  
af_ad_id ID рекламы.  
af_ad_type Тип рекламы  
af_adset Блок рекламы  
af_adset_id ID блока рекламы  
af_attribution_lookback Окно атрибуции  
af_c_id ID кампании  
af_channel Канал  
af_cost_currency Валюта расходов  
af_cost_model Модель затрат  
af_cost_value Величина затрат  
af_keywords Ключевые слова  
af_prt Партнер  
af_reengagement_window Окно повторного вовлечения  
af_siteid ID сайта  
af_sub_siteid ID субсайта  
af_sub1 Cубпараметр 1  
af_sub2 Cубпараметр 2  
af_sub3 Cубпараметр 3  
af_sub4 Cубпараметр 4  
af_sub5 Cубпараметр 5  
amazon_aid Идентификатор Amazon Fire  
android_id Android ID  
api_version Версия API  
app_id Идентификатор приложения  
app_name Имя приложения  
app_version Версия приложения  
appsflyer_id Идентификатор AppsFlyer ID  
attributed_touch_time Attributed Touch Time (Атрибутированное время касания)  
attributed_touch_time_selected_timezone Часовой пояс времени атрибутированного касания Специфично для Push API
attributed_touch_type Attributed Touch Type (Атрибутированный тип касания)  
bundle_id Идентификатор пакета  
campaign Кампания  
carrier carrier  
city city  
contributor_1_af_prt Партнер ассистента 1  
contributor_1_campaign Кампания ассистента 1  
contributor_1_match_type Тип содействия ассистента 1  
contributor_1_media_source Исходная точка взаимодействия ассистента 1  
contributor_1_touch_time Время касания ассистента 1  
contributor_1_touch_type Тип касания ассистента 1  
contributor_2_af_prt Партнер ассистента 2  
contributor_2_campaign Кампания ассистента 2  
contributor_2_match_type Тип содействия ассистента 2  
contributor_2_media_source Исходная точка взаимодействия ассистента 2  
contributor_2_touch_time Время касания ассистента 2  
contributor_2_touch_type Тип касания ассистента 2  
contributor_3_af_prt Партнер ассистента 3  
contributor_3_campaign Кампания ассистента 3  
contributor_3_match_type Тип содействия ассистента 3  
contributor_3_media_source Исходная точка взаимодействия ассистента 3  
contributor_3_touch_time Время касания ассистента 3  
contributor_3_touch_type Тип касания ассистента 3  
cost_in_selected_currency Затраты в выбранной валюте Специфично для Push API
country_code Код страны  
custom_data Пользовательские данные  
customer_user_id Идентификатор клиента  
deeplink_url Deep Link URL (URL-адрес глубинной ссылки) Доступно с первого квартала 2020 года
device_category Категория устройства  

device_download_time 

Время скачивания на устройство До 3 февраля 2020 года доступно также дополнительное поле download_time. 
device_type Тип устройства  
dma DMA  
device_download_time_selected_timezone Часовой пояс времени скачивания

Специфично для Push API

До 3 февраля 2020 года доступно также дополнительное поле download_time_selected_timezone.

event_name Имя события  
event_revenue Выручка от события  
event_revenue_currency Валюта выручки от событий  
event_revenue_usd Выручка от события в USD  
event_source Источник события  
event_time Event Time (Время события)  
event_time_selected_timezone Часовой пояс времени события Специфично для Push API
event_value Значение события  
gp_broadcast_referrer Инициатор GP Broadcast  
gp_click_time Время нажатия Google Play  
gp_install_begin Время начала установки Google Play  
gp_referrer Google Play Referrer  
http_referrer Источник ссылки HTTP  
idfa IDFA  
idfv IDFV  
imei imei  
install_app_store Магазин приложений, использованный для установки  
install_time Install Time (Время установки)  
install_time_selected_timezone Часовой пояс времени установки Специфично для Push API
ip IP  
is_LAT Is LAT Доступно с IV квартала 2019 года
is_primary_attribution Is Primary Attribution (Является основной атрибуцией)  
is_receipt_validated Проверено ли получение  
is_retargeting Is Retargeting (Является ретаргетингом)  
keyword_id ID ключевого слова  
keyword_match_type Тип сопоставления ключевых слов  
language language  
match_type Тип сопоставления  
media_source Медиа-источник  
network_account_id Идентификатор учетной записи сети  
oaid OAID  
operator operator  
original_url Original URL (Исходный URL-адрес)  
os_version Версия ОС  
platform Платформа  
postal_code Почтовый индекс  
Регион Регион  
retargeting_conversion_type Retargeting Conversion Type (Тип конверсии ретаргетинга)  
revenue_in_selected_currency Выручка в выбранной валюте Специфично для Push API
sdk_version Версия SDK  
selected_currency Выбранная валюта Специфично для Push API
selected_timezone Выбранный часовой пояс Специфично для Push API
Состояние Состояние  
store_reinstall (False=Скачать, True=Скачать заново) Переустановка из магазина приложений  
user_agent Агент пользователя  
wifi wifi  

Настройка 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

Типы событий

 Внимание!

Если вы фильтруете по внутренним событиям приложения, то есть не отмечаете опцию Select All (Выбрать все), то вам нужно добавлять новые внутренние события вручную. Это не относится к опции Select All (Выбрать все).

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

  • Можно выбрать до 52 внутренних событий или опцию Select All (Выбрать все).Это значит, что если у вас есть более 52 внутренних событий и вы хотите выбрать более 52, то нужно отметить опцию Select All (Выбрать все).
  • Внутреннее событие можно выбрать только после того, как оно будет зарегистрировано хотя бы один раз.
  • Если у вас более 52 событий, можно использовать поиск событий.mceclip1.png

 

Facebook Намереваетесь ли вы отправлять данные пользователей, атрибутированных Facebook?

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

 

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

  • В этом разделе описаны процедуры, позволяющие добавлять, тестировать, изменять и удалять конечные точки.
  • Члены команды могут просматривать настройки Push API, но не могут их изменять.
Чтобы добавить конечную точку Push API:
  1. Перейдите в раздел Integration (Интеграция) > API Access (Доступ к API).Прокрутите вниз до раздела Push API.
    Откроется раздел Push API.
  2. Нажмите Добавить конечную точку. 
  3. Выберите метод HTTP: POST или GET
  4. Введите URL-адрес конечной точки. 
  5. Выберите один или несколько типов событий. Внимание! Если сообщения о внутренних событиях отключены, значит, пока не было записано ни одного внутреннего события.
  6. Выберите поля, которые нужно включить в сообщение Push API. Внимание:
    • Всегда отправляются обязательные поля: идентификатор приложения, имя события, время события, IDFA (iOS) или Advertising ID (Android)
    • Чтобы выбрать дополнительные поля, используйте элементы управления, изображенные на рисунке ниже.

      PushAPIFieldSelect1.jpg

      • Наиболее часто используемые поля выбраны по умолчанию. Их можно убрать.
      • Выберите нужные вам дополнительные поля.
      • Снимите галочку с опции Select all (Выбрать все), чтобы очистить все дополнительные поля.
  7. Выберите до 52 внутренних событий или отметьте Select All (Выбрать все).
    • Внимание! Если вы не отметили Select All  (Выбрать все), нужно добавлять внутренние события приложения вручную. 
    • Список заполняется типами событий, которые уже зарегистрированы. Если какое-то событие отсутствует, отправьте событие такого типа с помощью тестового устройства.
  8. Нажмите Сохранить
    Push API активно
    Данные преобразования отправляются на конечную точку.
  9. Проверьте конечную точку в соответствии с описанной ниже процедурой.
  10. Если вы хотите получать события, атрибутированные Facebook, нужно принять  условия пользования Facebook. 

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

  1. Нажмите Отправить тест. 
    Тестовое сообщение о результате будет показано под кнопкой Отправить тест 
    Тестовое сообщение отправлено на конечную точку.
  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"
}

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

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

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

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

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

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

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

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

События ретаргетинга в приложении дублируются, когда событие покупки происходит как часть кампании ретаргетинга во время окна повторного вовлечения 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, но не могут их изменять.
Была ли эта статья полезной?