Del via

Push-meddelelsens enhedsregistrering til programudviklere

  • Artikel

Hvis du vil vide mere om den overordnede fremgangsmåde til konfiguration af push-meddelelser i Customer Insights - Journeys, kan du gå til oversigten over opsætningen af push-meddelelser.

Hvis du vil aktivere push-meddelelser i Customer Insights - Journeys, skal du udføre følgende trin:

  1. Konfigurationen af push-meddelelsesprogram
  2. Brugertilknytning for push-meddelelser
  3. Enhedsregistrering for push-meddelelser
  4. Modtagelse af push-meddelelser på enheder
  5. Interaktionsrapportering for push-meddelelser

I dette diagram beskrives de to trin, der er nødvendige for at registrere enheder og brugere i Customer Insights - Journeys.

Enheden til push-meddelelser og diagram over brugerregistrering.

Enhedsregistrering

Før konfigurationen af mobilappen kan fuldføres, skal udvikleren registrere enheder på tværs af servere. Du skal allerede have enhedstoken, bruger-id fra Customer Insights - Journeys (kontakt-id, kundeemne-id, Customer Insights - Data profil-id) og mobilprogram-id fra Customer Insights - Journeys.

Når en anmodning om registrering af en enhed er gennemført, er der et 202 svar. Svaret på 202 indikerer kun, at anmodningen blev accepteret. Hvis du vil bekræfte en vellykket anmodning, skal du kontrollere statussen ved hjælp af en webhook eller ved at ringe til statussen slutpunkt direkte.

API

Enhedsregistrering (enkelt)

Prøveanmodning 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%"
}

Prøveanmodning 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%"
}

Overskrifter:

  • x-ms-track-registration: når sand, gemmes oplysningerne om tilmeldingens succes/fejl, og de bliver tilgængelige via registreringsstatus-API'en.
  • url-adresse til x-ms-callback: Når den ikke er tom, udløser mislykkede eller vellykkede enhedsregistreringer POST-anmodningens webhook.
  • x-ms-callback-url-headers: Indeholder en serie af JSON fra en streng til streng-ordbog, der repræsenterer overskrifter, der er overført til webhook-anmodninger. Benyttes kun, når der defineres en url-adresse til x-ms-callback.

Returnerer: 202 hvis vellykket anmodning, og 400, hvis ikke gyldig.

Svarbrødtekst:

Når x-ms-track-registration er sand:

{
    "RegistrationRequestId": "%GUID%"
}

Ellers skal du have et tomt brødtekst.

Definitioner
Navn Beskrivelse
MobileAppId Id for det mobilprogram, der er konfigureret i Customer Insights - Journeys.
Bruger-id Bruger-id for kontakten, kundeemnet eller profilen Customer Insights - Data fra Customer Insights - Journeys.
ApiToken Dit API-token til godkendelse af anmodningen.
ApnsDeviceToken Det entydige enhedstoken-id, der oprettes af iOS-programmet. Dette sendes kun for en iOS-enhed
FcmDeviceToken Det entydige enhedstoken-id, der oprettes af Android-programmet. Dette sendes kun for en Android-enhed

Enhedsregistrering (flere)

Brødteksten i batchregistreringen indeholder en matrix med op til 100 objekter, der repræsenterer anmodninger om enhedsregistrering.

Prøveanmodning 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%"
    }
]

Prøveanmodning 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%"
    }
]

Overskrifter:

  • x-ms-track-registration: Når sand, gemmes oplysningerne om tilmeldingens succes/fejl, og de bliver tilgængelige via registreringsstatus-API'en.
  • x-ms-callback-url: Når den ikke er tom, udløser mislykkede eller vellykkede enhedsregistreringer en POST-anmodnings webhook.
  • x-ms-callback-url-headers: Indeholder en serie af JSON fra en streng til streng-ordbog, der repræsenterer overskrifter, der er overført til webhook-anmodninger. Bruges kun, når x-ms-callback-url er defineret.

Returnerer: 202 hvis vellykket anmodning, og 400, hvis ikke gyldig.

Svarbrødtekst:

Når x-ms-track-registration er sand: en matrix med elementer, svarer hver elementordre til ordren fra brødtekst arrayet for anmodningen.

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

Ellers skal du have et tomt brødtekst.

Status for enhedsregistrering

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

