Dela via

Enhetsregistrering av Push-meddelande för programutvecklare

  • Artikel

Om du vill ha mer information om den övergripande metoden för att konfigurera push-meddelanden i Customer Insights - Journeys, besök översikt över konfiguration av push-meddelande.

Om du vill aktivera push-meddelanden i Customer Insights - Journeys måste du utföra följande steg:

  1. Appkonfiguration för push-meddelanden
  2. Användarmappning för push-meddelanden
  3. Enhetsregistrering för push-meddelanden
  4. Ta emot push-meddelanden på enheter
  5. Interaktionsrapportering för push-meddelanden

Det här diagrammet beskriver de två steg som krävs för att registrera enheter och användare i Customer Insights - Journeys.

Enhets- och användarregistreringsdiagram för push-meddelanden.

Enhetsregistrering

För att mobilappskonfigurationen ska slutföras måste utvecklaren registrera enheter på flera servrar. Du bör redan ha enhetstoken, användar-ID från Customer Insights - Journeys (kontakt-ID, lead-ID, Customer Insights - Data profil-ID) och mobilapp-ID från Customer Insights - Journeys.

När du har ringt upp en registrering av en enhet får du ett 202-svar. Svaret från 202 anger endast att förfrågan har accepterats. Om du vill bekräfta en lyckad förfrågan måste du kontrollera statusen med hjälp av en webhook eller anropa slutpunkten direkt.

API

Enhetsregistrering (enkel)

Exempel HTTP-begäran (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%"
}

Exempel HTTP-begäran (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%"
}

Sidhuvuden:

  • x-ms-track-registration: när det är sant lagras information om registrering framgång/fel och vara tillgänglig via registrering status-API.
  • x-ms-callback-url: När den inte är tom, kommer misslyckad eller lyckad enhetsregistrering att utlösa POST-begäran webhook.
  • x-ms-callback-url-headers: Innehåller en serialiserad JSON av en sträng-till-sträng-ordbok, som representerar rubriker som skickas för webhook-förfrågningar. Används endast när x-ms-callback-url har definierats.

Returer: 202 om den angivna begäran är giltig, 400 annars.

Svarstext:

När x-ms-track-registration är sant:

{
    "RegistrationRequestId": "%GUID%"
}

I annat fall tom brödtext.

Definitioner
Namn Beskrivning
MobileAppId Identifieraren för den mobilapp som konfigurerats i Customer Insights - Journeys.
AnvändarID Användar-ID för kontakten, leadet eller Customer Insights - Data-profilen från Customer Insights - Journeys.
ApiToken Din API-token som auktoriserar förfrågan.
ApnsDeviceToken Det unika enhetstoken-ID som genereras av iOS-programmet. Detta skickas endast för en iOS-enhet
FcmDeviceToken Det unika enhetstoken-ID som genereras av Android-programmet. Detta skickas endast för en Android-enhet

Enhetsregistrering (flera)

Brödtexten i batchregistreringen innehåller en matris med upp till 100 objekt som representerar begäran om enhetsregistrering.

Exempel HTTP-begäran (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%"
    }
]

Exempel HTTP-begäran (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%"
    }
]

Sidhuvuden:

  • x-ms-track-registration:: När det är sant lagras information om registrering framgång eller fel och vara tillgänglig via registrering status-API.
  • x-ms-callback-url: När den inte är tom, kommer misslyckad eller lyckad enhetsregistrering att utlösa POST-begäran webhook.
  • x-ms-callback-url-headers:: Innehåller en serialiserad JSON av en sträng-till-sträng-ordbok, som representerar rubriker som skickas för webhook-förfrågningar. Används endast när x-ms-callback-url definieras.

Returer: 202 om den angivna begäran är giltig, 400 annars.

Svarstext:

När x-ms-track-registration är sant: en matris med objekt motsvarar varje objektordning order från förfrågans brödtextmatris.

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

I annat fall tom brödtext.

