Аудитории — API дополнительных идентификаторов

Для:
маркетологов разработчиков
Последнее обновление:

Вкратце: Используйте API дополнительных идентификаторов аудиторий для массовой загрузки идентификаторов пользователей из ваших внутренних систем (таких как бизнес-аналитика и CRM) в AppsFlyer Аудитории, что позволяет более активно взаимодействовать с аудиториями соответствующих партнеров, используя эти идентификаторы.

Об API 

API дополнительных идентификаторов аудитории позволяет добавлять следующие идентификаторы пользователей из ваших внутренних систем в аудитории AppsFlyer:

  • До 2 хешированных адресов электронной почты
  • Хешированный номер телефона
  • Хешированный номер телефона в формате E164

После этого вы можете отправить эти идентификаторы своим партнерам по аудитории (при условии, что ваша политика идентификаторов пользователей на уровне учетной записи позволяет это), что позволит им более точно определять ваши целевые аудитории. Обратите внимание, что не все рекламные партнеры поддерживают все виды идентификаторов.

Когда следует использовать этот API?

Этот API предназначен для использования, когда необходимо загрузить большой объем данных идентификаторов. Обычно это данные, собранные за продолжительный период времени (например, хешированные адреса электронной почты всех пользователей приложения за последние 12 месяцев). Для обновления идентификаторов с конкретных устройств в реальном времени настройте дополнительные идентификаторы в AppsFlyer SDK (пакет средств разработки ПО) или S2S-мобильный API.

Важно!

Шифрование: Все значения дополнительных идентификаторов должны быть зашифрованы с использованием хеширования SHA256. Незашифрованные идентификаторы не будут обработаны.

Время: Для обеспечения точного сопоставления идентификаторов API дополнительных идентификаторов аудитории можно использовать уже на следующий день после отчета ключевых идентификаторов через AppsFlyer SDK (UTC). Например, ключевые идентификаторы, о которых сообщено 3 января 2022 года (UTC), могут быть обновлены через этот API 4 января 2022 года (UTC) или позже.

Действия

Аутентификация

Запрос должен включать заголовок HTTP, содержащий API токен AppsFlyer V2.0 вашей учетной записи . Попросите администратора вашей учетной записи получить этот токен с дэшборда AppsFlyer.

Спецификации API и пример кода

Добавить\/изменить идентификаторы (PUT)

URL-адрес запроса API

https://hq1.appsflyer.com/api/audience-bulk-api/v1/additional-identifiers/app/{app-id}
Параметр Описание Обязательный
{app-id}

Идентификатор приложения, из которого были собраны идентификаторы (как отображается на дэшборде AppsFlyer)

 Да

Тело запроса API

{
  "key_type": "<key_type>",
  "action": "add",
  "data": [
    {
      "key_value": "<key_value>",
      "identifiers": {
        "hashed_emails": [
          "<hashed_email_value>",
          "<hashed_email_value>"
        ],
        "phone_number_sha256": "<phone_number_sha256_value>",
        "phone_number_e164_sha256": "<phone_number_e164_sha256_value>"
      }
    },
    {
      "key_value": "<key_value>",
      "identifiers": {
        "hashed_emails": [
          "<hashed_email_value>",
          "<hashed_email_value>"
        ],
        "phone_number_sha256": "<phone_number_sha256_value>",
        "phone_number_e164_sha256": "<phone_number_e164_sha256_value>"
      }
    }
  ]
}
Параметр Описание Обязательный
{key_type}

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

Указанное здесь значение применяется ко всем строкам запроса.

Возможные значения:

  • idfa
  • gaid
  • idfv
  • идентификатор_пользователя_клиента
  • imei
  • oaid
 Да
{action}

добавить

Нет

Значение по умолчанию: добавить
{key_value}

Допустимое значение идентификатора для указанного key_type

 Да

{identifiers}

Объект, содержащий имена и ценности идентификаторов для добавления:

  • {hashed_emails}
  • {phone_number_sha256}
  • {phone_number_e164_sha256}

Да

* Необходимо указать ценность хотя бы для одного из этих трёх идентификаторов

{hashed_emails}

Массив из двух хешированных адресов электронной почты

Формат:

  • Строчные буквы
  • Без пробелов
  • Хеширование SHA256

Пример ценности до хеширования: name@domain.com

Нет

{phone_number_sha256}

Номер телефона (см. примечание ниже)

Формат:

  • Без символов, букв или начальных нулей
  • Включить код страны
  • Хеширование SHA256

Пример ценности до хеширования:

442070313000

Нет
{phone_number_e164_sha256}

Номер телефона в формате E164 (см. примечание ниже)

Формат

  • Номер телефона E164
  • Хеширование SHA256

Пример ценности до хеширования:

+442070313000

Нет

Примечание 

Разные рекламные партнеры поддержка разные форматы телефонных номеров. Поэтому, если вы решили добавить номер телефона, рекомендуется отправлять оба идентификатора: phone_number_sha256 и phone_number_e164_sha256.

