API межсерверных событий для мобильных устройств (мобильный S2S)

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

S2S_us-en.png

API межсерверных событий для мобильных устройств

Платформа AppsFlyer атрибутирует и записывает события мобильных приложений, отправленных через SDK AppsFlyer и по API. Используйте API S2S для сообщения о событиях, происходящих вне приложения; например, пользователь продлевает свою подписку, используя ваш веб-интерфейс. После регистрации события S2S доступны на всей платформе, включая дэшборды, сырые данные и аналитику. Для веб-событий PBA см. Web S2S для PBA.

AppsFlyer заполняет события S2S следующими значениями:

  • Значения, отправленные в сообщении S2S
  • Некоторые значения атрибуции установок AppsFlyer, например, время установки и медиа-источник.

Инструкции по использованию API

Создайте свой вызов API, используя информацию, содержащуюся в следующих разделах. 

Факты о S2S API

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

https://api2.appsflyer.com/inappevent/app_id

  • app_id: Идентификатор приложения, используемый в дэшборде AppsFlyer. Вставьте его именно в том виде, в каком отображается на дэшборде.
  • Для приложений для iOS: убедитесь, что имеется префикс id .В противном случае будет получен действительный код возврата 200 OK, но событие не будет зарегистрировано.
  • Windows: получите ID приложения из Microsoft App Store.
  • Пример для Android: https://api2.appsflyer.com/inappevent/com.appsflyer.myapp
    iOS:https://api2.appsflyer.com/inappevent/id123456789
    Windows:https://api2.appsflyer.com/inappevent/a1b2c3d4e5f6
HTTP-метод POST
Принятый тип контента application/json
Авторизация

--header 'authentication: dev_key'

  • dev_key — это токен аутентификации в заголовке. 
  • Чтобы получить ключ разработчика, в AppsFlyer перейдите в   App Settings (Настройки приложения) > Dev Key (Ключ разработчика)
Серверы в разрешенном списке для получения ответных сообщений

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

Ограничение размера JSON 

Размер файла JSON: до 1 KB

Ограничение предоставления данных

Объем ограничения POST: 60 000 POST в минуту. Чтобы повысить этот лимит, обратитесь к своему менеджеру по работе с клиентами.

Инструкции по программированию
Кодирование URL

