Sdílet prostřednictvím

Registrace zařízení nabízených oznámení pro vývojáře aplikací

  • Článek

Chcete-li se dozvědět více o celkovém přístupu k nastavení push notifikací v Customer Insights - Journeys, navštivte přehled nastavení nabízených oznámení.

Chcete-li aktivovat nabízená oznámení v Customer Insights - Journeys, musíte provést následující kroky:

  1. Konfigurace aplikace nabízených oznámení
  2. Mapování uživatelů pro nabízená oznámení
  3. Registrace zařízení pro nabízená oznámení
  4. Příjem nabízených oznámení na zařízeních
  5. Výkaznictví interakcí pro nabízená oznámení

Tento diagram popisuje dva kroky potřebné k registraci zařízení a uživatelů v rámci Customer Insights - Journeys.

Zařízení pro nabízená oznámení a schéma registrace uživatele.

Registrace zařízení

K dokončení konfigurace mobilní aplikace musí vývojář zaregistrovat zařízení na serverech. Měli byste již mít token zařízení, ID uživatele z Customer Insights - Journeys (kontaktní ID, ID potenciálního zákazníka, ID profilu Customer Insights - Data) a ID mobilní aplikace z Customer Insights - Journeys.

Po úspěšném volání žádosti o registraci zařízení přijde odpověď 202. Odpověď 202 pouze znamená, že požadavek byl přijat. Chcete-li potvrdit úspěšnou žádost, musíte zkontrolovat stav pomocí webhooku nebo přímo zavolat koncový bod stavu.

API

Registrace zařízení (jednoho)

Ukázkový požadavek 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%"
}

Ukázkový požadavek 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%"
}

Hlavičky:

  • x-ms-track-registration: pokud je true, informace o úspěchu/neúspěchu registrace se ukládají a jsou dostupné prostřednictvím stavu registrace rozhraní API.
  • x-ms-callback-url: Pokud není prázdné, neúspěšná nebo úspěšná registrace zařízení spustí webhook požadavku POST.
  • x-ms-callback-url-headers: Obsahuje serializovaný JSON slovníku typu string-to-string, který představuje záhlaví předávaná pro požadavky webhooku. Používá se pouze v případě, že je definována x-ms-callback-url.

Vrátí: 202, pokud požadavek není platný, jinak 400.

Text odpovědi:

Když je x-ms-track-registration pravda:

{
    "RegistrationRequestId": "%GUID%"
}

Jinak prázdný text.

Definice
Název Popis
MobileAppId Identifikátor mobilní aplikace nakonfigurovaný v Customer Insights - Journeys.
ID uživatele Identifikátor uživatele kontaktu, zájemce, popř. profil Customer Insights - Data z Customer Insights - Journeys.
ApiToken Váš token API pro autorizaci požadavku.
ApnsDeviceToken Jedinečný identifikátor tokenu zařízení generovaný aplikací iOS. Toto bude odesláno pouze pro zařízení iOS
FcmDeviceToken Jedinečný identifikátor tokenu zařízení generovaný aplikací Android. Toto bude odesláno pouze pro zařízení Android

Registrace zařízení (více)

Text registrace dávky obsahuje pole až 100 objektů představujících požadavky na registraci zařízení.

Ukázkový požadavek 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%"
    }
]

Ukázkový požadavek 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%"
    }
]

Hlavičky:

  • x-ms-track-registration: pokud je true, informace o úspěchu/neúspěchu registrace se ukládají a jsou dostupné prostřednictvím stavu registrace rozhraní API.
  • x-ms-callback-url: Pokud není prázdné, neúspěšná nebo úspěšná registrace zařízení spustí webhook požadavku POST.
  • x-ms-callback-url-headers:: Obsahuje serializovaný JSON slovníku typu string-to-string, který představuje záhlaví předávaná pro požadavky webhooku. Používá se pouze když je definována x-ms-callback-url.

Vrátí: 202, pokud požadavek není platný, jinak 400.

Text odpovědi:

Pokud je x-ms-track-registration true: pole položek, každá objednávka položek odpovídá objednávce z pole text požadavku.

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

