API межсерверных событий

  • Разработчики

Введение

Этот API предназначен для передачи событий, которые происходят вне мобильного приложения, или же происходят внутри приложения, но не передаются через SDK AppsFlyer. Например, если у вас есть два интерфейса — мобильный и веб, в AppsFlyer вы можете регистрировать все события, происходящие в обеих средах.

 Примечание

В качестве типа контента необходимо указывать application/json.

URL:https://api2.appsflyer.com/inappevent/{app_id}

Пример для Android:https://api2.appsflyer.com/inappevent/com.appsflyer.myapp

Пример для iOShttps://api2.appsflyer.com/inappevent/id123456789

Обратите внимание, что в iOS идентификатор App ID должен иметь префикс id. В противном случае событие не будет зарегистрировано, несмотря на то, что кодом ответа на запрос будет HTTPS 200 OK.

 Важно!

Максимальный размер полезных данных в формате JSON не должен превышать 1 KБ.

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

Полезные данные JSON должны обязательно содержать параметр "af_events_api": "true".
Этот параметр обеспечивает структурирование события как комплексного, что дает возможность выполнятьавтоматическое сопоставление значений события с событиями различных партнеров.

См. приведенные ниже примеры.

Метод: POST

Заголовок - "authentication"= {dev-key}

Для просмотра ключа разработчика выберите Панель управления >> Настройки приложения >> Ключ разработчика

iOSAndroid
{
  "appsflyer_id": {AppsFlyer Device ID }, // e.g. 1415211453000-6513894
  "idfa":{idfa},
  "customer_user_id": {customer_user_id}, // Customer User ID optional parameter
  "bundle_id":{bundle_id},
  "eventName": {The event name}, // e.g. "af_purchase"
  "eventValue": {A JSON containing a rich in-app event value - must be stringfied},
  "{

    \"af_revenue\":\"6\",
    \"af_content_type\":\"wallets\",
    \"af_content_id\":\"15854\"

  }",
  "eventCurrency": {Event currency}, // e.g "USD"
  "ip": {device IP},
  "eventTime": {Event timestamp in UTC +0}, // e.g "2014-05-15 12:17:00.000"
  "af_events_api" :"true"
}

 Примечание

Перед формированием URI все зарезервированные символы (https://tools.ietf.org/html/rfc3986#section-2.1) необходимо перекодировать в %-представления.

Параметры

  1. Обязательные параметрыappsflyer_id (AppsFlyer Device id), eventName, eventValue и af_events_api
  2. Настоятельно рекомендуемые параметры: idfa для iOS и advertising_id для Android.
    Если вы планируете сопоставлять свои внутренние события в приложении, инициированные органическими пользователями, с внешними партнерами, эти параметры ОБЯЗАТЕЛЬНЫ. Кроме того, некоторые функции, такие как Audiences (Аудитории), классифицируют пользователей и обновляют сети на основе идентификаторов устройств.
  3. Необязательный параметр: eventValue — может иметь пустое значение, которое вводится как "eventValue":"" (без пробела)
  4. Необязательный параметр: IP-адрес (ip) — должен соответствовать IP-адресу мобильного устройства (в момент события)
  5. Необязательный параметр: поле идентификатора клиента (customer_user_id) — это идентификатор пользователя, сопоставленный с полем идентификатора клиента (Customer User ID) в отчетах необработанных данных. API Customer User ID в составе SDK автоматически прикрепляет данное значение ко всем внутренним событиям приложения уровня SDK. Для использования этой функции убедитесь, что это поле включено во ВСЕ межсерверные (S2S) события.

Подготовка данных для параметров

Логическая схема на стороне сервера необходима для того, чтобы получить определенные значения для вышеперечисленных параметров. Ниже приведен рекомендуемый порядок получения этих значений:

Сопоставление идентификатора AppsFlyer ID с идентификатором клиента

Идентификатор AppsFlyer — это обязательный параметр при отправке внутренних событий от сервера к серверу. Простой способ сопоставления пользователей с выполненными ими событиями приведен ниже.

  1. Задайте идентификатор клиента при установке приложения пользователем.
  2. Загрузите отчет о необработанных данных для установок посредством экспорта данных или с помощью API Pull.
  3. Получите идентификатор AppsFlyer, сопоставляя идентификатор клиента в своих внутренних системах с идентификатором клиента в отчете о необработанных данных.
  4. Сопоставьте идентификатор AppsFlyer с идентификатором клиента во внутренних системах (важно для использования в будущем).

Сопоставив идентификатор AppsFlyer с идентификатором клиента во внутренних системах, можно легко определить пользователя, выполнившего определенное событие. Затем вы сможете получить идентификатор AppsFlyer и другие значения (значение события, валюту события, время события и т. д.) и отправить внутреннее событие приложения от сервера к серверу.

Регистрация времени событий

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

Для указания времени возникновения события (в часовом поясе UTC +0) можно использовать дополнительный параметр eventTime . Если данный параметр не включен в сообщение, AppsFlyer будет использовать метку времени из полученного HTTPS-сообщения . 

Формат eventTime: "гггг-ММ-дд ЧЧ:мм:сс.ССС" (например, "2014-05-15 12:17:00.000"). Когда события отправляются с временными метками, то они будут записаны с метками реального времени (т.е с фактическим временем события) в том случае, если их отправить в AppsFlyer до 02:00 (UTC +0) следующего дня.

События с метками прошедшего времени, не отправленные до 02:00, записываются с указанием фактического времени отправки.

Событие с временной меткой, отправленное до 02:00 UTC +0

Время возникновения события: 2 мая, 22:00

Время отправки события на серверы AppsFlyer: 3 мая, 01:00

Событие регистрируется на платформе AppsFlyer с фактическим временем возникновения (2 мая, 22:00).

Событие с временной меткой, отправленное после 02:00 UTC +0

Время возникновения события: 2 мая, 22:00

Время отправки события на серверы AppsFlyer: 4 мая, 09:00

Событие регистрируется на платформе AppsFlyer с временем отправки на серверы AppsFlyer, а не с временем возникновения (4 мая, 09:00).

События с метками будущего времени

События, отправляемые с метками будущего времени, всегда записываются в AppsFlyer с временем отправки в AppsFlyer, а не с временем события, которое указано в полезных данных.

Регистрация времени событий — визуальная временная шкала

Server-to-Server-Events.PNG

 Примечание

Максимальное количество межсерверных (S2S) запросов составляет 60000 в минуту или 1000 в секунду. Если ваши требования отличаются, обратитесь к вашему менеджеру.

Ответные коды с сервера

200
OK, запрос был обработан системой AppsFlyer.
401
unauthorized, ключ, указанный в заголовке аутентификации, не является ключом разработчика (dev-key) для данного приложения.
400
ошибка запроса при ошибке как минимум по одному из критериев валидации
500
Internal server error, указывает на возникновение ошибки на сервере

Если серверы защищены брандмауэром, для получения ответных сообщений необходимо разблокировать входящие ответы для диапазонов IP-адресов AWS .

Пример тела запроса

{
  "appsflyer_id": "1415211453000-6513894",
	"advertising_id": "38412345-8cf0-aa78-b23e-10b96e40000d",
	"eventName": "af_purchase",
	"eventValue": 
	"{
		\"af_revenue\": \"6\",
		\"af_content_type\": \"wallets\",
		\"af_content_id\": \"15854\",
		\"af_quantity\" :\"1\"
   }",
	"eventCurrency": "USD",
	"ip": "1.2.3.4",
	"eventTime": "2014-05-15 12:17:00.000",
	"af_events_api" :"true"
}