Закодируйте зарезервированные процентом символы (https://tools.ietf.org/html/rfc3986#section-2.1) перед формированием URL метода. 

TLS

Используйте TLS 1.2 или выше. Поддерживаемые шифры

Факты о S2S API

Параметры полезных данных

  • В параметры полезных данных входят один или несколько идентификаторов устройств (в зависимости от ОС).
  • Что делать, если я не могу отправить идентификатор устройства?
    • Иногда нельзя отправить идентификатор по не зависящим от вас обстоятельствам. Например, потому что пользователь ограничил отслеживание рекламы (LAT) или использует iOS 14 и не дал согласие на ATT (не предоставляет данные IDFA).
    • В таком случае вам нужно учесть, что если не  отправлять идентификатор рекламы/устройства, то может возникнуть ошибка атрибуции, то есть AppsFlyer не сможет атрибутировать событие медиа-источнику. При этом события регистрируются и отображаются в отчетах и на дэшбордах. 
Операционные системы Имя идентификатора Описание

iOS.

iconAFios.png

 

idfa 

Когда доступно, введите IDFA устройства.

Формат: строка

Например: "idfa": "9876F1SS-2983-3855-27RR-2R626772VFNB"

idfv

Когда доступно, введите IDFV устройства.

Формат: строка
Пример: "idfv": "95C9BD22-4A4C-41C8-9548-ED07C5C8C145"

Android;

iconAFand.png

advertising_id

Когда доступно, введите GAID устройства (рекламный ID)

Формат: строка

Например: "advertising_id": "9c9a82fb-d5de-4cd1-90c3-527441c11828"

oaid

Формат: строка

Например: "oaid": "1fe9a970-efbb-29e0-0bdd-f5dbbf751ab5"

amazon_aid

Формат: строка

imei

Формат: строка

Например: "imei": "AA-BBBBBB-CCCCCC-D"

Идентификаторы устройств
Имя параметра Обязательный Описание

appsflyer_id

Да

Уникальный идентификатор, генерируемый AppsFlyer при первом запуске приложения. 

  • Формат: строка
  • Например: "appsflyer_id": "1415211453000-6513894"

customer_user_id

Нет

Идентификатор клиента, уникальный идентификатор пользователя, заданный владельцем приложения.

  • Формат: строка. 
  • Например: "customer_user_id": "my_customer_number1234" 

att

Нет

iOS Статус авторизации ATTrackingManager

  • Если версия ОС устройства - iOS 14 или новее, заполните att значением ATTrackingManager.
    • Формат: однозначное целое число
    • Пример: 1
  • Значения iOS для ATTrackingManager:
    • 0: не определено
    • 1: ограничено
    • 2: отказано
    • 3: Авторизовать

Внимание! 

  • В рамках политики конфиденциальности Apple мы рекомендуем вам заполнить att значением ATTrackingManager.
  • Вы можете отправить этот параметр до официального выпуска iOS 14; мы начнем его обработку после официального выпуска.

 

ip

Нет

IP-адрес мобильного устройства во время события.

  • Если его отправить, то IP-адрес подставляется в поля с геоданными.
  • Если параметр не отправлять, то AppsFlyer заполняет поля IP-адреса и геоданных значениями из события атрибуции установки.
  • Формат: строка, содержащая адрес IPV4 или IPV6
  • Например: "ip": "192.0.2.1
af_events_api Устаревшее
  • Не рекомендуется с 6 июля 2020 г.
  • В этом параметре нет необходимости, вы можете прекратить его отправлять. Это никоим образом не влияет на атрибуцию.

eventName

Да

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

  • Формат: строка
  • Например: "eventName": "af_purchase"

Значение события

Да

If you send an event without a value then send: "eventValue":""

  • Значения события необходимо отправлять без дополнительных символов или форматирования.
  • Для af_revenue может быть использована десятичная запятая. Перед отрицательными значениями нужно ставить знак -
  • Формат: строка в JSON
  • Например: "eventValue": "{ \"af_revenue\": \"6\", \"af_content_type\": \"wallets\", \"af_content_id\": \"15854\", \"af_quantity\" :\"1\" }"

app_version_name

Нет

Версия вашего приложения или идентификатор.

  • Формат: строка
  • Например: "app_version_name": "my_app_version"

app_store

Нет

Эквивалентно AF_STORE в приложениях для Android. Магазин, из которого было скачано приложение. 

  • Поле в отчете по сырым данным: установить App Store
  • Формат: строка
  • Например: my_android_store_is_best

Event Time (Время события)

Нет

Время, когда произошло событие, используя часовой пояс UTC.

  • По умолчанию: если eventTime не отправляется, время устанавливается на время прибытия HTTP-сообщения.
  • Формат: строка yyyy-mm-dd hh:mm:ss.sss время должно быть указано по часовому поясу UTC.
  • Например: "eventTime":"2019-05-15 12:17:01.123" означает 12:17:01 UTC. 

Закрытие дня:

  • Если вы используете eventTime,  событие должно поступить в AppsFlyer не позже 02:00 следующего дня. Например, если событие произошло в понедельник в 17:00 UTC, оно должно поступить на серверы AppsFlyer не позднее 02:00 UTC вторника. 
  • События, полученные после закрытия дня, отмечаются по времени прибытия.
  • События, имеющие будущее время, то есть после времени прибытия, отмечаются по времени прибытия. 

Пример

  • Время указывается по UTC
  • Событие отправлено с параметром eventTime = понедельник 21:00.
Время прибытия Время, записанное AppsFlyer Пояснение
Вторник 01:00 Понедельник 21:00 Прибыл до закрытия дня.
Среда 09:00  Среда 09:00 Прибыл после закрытия дня. Время установлено на время прибытия. 

eventCurrency

Нет

Код валюты с использованием 3-символьных кодов ISO 4217 и BCN (биткойн)

  • По умолчанию: USD
  • Например: "eventCurrency": "ZAR"

bundleIdentifier

Нет

Уникальный идентификатор приложения В сырых данных параметр заполняет идентификатор пакета.

  • Формат: строка
  • Например: "bundleIdentifer": "com.myapp"

sharing_filter

Нет

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

Используйте фильтр для соблюдения нормативных требований, таких как GDPR и CCPA, для реализации механизмов отказа пользователей от предоставления данных и по другим причинам бизнес-логики. 

У sharing_filter есть следующие параметры:

  • all: Все партнеры заблокированы. Не делитесь этим событием ни с кем.  Пример: "sharing_filter": "all"
  • Список идентификаторов партнеров в массиве. Формат ["partnerid_1", "partnerid_2", "partnerid_n"]  Пример: "sharing_filter": ["googleadwords_int", "adcolony_int"]

Чтобы получить список идентификаторов партнеров, обратитесь к вашему CSM или в службу поддержки AppsFlyer.

custom_dimension

Нет

Reserved for AppsFlyer future use

app_type

Нет

For iOS apps.

Permitted value: app_clip

If the user event takes place in an app_clip, send the parameter. In all other cases don't send the parameter.

Пример curl

curl --location --request POST 'https://api2.appsflyer.com/inappevent/<app_id_placeholder>' \
--header 'authentication: <dev_key_placeholder>
' \
--header 'Content-Type: application/json' \
--data-raw '{
  "appsflyer_id": "9999999999999-9999999999999999999",
	"advertising_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
	"customer_user_id" : "example_customer_id_123",
	"ip": "199.0.2.1",
	"app_version_name" : "example_version_name",
	"eventTime" : "2020-02-25 12:00.000",
	"eventName": "af_purchase",
	"eventCurrency": "ZAR",
	"eventValue": 
	"{
		\"af_revenue\": \"1006\",
		\"af_content_type\": \"wallets\",
		\"af_content_id\": \"15854\",
		\"af_quantity\" :\"1\"
   }"
}
'