Status för enhetsregistrering

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

Begärandetext:

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

Returer: 200 om den angivna begäran är giltig, 400 annars.

Begärandetext – en matris med objekt:

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

Varje objektorder motsvarar ordern från matrisen RegistrationRequestIds.

Definitioner
Namn Beskrivning
RegistrationRequestIds En matris med enskilda registreringsförfrågningar. Värdena tas från registreringssamtalens svar. Detta anges endast när rubriken x-ms-track-registration användes för registrering
MobileAppId Identifieraren för den mobilapp som konfigurerats i Customer Insights - Journeys.
AnvändarID Användar-ID för kontakten, leadet eller Customer Insights - Data-profilen från Customer Insights - Journeys.

Viktigt

Det finns tre möjliga orsaker till varför statusen kan fastna i status väntande:

  1. Den ursprungliga begäran om enhetsregistrering hade en ogiltig API-token. Om du vill förhindra att skadliga användare utför en DoS-angrepp mot en miljö genom att anropa "registerenhet" och skapa generering av historik för förfallna miljöer, leder sådana försök inte till att registreringshistorik lagras. Därför finns det ingen information för att kontrollera framgång.
  2. CRM-systemet fortsätter att fungera i flera timmar, vilket gör att statusuppdateringsåtgärden inte kan köras efter flera uppdateringar.
  3. Begäran om enhetsregistrering gjordes utan det medföljande x-ms-track-registration-huvudet.

Webhook för enhetsregistreringsstatus

Om en x-ms-status-callback-url anges som URL:en när en enhetsregistrering lyckas eller misslyckas får du Customer Insights - Journeys åtkomst till värdet i rubriken.

POST till webbadressen som tillhandahålls inom x-ms-status-callback-url rubriken för begäran om enhetsregistrering.

Brödtext:

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

Dricks

Signaturen är HMACSHA256 hasch med callback-URL som beräknas med API-token som en nyckel. Använd värdet för att kontrollera att Customer Insights - Journeys samtalet har ringts upp. Hasha callback-URL:en med API-token på webhooks sida, använda samma algoritm och jämföra värdena.

Kommentar

Ett försök att göra en förfrågan sker en gång. Om det inte går att utföra en förfrågan förloras meddelandet. Feltyper innehåller fel på callback-URL, REST API tidsgräns för samtal eller en oväntad svarsstatuskod.

Returer: 202 om den angivna begäran är giltig, 400 annars.

Förväntad kropp: tom brödtext.

Enhetsrensning (enkel)

Det är viktigt att ta bort enheter som inte längre är giltiga från databasen för att säkerställa att meddelanden skickas. Använd följande metod om du vill ta bort gamla kombinationer av enheter, användare och program från enhetstabellen.

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

Returer: 202 om den angivna begäran är giltig, 400 annars.

Definitioner
Namn Beskrivning
MobileAppId Identifieraren för den mobilapp som konfigurerats i Customer Insights - Journeys.
ApiToken Din API-token som auktoriserar förfrågan.
AnvändarID Användar-ID för kontakten, leadet eller Customer Insights - Data-profilen från Customer Insights - Journeys.
DeviceToken Det unika enhetstoken-ID som genereras av programmet.

Enhetsrensning (flera)

Det är viktigt att ta bort enheter som inte längre är giltiga från databasen för att säkerställa att meddelanden skickas. Använd följande metod om du vill ta bort gamla kombinationer av enheter, användare och program från enhetstabellen.

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

Returer: 202 om den angivna begäran är giltig, 400 annars.

Definitioner
Namn Beskrivning
MobileAppId Identifieraren för den mobilapp som konfigurerats i Customer Insights - Journeys.
ApiToken Din API-token som auktoriserar förfrågan.
AnvändarID Användar-ID för kontakten, leadet eller Customer Insights - Data-profilen från Customer Insights - Journeys.
DeviceToken Det unika enhetstoken-ID som genereras av programmet.