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

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

Введение

Цель этого API — передача событий, которые происходят вне мобильного приложения, непосредственно на сервер 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}

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

iOS Android
{
    "appsflyer_id": {This is a mandatory field, AppsFlyer Device ID must be used },  // например 1415211453000-6513894
    "idfa":{idfa},
    "customer_user_id": {customer_user_id}, // необязательный параметр Customer User ID
    "bundle_id":{bundle_id},
    "eventName": {The event name}, // например "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}, // например "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. Если вы планируете сопоставлять свои внутренние события в приложении, инициированные органическими пользователями, с событиями внешних партнеров, эти параметры ОБЯЗАТЕЛЬНЫ. 
  3. Необязательный параметр: eventValue — может иметь пустое значение, которое вводится как "eventValue":"" (без пробела)
  4. Необязательный параметр: IP-адрес (ip) — должен соответствовать IP-адресу мобильного устройства (в момент события)
  5. Необязательный параметр: поле идентификатора клиента (customer_user_id) — это идентификатор пользователя, сопоставленный с полем идентификатора клиента (Customer User ID) в отчетах необработанных данных. API Customer User ID в составе SDK автоматически прикрепляет данное значение ко всем внутренним событиям приложения уровня SDK. Для использования этой функции убедитесь, что это поле включено во ВСЕ межсерверные (S2S) события.

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

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

 Важно!

Пакетный режим не означает отправку в одном запросе объединенного набора полезных данных для всех событий. Пакетный режим — это массовая отправка отдельных межсерверных запросов. Каждый запрос должен содержать свой набор полезных данных.

Если отправить запрос с полезными данными в формате JSON, включающими несколько событий, сервер возвращает код ошибки 400 вместе с сообщением об ошибке "Payload is missing or failed to parse" (Полезные данные отсутствуют, или ошибка при их анализе).

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

Формат eventTime: "гггг-ММ-дд ЧЧ:мм:сс.ССС" (например, «2014-05-15 12:17:00.000»)  

Чтобы при отправке событий в пакетном режиме они были зарегистрированы со своей собственной отметкой реального времени, их необходимо отправить в AppsFlyer до 02:00 (UTC) следующего дня.   

 Примечание

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


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

Пример 1

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

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

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

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

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

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

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

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

Если серверы защищены брандмауэром, для получения ответных сообщений необходимо разблокировать входящие ответы для диапазонов 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 из 10