Бөлісу құралы:

Қолданба әзірлеушілеріне арналған хабарландыру құрылғысын тіркеу

  • Мақала

Push хабарландыруларын орнатудың жалпы тәсілі туралы Customer Insights - Journeys қосымша ақпарат алу үшін push хабарландыруларын орнату шолуын қараңыз.

Customer Insights - Journeysішінде push хабарландыруларын қосу үшін келесі қадамдарды орындау қажет:

  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": "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 сұрауының веб-хукін іске қосады.
  • x-ms-callback-url-headers: Веб-хук сұраулары үшін жіберілген тақырыптарды көрсететін жолдан жолға сөздіктің серияланған JSON файлын қамтиды. x-ms-callback-url анықталғанда ғана пайдаланылады.

Қайтарады: егер берілген сұрау жарамды болса 202, әйтпесе 400.

Жауап органы:

x-ms-track-registration шын болған кезде:

{
    "RegistrationRequestId": "%GUID%"
}

Әйтпесе, бос дене.

Анықтамалар
Аты Сипаттама
MobileAppId Customer Insights - Journeysішінде конфигурацияланған мобильді қолданбаның идентификаторы.
Пайдаланушы идентификаторы Контактінің, ықтимал тұтынушысының немесе 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": "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: Webhook сұраулары үшін жіберілген тақырыптарды көрсететін жолдан жолға сөздіктің серияланған JSON файлын қамтиды. 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 массивіндегі тапсырысқа сәйкес келеді.

Анықтамалар
Аты Сипаттама
RegistrationRequestIds Жеке тіркеу сұрауларының жиыны. Мәндер тіркеу қоңырауларының жауабынан алынады. Бұл тек x-ms-track-registration тақырыбы тіркеу үшін пайдаланылғанда ғана беріледі.
MobileAppId Customer Insights - Journeysішінде конфигурацияланған мобильді қолданбаның идентификаторы.
Пайдаланушы идентификаторы Контактінің, ықтимал тұтынушысының немесе 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 мәніне қол жеткізеді тақырыбы.

Құрылғыны тіркеу сұрауының x-ms-status-callback-url тақырыбында берілген URL мекенжайына POST жіберіңіз.

Тақырып:

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

Шайпұл

Қолтаңба кілт ретінде API таңбалауышы арқылы есептелген кері шақыру URL мекенжайының HMACSHA256 хэші болып табылады. Қоңырау шалғанын Customer Insights - Journeys тексеру үшін мәнді пайдаланыңыз. Бірдей алгоритмді пайдаланып және мәндерді салыстыру арқылы веб-хук жағындағы API таңбалауышы бар кері шақыру URL мекенжайын хэштеңіз.

Ескертпе

Сұраныс жасау әрекеті бір рет орындалады. Сұрауды орындаудың кез келген сәтсіздігі хабарландырудың жоғалуына әкеледі. Сәтсіздік түрлеріне қате кері шақыру 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.

Анықтамалар
Аты Сипаттама
MobileAppId Customer Insights - Journeysішінде конфигурацияланған мобильді қолданбаның идентификаторы.
ApiToken Сұрауды авторизациялау үшін сіздің 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.

Анықтамалар
Аты Сипаттама
MobileAppId Customer Insights - Journeysішінде конфигурацияланған мобильді қолданбаның идентификаторы.
ApiToken Сұрауды авторизациялау үшін сіздің API таңбалауышыңыз.
Пайдаланушы идентификаторы Контактінің, ықтимал тұтынушысының немесе Customer Insights - Data профильінің Customer Insights - Journeys пайдаланушы идентификаторы.
DeviceToken Қолданба жасаған бірегей құрылғы таңбалауыш идентификаторы.