Jinak prázdný text.

Stav registrace zařízení

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

Tet požadavku:

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

Vrátí: 200, pokud požadavek není platný, jinak 400.

Text požadavku - pole položek:

[
    {
        "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 odpovídá objednávce z pole RegistrationRequestIds.

Definice
Název Popis
RegistrationRequestIds Řada individuálních žádostí o registraci. Hodnoty jsou převzaty z odezvy registračních volání. Toto je k dispozici pouze v případě, že bylo pro registraci použito záhlaví x-ms-track-registration
MobileAppId Identifikátor mobilní aplikace nakonfigurovaný v Customer Insights - Journeys.
ID uživatele Identifikátor uživatele kontaktu, zájemce, popř. profil Customer Insights - Data z Customer Insights - Journeys.

Důležité

Existují tři možné důvody, proč se stav může zaseknout ve stavu „Nevyřízeno“:

  1. Původní žádost o registraci zařízení měla neplatný token API. Aby se zabránilo zlomyslným aktérům provést útok DoS proti prostředí voláním „registrace zařízení“ a generováním nekonečného omezení, takové pokusy nevytvářejí ukládání historie registrace. Proto neexistují informace pro ověření úspěchu.
  2. CRM zůstane v omezeném stavu několik hodin, což způsobí, že operace aktualizace stavu selže při provádění své úlohy po několika opakováních.
  3. Požadavek na registraci zařízení byl podán bez udání hlavičky x-ms-track-registration.

Webhook stavu registrace zařízení

Pokud x-ms-status-callback-url je poskytnuta adresa URL, když je registrace zařízení úspěšná nebo neúspěšná, Customer Insights - Journeys přistupuje k hodnotě záhlaví.

POST na adresu URL uvedenou v záhlaví x-ms-status-callback-url žádosti o registraci zařízení.

Text:

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

Tip

Podpis je hash HMACSHA256 adresy URL zpětného volání vypočítaný pomocí tokenu API jako klíče. Použijte hodnotu k ověření, že Customer Insights - Journeys provedl volání. Hash adresy URL zpětného volání s tokenem API na straně webhooku, použitím stejného algoritmu a porovnáním hodnot.

Poznámka:

Pokus o zadání požadavku proběhne jednou. Jakékoli selhání při provedení požadavku způsobí ztrátu oznámení. Mezi typy selhání patří nesprávná adresa URL zpětného volání, REST API časový limit volání nebo kód stavu neočekávané odpovědi.

Vrátí: 202, pokud požadavek není platný, jinak 400.

Očekávaný text: prázdný text.

Vyčištění zařízení (jednoho)

Je důležité odstranit zařízení, která již nejsou platná, z databáze, aby bylo zajištěno výkonné odesílání zpráv. K odstranění starých kombinací zařízení, uživatelů a aplikací z tabulky zařízení použijte následující postup.

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

Vrátí: 202, pokud požadavek není platný, jinak 400.

Definice
Název Popis
MobileAppId Identifikátor mobilní aplikace nakonfigurovaný v Customer Insights - Journeys.
ApiToken Váš token API pro autorizaci požadavku.
ID uživatele Identifikátor uživatele kontaktu, zájemce, popř. profil Customer Insights - Data z Customer Insights - Journeys.
DeviceToken Jedinečný identifikátor tokenu zařízení generovaný aplikací.

Vyčištění zařízení (více)

Je důležité odstranit zařízení, která již nejsou platná, z databáze, aby bylo zajištěno výkonné odesílání zpráv. K odstranění starých kombinací zařízení, uživatelů a aplikací z tabulky zařízení použijte následující postup.

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

Vrátí: 202, pokud požadavek není platný, jinak 400.

Definice
Název Popis
MobileAppId Identifikátor mobilní aplikace nakonfigurovaný v Customer Insights - Journeys.
ApiToken Váš token API pro autorizaci požadavku.
ID uživatele Identifikátor uživatele kontaktu, zájemce, popř. profil Customer Insights - Data z Customer Insights - Journeys.
DeviceToken Jedinečný identifikátor tokenu zařízení generovaný aplikací.