Споделяне чрез

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

  • Статия

За да научите повече за цялостния подход за настройване на насочени известия в Customer Insights - Journeys, посетете прегледа на настройката за насочени известия.

За да разрешите насочените известия в, Customer Insights - Journeys трябва да изпълните следните стъпки:

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

Тази диаграма описва двете стъпки, необходими за регистриране на устройства и потребители в тях 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": "00000000-0000-0000-0000-000000000000",
    "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": "00000000-0000-0000-0000-000000000000",
    "ApiToken": "%API_TOKEN%",
    "FcmDeviceToken": "%FCM_TOKEN%"
}

Заглавки:

  • x-ms-track-registration: когато е вярно, информацията за успеха / неуспеха на регистрацията се съхранява и е достъпна чрез API за състоянието на регистрацията.
  • x-ms-callback-url: Когато не е празен, неуспешна или успешна регистрация на устройство задейства POST заявка webhook.
  • x-ms-callback-url-headers: Съдържа сериализиран JSON на речник от низ към низ, представляващ заглавки, предадени за заявки за webhook. Използва се само когато е дефиниран x-ms-callback-url адрес.

Връщания: 202, ако заявката е валидна, 400 в противен случай.

Орган за отговор:

Когато x-ms-track-registration е вярно:

{
    "RegistrationRequestId": "%GUID%"
}

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

Дефиниции
Име Описание
ИД на мобилно приложение Идентификаторът на мобилното приложение, конфигуриран в Customer Insights - Journeys.
Потребителски ИД Потребителският идентификатор на контакта, потенциалния клиент или Customer Insights - Data профила от Customer Insights - Journeys.
АпиТокен Вашият 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": "00000000-0000-0000-0000-000000000000",
        "ApiToken": "%API_TOKEN%",
        "ApnsDeviceToken": "%APNS_TOKEN%"
    },
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",
        "UserId": "00000000-0000-0000-0000-000000000000",
        "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": "00000000-0000-0000-0000-000000000000",
        "ApiToken": "%API_TOKEN%",
        "FcmDeviceToken": "%FCM_TOKEN%"
    },
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",
        "UserId": "00000000-0000-0000-0000-000000000000",
        "ApiToken": "%API_TOKEN%",
        "FcmDeviceToken": "%FCM_TOKEN%"
    }
]

Заглавки:

  • x-ms-track-registration: Когато е вярно, информацията за успеха или неуспеха на регистрацията се съхранява и е достъпна чрез API за състоянието на регистрацията.
  • x-ms-callback-url: Когато не е празно, неуспешна или успешна регистрация на устройство задейства уеб кука POST за заявка.
  • x-ms-callback-url-headers: Съдържа сериализиран JSON на string-to-string речник, представляващ заглавки, предадени за заявки за webhook. Използва се само когато x-ms-callback-url е дефиниран.

Връщания: 202, ако заявката е валидна, 400 в противен случай.

Орган за отговор:

Когато x-ms-track-registration е истина: масив от елементи, всяка поръчка на артикул съответства на поръчка от масива на тялото на заявката.

[
    {
        "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 .

Дефиниции
Име Описание
Идентификатори на заявки за регистрация Набор от индивидуални заявки за регистрация. Стойностите се вземат от отговора на регистрационните повиквания. Това се предоставя само когато заглавката на x-ms-track-registration е използвана за регистрация
ИД на мобилно приложение Идентификаторът на мобилното приложение, конфигуриран в Customer Insights - Journeys.
Потребителски ИД Потребителският идентификатор на контакта, потенциалния клиент или Customer Insights - Data профила от Customer Insights - Journeys.

Важно

Има три възможни причини, поради които състоянието може да се забие в състояние "Висящо":

  1. Първоначалната заявка за регистрация на устройство имаше невалиден API маркер. За да се предотврати злонамерени участници да извършват DoS атака срещу среда, като се обаждат на "регистрирано устройство" и генерират безкрайно дроселиране, такива опити не водят до съхраняване на историята на регистрацията. Следователно няма информация, която да провери успеха.
  2. CRM остава в състояние на дроселиране в продължение на няколко часа, което води до неуспешно изпълнение на операцията за актуализиране на състоянието след няколко повторения.
  3. Заявката за регистрация на устройството е направена без предоставената заглавка за регистрация на x-ms-track.

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

Ако е предоставен 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 от страната на webhook, като използвате същия алгоритъм и сравнявате стойностите.

Бележка

Опитът да се направи заявка се случва веднъж. Всяко неизпълнение на искане води до загуба на известието. Типовете грешки включват неправилен 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": "00000000-0000-0000-0000-000000000000",
    "DeviceToken": "%OPTIONAL_FCM_OR_APNS_DEVICE_TOKEN%"
}

Връщания: 202, ако заявката е валидна, 400 в противен случай.

Дефиниции
Име Описание
ИД на мобилно приложение Идентификаторът на мобилното приложение, конфигуриран в Customer Insights - Journeys.
АпиТокен Вашият API маркер за упълномощаване на заявката.
Потребителски ИД Потребителският идентификатор на контакта, потенциалния клиент или 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": "00000000-0000-0000-0000-000000000000",
    "DeviceToken": "%OPTIONAL_FCM_OR_APNS_DEVICE_TOKEN%"
}

Връщания: 202, ако заявката е валидна, 400 в противен случай.

Дефиниции
Име Описание
ИД на мобилно приложение Идентификаторът на мобилното приложение, конфигуриран в Customer Insights - Journeys.
АпиТокен Вашият API маркер за упълномощаване на заявката.
Потребителски ИД Потребителският идентификатор на контакта, потенциалния клиент или Customer Insights - Data профила от Customer Insights - Journeys.
DeviceToken Уникалният идентификатор на маркера на устройството, генериран от приложението.