Zdieľať cez

Registrácia zariadenia push notifikácie pre vývojárov aplikácií

  • Článok

Ak sa chcete dozvedieť viac o celkovom prístupe k nastaveniu upozornení push v Customer Insights - Journeys, navštívte prehľad nastavenia upozornení push.

Ak chcete povoliť upozornenia push v Customer Insights - Journeys, musíte vykonať nasledujúce kroky:

  1. Konfigurácia aplikácie push notifikácií
  2. Mapovanie používateľov pre upozornenia push
  3. Registrácia zariadenia pre push notifikácie
  4. Prijímanie upozornení push na zariadeniach
  5. Hlásenie interakcií pre upozornenia push

Tento diagram popisuje dva kroky potrebné na registráciu zariadení a používateľov Customer Insights - Journeys.

Zariadenie na odosielanie upozornení a diagram registrácie používateľa.

Registrácia zariadenia

Na dokončenie konfigurácie mobilnej aplikácie musí vývojár zaregistrovať zariadenia na serveroch. Už by ste mali mať token zariadenia, ID používateľa od Customer Insights - Journeys (identifikátor kontaktu, ID potenciálneho zákazníka, Customer Insights - Data ID profilu) a ID mobilnej aplikácie od Customer Insights - Journeys.

Po úspešnom volaní žiadosti o registráciu zariadenia príde odpoveď 202. Odpoveď 202 iba naznačuje, že žiadosť bola prijatá. Ak chcete potvrdiť úspešnú žiadosť, musíte skontrolovať stav pomocou webhooku alebo priamo zavolať koncový bod stavu.

Rozhranie API

Registrácia zariadenia (jedno)

Vzorová požiadavka 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%"
}

Vzorová požiadavka 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%"
}

Hlavičky:

  • x-ms-track-registration: ak je pravda, informácie o úspechu/neúspechu registrácie sa uložia a budú dostupné prostredníctvom API stavu registrácie.
  • x-ms-callback-url: Ak nie je prázdne, neúspešná alebo úspešná registrácia zariadenia spustí webhook požiadavky POST.
  • x-ms-callback-url-headers: Obsahuje serializovaný JSON slovníka typu string-to-string, ktorý predstavuje hlavičky odovzdané pre požiadavky webhooku. Používa sa len vtedy, keď je definovaná x-ms-callback-url.

Vrátenie: 202, ak je poskytnutá žiadosť platná, 400 inak.

Telo odpovede:

Keď je x-ms-track-registration pravdivé:

{
    "RegistrationRequestId": "%GUID%"
}

V opačnom prípade je telo prázdne.

Definície
Name Description
MobileAppId Identifikátor mobilnej aplikácie nakonfigurovaný v Customer Insights - Journeys.
Identifikácia používateľa Identifikátor používateľa kontaktu, potenciálneho zákazníka alebo Customer Insights - Data profilu z Customer Insights - Journeys.
ApiToken Váš token API na autorizáciu žiadosti.
ApnsDeviceToken Jedinečný identifikátor tokenu zariadenia vygenerovaný aplikáciou iOS . Toto bude odoslané iba pre zariadenie iOS
FcmDeviceToken Jedinečný identifikátor tokenu zariadenia vygenerovaný aplikáciou Android . Toto bude odoslané iba pre zariadenie Android

Registrácia zariadenia (viacero)

Telo registrácie dávky obsahuje pole až 100 objektov reprezentujúcich požiadavky na registráciu zariadenia.

Vzorová požiadavka 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%"
    }
]

Vzorová požiadavka 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%"
    }
]

Hlavičky:

  • x-ms-track-registration: Ak je pravda, informácie o úspechu alebo zlyhaní registrácie sa uložia a budú dostupné prostredníctvom API stavu registrácie.
  • x-ms-callback-url: Ak nie je prázdne, neúspešná alebo úspešná registrácia zariadenia spustí webhook POST žiadosti.
  • x-ms-callback-url-headers: Obsahuje serializovaný JSON slovníka typu string-to-string, ktorý predstavuje hlavičky odovzdané pre požiadavky webhooku. Používa sa len vtedy, keď je zadefinované x-ms-callback-url .

Vrátenie: 202, ak je poskytnutá žiadosť platná, 400 inak.

Telo odpovede:

Keď x-ms-track-registration je pravdivé: pole položiek, každá objednávka položiek zodpovedá objednávke z poľa tela požiadavky.

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

V opačnom prípade je telo prázdne.

Stav registrácie zariadenia

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

Telo žiadosti:

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

