Поделиться через

Регистрация устройств с push-уведомлениями для разработчиков приложений

  • Статья

Чтобы узнать больше об общем подходе к настройке push-уведомлений в Customer Insights - Journeys, см. обзор настройки push-уведомлений.

Чтобы включить push-уведомления в Customer Insights - Journeys, вам необходимо выполнить следующие шаги:

  1. Конфигурация приложений для push-уведомлений
  2. Сопоставление пользователей для push-уведомлений
  3. Регистрация устройства для push-уведомлений
  4. Получение push-уведомлений на устройствах
  5. Отчетность по взаимодействиям для push-уведомлений

На этой схеме описаны два шага, необходимые для регистрации устройств и пользователей в Customer Insights - Journeys.

Устройства с push-уведомлениями и схема регистрации пользователей.

Регистрация устройства

Чтобы завершить настройку мобильного приложения, разработчик должен зарегистрировать устройства на серверах. У вас уже должен быть токен устройства, идентификатор пользователя из Customer Insights - Journeys (идентификатор контакта, идентификатор интереса, идентификатор профиля Customer Insights - Data) и идентификатор мобильного приложения из Customer Insights - Journeys.

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

API

Регистрация устройства (одиночная)

Образец запроса HTTP (iOS):

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices

{
    "MobileAppId": "00000000-0000-0000-0000-000000000000",
    "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "ApiToken": "%API_TOKEN%",
    "ApnsDeviceToken": "%APNS_TOKEN%"
}

Образец запроса HTTP (Android):

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices

{
    "MobileAppId": "00000000-0000-0000-0000-000000000000",
    "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "ApiToken": "%API_TOKEN%",
    "FcmDeviceToken": "%FCM_TOKEN%"
}

Заголовки:

  • x-ms-track-registration: если значение «true», информация об успешной/неуспешной регистрации сохраняется и доступна через API статуса регистрации.
  • x-ms-callback-url: если он не пуст, неудачная или успешная регистрация устройства вызовет веб-перехватчик POST-запроса.
  • x-ms-callback-url-headers: содержит сериализованный JSON словаря строка-в-строку, представляющий заголовки, передаваемые для запросов веб-перехватчика. Используется только тогда, когда определен x-ms-callback-url.

Возвращает: 202, если запрос действителен, в противном случае это будет 400.

Текст ответа:

Когда значение для x-ms-track-registration — «true»:

{
    "RegistrationRequestId": "%GUID%"
}

В противном случае пустой текст запроса.

Определения
Полное имя Description
MobileAppId Идентификатор мобильного приложения, настроенный в Customer Insights - Journeys.
UserId Идентификатор пользователя контакта, интереса или профиля Customer Insights - Data из Customer Insights - Journeys.
ApiToken Ваш токен API для авторизации запроса.
ApnsDeviceToken Уникальный идентификатор токена устройства, созданный приложением iOS. Это будет отправлено только на устройство iOS
FcmDeviceToken Уникальный идентификатор токена устройства, созданный приложением Android. Это будет отправлено только на устройство Android

Регистрация устройств (нескольких)

Текст пакетной регистрации содержит массив, содержащий до 100 объектов, представляющих собой запросы на регистрацию устройств.

Образец запроса HTTP (iOS):

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/batch

[
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",      
        "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "ApiToken": "%API_TOKEN%",
        "ApnsDeviceToken": "%APNS_TOKEN%"
    },
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",
        "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "ApiToken": "%API_TOKEN%",
        "ApnsDeviceToken": "%APNS_TOKEN%"
    }
]

Образец запроса HTTP (Android):

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/batch

[
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",      
        "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "ApiToken": "%API_TOKEN%",
        "FcmDeviceToken": "%FCM_TOKEN%"
    },
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",
        "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "ApiToken": "%API_TOKEN%",
        "FcmDeviceToken": "%FCM_TOKEN%"
    }
]

Заголовки:

  • x-ms-track-registration: если значение «true», информация об успешной или неуспешной регистрации сохраняется и доступна через API статуса регистрации.
  • x-ms-callback-url: если он не пуст, неудачная или успешная регистрация устройства вызовет веб-перехватчик запроса POST.
  • x-ms-callback-url-headers: содержит сериализованный JSON словаря строка-в-строку, представляющий заголовки, передаваемые для запросов веб-перехватчика. Используется только тогда, когда определен x-ms-callback-url.

Возвращает: 202, если запрос действителен, в противном случае это будет 400.

Текст ответа:

Когда значение для x-ms-track-registration — «true»: массив элементов, порядок каждого элемента соответствует порядку из массива текста запроса.

[
    {
        "RegistrationRequestId": "%REG_REQUEST_ID%"
    },
    {
        "RegistrationRequestId": "%REG_REQUEST_ID%"
    }
]

В противном случае пустой текст запроса.

Статус регистрации устройства