Ограничения

К запросу Добавить/изменить идентификаторы применяются следующие ограничения:

  • Ранее существующие ценности (если таковые имеются) будут перезаписаны ценностями, отправленными в запросе.
  • Объект {data} может включать максимум 4 000 строк (ключевых значений) на запрос.

Пример запроса на добавление идентификаторов

HTTP PUT
body:
{
  "key_type": "idfv",
  "action": "add",
  "data": [
    {
      "key_value": "CDDA802e-AAAA-BBBB-CCCC-DDDDDDDDDDDD",
      "identifiers": {
        "hashed_emails": [
          "34d31be18022626de6b311d6a76e791176d2691b6eef406f524d8f56364c187a",
          "d8c2aec999baad2464e521873ee4465caaf7ff6db8c8b4a25b09ca07694e4dee"
        ],
        "phone_number_sha256": "6c91c4c640f6ef0162833260db4f13dec0df2b683092f4dba7e874bef1acea37",
        "phone_number_e164_sha256": "f3d7e96c73fb0de1b66acfce541d7af758fbd4f3fa3af0ea4e10110000d3625e"
      }
    }
  ]
}

Удалить идентификаторы (PUT)

URL-адрес запроса API

https://hq1.appsflyer.com/api/audience-bulk-api/v1/additional-identifiers/app/{app-id}
Параметр Описание Обязательный
{app-id}

Идентификатор приложения, из которого были собраны идентификаторы (как отображается на дэшборде AppsFlyer)

 Да

Тело запроса API

{
  "key_type": "<key_type>",
  "action": "remove",
  "data": [
    {
      "key_value": ",<key_value>",
      "identifiers": [
        "hashed_emails",
        "phone_number_sha256",
        "phone_number_e164_sha256"
      ]
    },
    {
      "key_value": ",<key_value>",
      "identifiers": [
        "hashed_emails",
        "phone_number_sha256",
        "phone_number_e164_sha256"
      ]
    }
  ]
}
Параметр Описание Обязательный
{key_type}

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

Указанное здесь значение применяется ко всем строкам запроса.

Возможные значения:

  • idfa
  • gaid
  • idfv
  • идентификатор_пользователя_клиента
  • imei
  • oaid
 Да
{key_value}

Допустимое значение идентификатора для указанного key_type

 Да
{action}

удалить

Нет

Значение по умолчанию: добавить

{identifiers}

Массив, содержащий имена идентификаторов, для которых необходимо удалить ценности:

  • {hashed_emails}
  • {phone_number_sha256}
  • {phone_number_e164_sha256}

Да


* Необходимо включить как минимум один из этих трёх идентификаторов

Ограничения

Объект {data} может включать максимум 4 000 строк (ключевых значений) на запрос.

Пример запроса на удаление идентификаторов

HTTP PUT
body:
{
  "key_type": "gaid",
  "action": "remove",
  "data": [
    {
      "key_value": "cdda802e-aaaa-bbbb-cccc-dddddddddddd",
      "identifiers": [
        "hashed_emails",
        "phone_number_sha256",
        "phone_number_e164_sha256"
      ]
    }
  ]
}

Ответы

Код Сообщение Описание

202

Принято к обработке

Запрос будет применён в следующем окне обработки.

400

Тело запроса должно содержать допустимый key_type

Поддерживаются следующие типы ключей:

  • idfa
  • gaid
  • idfv
  • идентификатор_пользователя_клиента
  • imei
  • oaid

400

Запрос должен содержать «данные» как минимум с одним элементом

Список данных не может быть пустым.

400

Список «данных» не должен превышать размер 4000 в одном запросе

Список данных может содержать максимум 4000 строк.

400

В запросе слишком много недопустимых элементов данных

Более 10% данных для изменения не соответствуют спецификации.

404

AppsFlyer — Страница не найдена

Проверьте следующее:

  • Указанный в URL-адресе API запроса {app-id} правильный.
  • В HTTP-заголовке указан правильный токен API AppsFlyer V2.0. Администратор вашего аккаунта может получить этот токен на дэшборде AppsFlyer.

Примеры ответов

{
"message": "Accepted for processing",
"received": 1000,"invalid": 2,
"trace-id": "698ed323-c787-45b5-b792-463c67c94064"
}

{
"error": "Request body must have a valid key_type",
"trace-id": "18a5f685-ea4d-4ca9-beab-a542a3786d12"
}

{
"error": "Request must have 'data' with at least 1 element",
"trace-id": "c155a7fa-b573-4efe-9bfb-5ae7de40e7fd"
}

{
"error": "Request 'data' should not exceeds the size of 4000 in a single request”,
"trace-id": "b325a7fa-b573-4efe-9bfb-5ae7de40e72c"
}

{
"error": "Request data has too many invalid 'data' elements",
"valid": 2,
"invalid": 30,
"trace-id": "33551c1d-5682-405e-a959-c8729ca74735"
}

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

  • 5 запросов в секунду
  • 350 запросов в минуту