Vrátenie: 200, ak je poskytnutá žiadosť platná, 400 inak.

Telo odpovede – pole položiek:

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

Každá objednávka položky zodpovedá objednávke z poľa RegistrationRequestIds .

Definície
Name Description
RegistrationRequestIds Množstvo individuálnych žiadostí o registráciu. Hodnoty sú prevzaté z odozvy registračných volaní. Toto sa poskytuje iba vtedy, keď bola na registráciu použitá hlavička x-ms-track-registration
MobileAppId Identifikátor mobilnej aplikácie nakonfigurovaný v Customer Insights - Journeys.
Identifikácia používateľa Identifikátor používateľa kontaktu, potenciálneho zákazníka alebo Customer Insights - Data profilu z Customer Insights - Journeys.

Dôležité

Existujú tri možné dôvody, prečo sa stav môže zaseknúť v stave „Nevybavené“:

  1. Pôvodná žiadosť o registráciu zariadenia mala neplatný token rozhrania API. Aby sa zabránilo škodlivým aktérom vykonať útok DoS proti prostrediu volaním „zariadenia na registráciu“ a generovaním nekonečného obmedzovania, takéto pokusy nevedú k ukladaniu histórie registrácie. Preto neexistujú žiadne informácie na kontrolu úspechu.
  2. CRM zostane v obmedzenom stave niekoľko hodín, čo spôsobí, že operácia aktualizácie stavu zlyhá pri vykonávaní svojej úlohy po viacerých pokusoch.
  3. Žiadosť o registráciu zariadenia bola uskutočnená bez poskytnutej hlavičky x-ms-track-registration .

Webhook stavu registrácie zariadenia

Ak x-ms-status-callback-url v prípade úspešnej alebo neúspešnej registrácie zariadenia poskytne adresu URL, Customer Insights - Journeys pristúpi k hodnote hlavička.

POST na adresu URL poskytnutú v hlavičke x-ms-status-callback-url žiadosti o registráciu zariadenia.

Telo:

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

Prepitné

Podpis je hash HMACSHA256 adresy URL spätného volania vypočítaný pomocou tokenu API ako kľúča. Pomocou hodnoty overte, že Customer Insights - Journeys vyvolalo hovor. Hašujte webovú adresu spätného volania s tokenom API na strane webhooku pomocou rovnakého algoritmu a porovnaním hodnôt.

Poznámka

Pokus o zadanie žiadosti sa uskutoční raz. Akékoľvek zlyhanie pri vykonaní požiadavky spôsobí stratu oznámenia. Typy zlyhania zahŕňajú nesprávnu adresu URL spätného volania, Rozhranie REST API časový limit hovoru alebo kód stavu neočakávanej odpovede.

Vrátenie: 202, ak je poskytnutá žiadosť platná, 400 inak.

Očakávané telo: prázdne telo.

Čistenie zariadenia (jedno)

Je dôležité odstrániť zariadenia, ktoré už nie sú platné, z databázy, aby sa zabezpečilo efektívne odosielanie správ. Na odstránenie starých kombinácií zariadení, používateľov a aplikácií z tabuľky zariadení použite nasledujúci postup.

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

Vrátenie: 202, ak je poskytnutá žiadosť platná, 400 inak.

Definície
Name Description
MobileAppId Identifikátor mobilnej aplikácie nakonfigurovaný v Customer Insights - Journeys.
ApiToken Váš token API na autorizáciu žiadosti.
Identifikácia používateľa Identifikátor používateľa kontaktu, potenciálneho zákazníka alebo Customer Insights - Data profilu z Customer Insights - Journeys.
DeviceToken Jedinečný identifikátor tokenu zariadenia vygenerovaný aplikáciou.

Čistenie zariadenia (viacero)

Je dôležité odstrániť zariadenia, ktoré už nie sú platné, z databázy, aby sa zabezpečilo efektívne odosielanie správ. Na odstránenie starých kombinácií zariadení, používateľov a aplikácií z tabuľky zariadení použite nasledujúci postup.

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

Vrátenie: 202, ak je poskytnutá žiadosť platná, 400 inak.

Definície
Name Description
MobileAppId Identifikátor mobilnej aplikácie nakonfigurovaný v Customer Insights - Journeys.
ApiToken Váš token API na autorizáciu žiadosti.
Identifikácia používateľa Identifikátor používateľa kontaktu, potenciálneho zákazníka alebo Customer Insights - Data profilu z Customer Insights - Journeys.
DeviceToken Jedinečný identifikátor tokenu zariadenia vygenerovaný aplikáciou.