Коды ответа

Код ответа  Сообщение Способ устранения
200 OK

При получении сообщения выполняется минимальная валидация данных. Таким образом, вы можете получить ответ ОК, даже если событие не будет полностью записано в AppsFlyer. Для отладки событий:

  • Используя пример CURL в этой статье
    • Обновите идентификатор приложения и детали ключа разработчика.
    • Измените параметры appsflyer_id и eventTime. Используйте текущее время и appsflyer_id, недавно атрибутированный как неорганический.
  • Отправьте запрос.
    • Вы должны получить сообщение 200 OK.
    • Проверьте, правильно ли записано событие, включая доход
    • При необходимости внесите дополнительные изменения и повторите тестирование.
400 Failed to Authenticate Убедитесь, что ключ аутентификации правильный.
400 appsflyer_id is a mandatory field
  •  Убедитесь, что данные в формате JSON содержат правильный идентификатор AppsFlyer ID.
  • Убедитесь, что данные JSON преобразованы в строки и правильно отформатированы.
401 Не авторизовано Когда ключ, предоставленный в заголовке аутентификации, не является ключом <dev_key> для этого приложения.
400 Bad request

Когда запрос не прошел как минимум один из критериев валидации.

400 Payload is missing or failed to parse
  • Убедитесь, что данные JSON преобразованы в строки и правильно отформатированы.
  • Если полезные данные JSON содержат более одного события. Отправляйте только по одному событию в каждом запросе.
500  Internal Server Error  Убедитесь, что данные JSON преобразованы в строки и правильно отформатированы.
 