Anmodningsbrødtekst:

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

Returnerer: 200 hvis vellykket anmodning, og 400, hvis ikke gyldig.

Responstekst – en matrix med elementer:

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

Hver enkelt vareordre svarer til ordren fra RegistrationRequestIds-matrix.

Definitioner
Name Description
RegistrationRequestIds En matrix med individuelle tilmeldingsanmodninger. Værdierne bruges som svar på tilmeldingsopkaldene. Dette sker kun, når x-ms-track-registration-headeren blev brugt til tilmelding
MobileAppId Id for det mobilprogram, der er konfigureret i Customer Insights - Journeys.
Bruger-id Bruger-id for kontakten, kundeemnet eller profilen Customer Insights - Data fra Customer Insights - Journeys.

Vigtigt!

Der er tre mulige årsager til, at statussen kan blive hængende i tilstanden "Afventer":

  1. Den oprindelige anmodning om registrering af enheden havde et ugyldigt API-token. Hvis ondsindede angreb skal forhindres i at udføre et DoS-angreb på et miljø ved at kalde "registrer enhed" og generere uendelig mængdeudfyldning, betyder sådanne forsøg ikke, at registreringsoversigten lagres. Der er derfor ingen grund til at kontrollere oplysningerne igen.
  2. CRM forbliver i en tilstand med mange timer, hvilket medfører, at statusopdateringshandlingen ikke udfører jobbet efter flere poster.
  3. Enhedsregistreringsanmodningen blev foretaget uden det angivne x-ms-track-registreringsheader.

Enhedsregistrering Status Webhook

Hvis der angives en url-adresse til en x-ms-status-callback, når en enhedsregistrering lykkes eller mislykkes, får Customer Insights - Journeys adgang til værdien af overskriften.

POST til URL-adressen i x-ms-status-callback-url-headeren for enhedens tilmeldingsanmodning.

Tekst:

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

Tip

Signaturen er en HMACSHA256 hash for tilbagekald af URL, der beregnes ved hjælp af API-token som en nøgle. Brug værdien til at kontrollere, at Customer Insights - Journeys har foretaget opkaldet. Hash tilbagekald af URL med API-tokenet på webhooks side ved hjælp af brug af den samme algoritme og ved at sammenligne værdierne.

Bemærk

Der gøres forsøg på at anmode om det én gang. Hvis en forespørgsel ikke udføres, går meddelelsen tabt. Fejltyper omfatter en forkert URL-adresse til tilbagekald, REST API timeout eller en uventet svarstatuskode.

Returnerer: 202 hvis vellykket anmodning, og 400, hvis ikke gyldig.

Forventet brødtekst: Tom brødtekst.

Enhedsoprydning (enkelt)

Det er vigtigt at fjerne enheder, der ikke længere er gyldige, fra databasen for at sikre, at der sendes en meddelelse om, at der udføres. Brug følgende fremgangsmåde til at fjerne gamle enheds-, bruger- og program kombinationer fra enhedstabellen.

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

Returnerer: 202 hvis vellykket anmodning, og 400, hvis ikke gyldig.

Definitioner
Navn Beskrivelse
MobileAppId Id for det mobilprogram, der er konfigureret i Customer Insights - Journeys.
ApiToken Dit API-token til godkendelse af anmodningen.
Bruger-id Bruger-id for kontakten, kundeemnet eller profilen Customer Insights - Data fra Customer Insights - Journeys.
DeviceToken Det entydige enhedstoken-id, der oprettes af programmet.

Enhedsoprydning (flere)

Det er vigtigt at fjerne enheder, der ikke længere er gyldige, fra databasen for at sikre, at der sendes en meddelelse om, at der udføres. Brug følgende fremgangsmåde til at fjerne gamle enheds-, bruger- og program kombinationer fra enhedstabellen.

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

Returnerer: 202 hvis vellykket anmodning, og 400, hvis ikke gyldig.

Definitioner
Navn Beskrivelse
MobileAppId Id for det mobilprogram, der er konfigureret i Customer Insights - Journeys.
ApiToken Dit API-token til godkendelse af anmodningen.
Bruger-id Bruger-id for kontakten, kundeemnet eller profilen Customer Insights - Data fra Customer Insights - Journeys.
DeviceToken Det entydige enhedstoken-id, der oprettes af programmet.