В этом случае AppsFlyer получает межсерверное (S2S) внутреннее событие, которое представляет собой покупку с доходом, вместе с дополнительными свойствами, например, тип контента и пр.

Особые случаи

Отправка данных об отрицательной выручке

Если нужно отправить событие с отрицательным доходом (для таких событий, как отмена покупки или получение компенсации), для параметра выручки можно задать отрицательное значение. Например:

{
  "appsflyer_id": "1415211453000-6513894",
	"advertising_id": "38412345-8cf0-aa78-b23e-10b96e40000d",
	"eventName": "cancel_purchase",
	"eventValue": 
	"{
		\"af_revenue\": \"-6\",
		\"af_content_type\": \"wallets\",
		\"af_content_id\": \"15854\",
		\"af_quantity\" :\"1\"
   }",
	"eventCurrency": "USD",
	"ip": "1.2.3.4",
	"eventTime": "2014-05-15 12:17:00.000",
	"af_events_api" :"true"
}

Отправка событий без значения события

Если нужно отправить событие без значения события, просто передайте в качестве значения события пустую строку: "event_value":""

Теперь AppsFlyer может отправлять подобные rich in-app события медиа источникам для улучшения таргетинга, оптимизации и создания аудитории соответственно настройкам рекламодателя.

Получение AppsFlyer Device ID

В сообщениях межсерверных событий параметр appsflyer_id является обязательным. AppsFlyer использует данный параметр для атрибуции события исходному устройству и атрибутированному медиа источнику. 

Есть несколько способов получения этого ID.

  1. От мобильного устройства с помощью API SDK AppsFlyer (Android / iOS)
  2. С помощью Pull или Push API (см. по ссылкам дополнительные сведения об Push API и Pull API)
  3. Путем экспорта отчета необработанных данных об установках

 Совет

Если при тестировании межсерверных (S2S) сообщений используются необработанные данные или API Pull или Push, выполните поиск записи с медиа-источником "s2s_test". Это ваше тестовое устройство, а его идентификатор AppsFlyer Device — это необходимый ID.

Разница между органическими и неорганическими событиями

При отправке S2S-событий приложения AppsFlyer автоматически связывает с этими событиями дополнительные данные. Эти дополнительные данные поступают из события установки, которое предшествует внутренним событиям приложения. 

Это означает, что некоторые данные, которые AppsFlyer связывает с неорганическими S2S-событиями, не будут связаны с органическими S2S-событиями в приложении.

 Пример

Например, если сравнить отчеты о необработанных данных для неорганических и органических S2S-событий, можно заметить, что неорганические события содержат данные, которых нет в органических событиях.

Неорганические внутренние события приложения содержат данные о медиа-источнике, кампании, типе и времени атрибуции перехода по ссылке.

Что касается органических событий приложения, то они происходят после органической установки. При органической установке отсутствуют данные о кампании, медиа-источниках или типе и времени атрибуции перехода по ссылке.

Была ли эта статья полезной?
Пользователи, считающие этот материал полезным: 4 из 12