Тестирование

Рассмотрим:

  • Для тестирования используйте идентификатор AppsFlyer для неорганической установки, чтобы тестировать атрибуты событий в реальном времени. Органические события атрибутируются с задержкой в несколько часов.
  • Некоторые поля события заполняются с использованием события атрибуции установки пользователем. Например, время установки и медиа-источник. 

Чтобы атрибутировать тестовое устройство как неорганическую установку:

  1. Подготовьте настраиваемую ссылку атрибуции для тестирования сообщений S2S. Установите для параметра медиа-источника в ссылке значение s2s_test. Например: &pid=s2s_test 
  2. Регистрация тестового устройства
  3. Удалите приложение с тестового устройства.
  4. Отправьте ссылку на тестовое устройство.
  5. Щелкните ссылку.
  6. Установите и запустите приложение.
  7. На дэшборде проверьте, что установка атрибутирована.
  8. Получите AppsFlyer ID для использования в вашем сообщении S2S.

Чтобы отправить тестовое сообщение S2S:

  1. Подготовьте сообщение S2S, используя назначенный идентификатор AppsFlyer. См. ниже примеры кода.
  2. Отправьте сообщение.
  3. Выполните одно из следующих действий, чтобы увидеть, как сообщение записывается в AppsFlyer:
  4. Проверьте и просмотрите, что:
    • Значения, отправленные в сообщении S2S, правильно заполняют отчет. Обратите особое внимание на поля «Дата события», «Валюта события», «Доход от события» и «Значение события».
    • Источник атрибуции и время установки заполняются AppsFlyer.
    • Значения, предоставляемые самим SDK, такие как версия SDK, не заполняются.

Пример кода для отправки сообщений S2S

JavaPythonNode JSC#PHPGo
/* using the okhttp package 
install from maven https://mvnrepository.com/artifact/com.squareup.okhttp3/okhttp */
import okhttp3.*;
import java.io.IOException;

public class SendRequest {
  public static void main(String[] args) {

    OkHttpClient client = new OkHttpClient();
    MediaType mediaType = MediaType.parse("application/json");

    RequestBody body = RequestBody.create(mediaType, "" +
        "{\r\n\t\"appsflyer_id\": \"<APPS_FLYER_ID>\"," +
        "\r\n\t\"customer_user_id\": \"123456\",\r\n\t\"eventName\": \"af_purchase\",\r\n\t\"" +
        "eventValue\": \"{\\\"af_revenue\\\":\\\"6\\\" ,\\\"af_content_id\\\":\\\"15854\\\"}\",\r\n\t\"" +
        "eventCurrency\": \"USD\",\r\n\t\"" +
        "eventTime\": \"2018-08-10 4:17:00.000\",\r\n\t\"");

    Request request = new Request.Builder()
        .url("https://api2.appsflyer.com/inappevent/<APP_ID>")
        .post(body)
        .addHeader("Content-Type", "application/json")
        .addHeader("authentication", "<YOUR_DEV_KEY>")
        .build();

    try {
      Response response = client.newCall(request).execute();
      System.out.println(response.code());
      System.out.println(response.body().string());
    } catch (IOException e) {
      e.printStackTrace();
    }
  }
}

Отправка рекламного идентификатора / идентификатора устройства важна

  • Рекламный идентификатор / идентификатор устройства является обязательным для отправки постбэков в сети SRN, такие как Facebook и Google Ads. Если вы не можете отправить идентификатор, примите во внимание, что нельзя отправлять постбэки.
  • Если вы отправите только идентификатор AppsFlyer, внутренние события приложения будут записываться и атрибутироваться правильно.

Заполнение параметров

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