POST  {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/status/

Текст запроса:

{
    "RegistrationRequestIds": [
        "%REG_REQUEST_ID%"
    ],
    "MobileAppId": "%MOBILE_APP_ID%",
    "ApiToken": "%API_TOKEN%"
}

Возвращает: 200, если запрос действителен, в противном случае это будет 400.

Текст запроса — массив элементов:

[
    {
        "Status": "Pending|Success|Failed",
        "FailureReason": " DuplicateExists|DryRunSendingFailed|DeviceTokenTooLong|FailedToStoreDevice|ApiTokenNotValid " // dry run sending is a verification of device token by sending an invisible notification to mobile app. Such sending failure might happen due to a wrong device token or incorrect/expired mobile app auth data
    },
    {
        "Status": "Pending|Success|Failed",
        "FailureReason": " DuplicateExists|DryRunSendingFailed|DeviceTokenTooLong|FailedToStoreDevice|ApiTokenNotValid " // dry run sending is a verification of device token by sending an invisible notification to mobile app. Such sending failure might happen due to a wrong device token or incorrect/expired mobile app auth data
    }
]

Каждому порядку элемента соответствует заказ из массива RegistrationRequestIds.

Определения
Полное имя Description
RegistrationRequestIds Массив индивидуальных запросов на регистрацию. Значения берутся из ответа на регистрационные вызовы. Это предоставляется только в том случае, если для регистрации использовался заголовок x-ms-track-registration
MobileAppId Идентификатор мобильного приложения, настроенный в Customer Insights - Journeys.
UserId Идентификатор пользователя контакта, интереса или профиля Customer Insights - Data из Customer Insights - Journeys.

Важно

Существует три возможные причины, по которым статус может зависнуть в состоянии «Ожидание»:

  1. Исходный запрос на регистрацию устройства содержал недопустимый токен API. Чтобы предотвратить выполнение DoS-атаки на среду злоумышленниками путем вызова «зарегистрировать устройство» и создания бесконечного регулирования количества запросов, такие попытки не приводят к сохранению истории регистрации. Поэтому информация для проверки успешного выполнения отсутствует.
  2. CRM остается в регулируемом состоянии в течение нескольких часов, что приводит к сбою операции обновления статуса после нескольких повторных попыток.
  3. Запрос на регистрацию устройства был сделан без предоставленного заголовка x-ms-track-registration.

Веб-перехватчик состояния регистрации устройства

Если x-ms-status-callback-url предоставляется URL-адресу в случае успешной или неудачной регистрации устройства, Customer Insights - Journeys обращается к значению заголовка.

POST для URL-адреса, указанного внутри заголовка запроса на регистрацию устройства x-ms-status-callback-url.

Текст:

{ 
    "Status": "Success|Failed", 
    "Signature": "%SIGNATURE%", 
    "FailureReason": " DuplicateExists|DryRunSendingFailed|DeviceTokenTooLong|FailedToStoreDevice|ApiTokenNotValid" 
}

Совет

Подпись — это хэш HMACSHA256 URL-адреса обратного вызова, рассчитанный с использованием токена API-интерфейса в качестве ключа. Используйте значение, чтобы убедиться, что Customer Insights - Journeys сделал вызов. Хешируйте URL-адрес обратного вызова с токеном API-интерфейса на стороне веб-перехватчика, используя тот же алгоритм и сравнивая значения.

Заметка

Попытка сделать запрос происходит один раз. Любая неспособность выполнить запрос приводит к потере уведомления. Типы сбоев включают неверный URL-адрес обратного вызова, тайм-аут вызова REST API или неожиданный код состояния ответа.

Возвращает: 202, если запрос действителен, в противном случае это будет 400.

Ожидаемый текст: пустой текст.

Очистка устройства (одного)

Важно удалить устройства, которые больше недействительны, из базы данных, чтобы обеспечить эффективную отправку сообщений. Используйте следующий подход, чтобы удалить старые комбинации устройств, пользователей и приложений из таблицы устройств.

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/cleanup

{
    "MobileAppId": "00000000-0000-0000-0000-000000000000",
    "ApiToken": "%API_TOKEN%",
    "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "DeviceToken": "%OPTIONAL_FCM_OR_APNS_DEVICE_TOKEN%"
}

Возвращает: 202, если запрос действителен, в противном случае это будет 400.

Определения
Полное имя Description
MobileAppId Идентификатор мобильного приложения, настроенный в Customer Insights - Journeys.
ApiToken Ваш токен API для авторизации запроса.
UserId Идентификатор пользователя контакта, интереса или профиля Customer Insights - Data из Customer Insights - Journeys.
DeviceToken Уникальный идентификатор токена устройства, созданный приложением.

Очистка устройств (нескольких)

Важно удалить устройства, которые больше недействительны, из базы данных, чтобы обеспечить эффективную отправку сообщений. Используйте следующий подход, чтобы удалить старые комбинации устройств, пользователей и приложений из таблицы устройств.

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/cleanup/batch

{
    "MobileAppId": "00000000-0000-0000-0000-000000000000",
    "ApiToken": "%API_TOKEN%",
    "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "DeviceToken": "%OPTIONAL_FCM_OR_APNS_DEVICE_TOKEN%"
}

Возвращает: 202, если запрос действителен, в противном случае это будет 400.

Определения
Полное имя Description
MobileAppId Идентификатор мобильного приложения, настроенный в Customer Insights - Journeys.
ApiToken Ваш токен API для авторизации запроса.
UserId Идентификатор пользователя контакта, интереса или профиля Customer Insights - Data из Customer Insights - Journeys.
DeviceToken Уникальный идентификатор токена устройства, созданный приложением.