Когда AppsFlyer обрабатывает события S2S в приложении, поля атрибуции заполняются с помощью идентификатора AppsFlyer, чтобы определить соответствующее событие установки, которое предшествовало событиям в приложении.

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

 Пример

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

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

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

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

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

  • Идентификатор AppsFlyer является обязательным и используется для атрибуции событий.
  • Он генерируется, когда пользователь впервые устанавливает мобильное приложение.
  • Чтобы вы могли сопоставить свой CUID с идентификатором AppsFlyer, вам нужно установить CUID в приложении. 

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

  • Задайте идентификатор клиента при установке приложения пользователем.
  • Отчеты по сырым данным AppsFlyer содержат CUID и идентификатор AppsFlyer. Используйте один из инструментов доставки данных или AppsFlyer Push API. 
  • Используйте отчеты о сырых данных, чтобы сопоставить CUID с идентификатором AppsFlyer. 
  • Идентификаторы AppsFlyer можно получить с помощью SDK AppsFlyer, интегрированных в ваши приложения (Android / IOS).
  • Сопоставьте идентификатор AppsFlyer с идентификатором клиента во внутренних системах (важно для использования в будущем).

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

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

{
  "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"
}


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

Получение идентификатора AppsFlyer ID

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

 Совет

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

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

События с отрицательным значением дохода могут быть отправлены. Например, если покупка была отменена. Параметр af_revenue может иметь отрицательные значения для записи этого события.

Если вы заполняете af_quantity, возможно, вы захотите заполнить его отрицательным значением в зависимости от логики вашей системы. AppsFlyer не использует af_quantity.

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

{
	"eventName": "cancel_purchase",
	"eventValue": 
	"{
		\"af_revenue\": \"-6\",
		\"af_content_type\": \"wallets\",
		\"af_content_id\": \"15854\",
		\"af_quantity\" :\"1\"
   }",
	"eventCurrency": "USD",
	
}

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

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

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

Устранение неполадок

События не отображаются в дэшборде

  • Конечная точка: убедитесь, что используемая конечная точка верна.
  • Убедитесь, что полезные данные содержат обязательные параметры. См. здесь.
  • Убедитесь, что AppsFlyer ID, используемый для запуска события, является действительным идентификатором appsflyer_id, который установлен в конкретном приложении. Что это не тестовый идентификатор, представленный в документации. См. здесь.
  • Для S2S-событий групповая отправка событий в одном запросе S2S не поддерживается. Каждое событие необходимо отправлять отдельно. 
  • На обзорном дэшборде диапазон дат относится к дате установки приложения (LTV), а не к дате события.
    • Убедитесь, что вы ввели правильный диапазон дат.
    • Убедитесь, что диапазон дат на дэшборде соответствует дате установки устройства (appsflyer_id), а не дате события.
  • Отчет по сырым данным о событиях: диапазон дат относится к дате события, а не дате установки. 

События не содержат доход

Если после отправки S2S-событий окажется, что данные о доходе не записаны, убедитесь, что отправленные данные в формате JSON преобразованы в строки. Самое важное — это значение параметра события в формате JSON. Он должен быть преобразован в строку, как показано на следующем примере.

"{\"af_revenue\":\"6\" ,\"af_content_type\":\"wallets\"}"

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

Значения дохода не должны быть отформатированы каким-либо образом. Они могут содержать десятичный разделитель, но это не обязательно. Не используйте знаки/коды валют или разделители ,. Доход может иметь префикс -

  • Пример допустимых значений: 123 , -123.45123.456 
  • Примеры недопустимых значений: 1,234.561,234

В событиях S2S заполнены не все поля

Поля сырых данных заполняются с использованием значения, отправленного в вызове S2S, а некоторые поля заполняются с помощью события установки.  Аналогичное поведение, но не идентичное, наблюдается для событий в приложении, сообщаемых с помощью AppsFlyer SDK. Существуют некоторые различия, в частности, следующие поля не заполняются для событий S2S:

  • wifi
  • operator
  • language
  • Тип устройства
  • Категория устройства
  • Версия приложения: используйте app_version_name.
  • Имя приложения
Была ли эта статья полезной?