Del via

Registrering av push-varslingsenhet for programutviklere

  • Artikkel

Hvis du vil vite mer om den generelle metoden for konfigurasjon av push-varsler i Customer Insights - Journeys, kan du gå til oversikt for oppsett av push-varsling.

For å kunne aktivere push-varsler i Customer Insights - Journeys må du utføre følgende trinn:

  1. Konfigurasjon av push-varselprogrammer
  2. Brukertilordning for push-varslinger
  3. Enhetsregistrering for push-varsler
  4. Motta push-varsler på enheter
  5. Samhandlingsrapportering for push-varsler

Dette diagrammet beskriver de to trinnene som kreves for å registrere enheter og brukere i Customer Insights - Journeys.

Diagram for push-varslingsenhet og brukerregistrering.

Enhetsregistrering

Utvikleren må registrere enheter på tvers av servere for å fullføre konfigurasjonen av mobilappen. Du skal allerede ha enhetstoken, bruker-ID fra fra Customer Insights - Journeys (kontakt-ID, kundeemne-ID, Customer Insights - Data-profil-ID) og mobilprogram-IDen fra Customer Insights - Journeys.

Når en forespørsel om enhetsregistrering er vellykket, er det et 202-svar. 202-svaret angir bare at forespørselen er godtatt. Hvis du vil bekrefte at forespørselen er vellykket, må du kontrollere statusen ved å bruke en webhook eller kalle statusendepunkt direkte.

API

Enhetsregistrering (enkel)

Eksempel på HTTP-forespørsel (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%"
}

Eksempel på HTTP-forespørsel (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%"
}

Topptekster:

  • x-ms-track-registration: når sann blir informasjonen om registreringen vellykket/mislykket lagret og er tilgjengelig via API for registreringsstatus.
  • x-ms-callback-url: Når den ikke er tom, utløser en mislykket eller vellykket enhetsregistrering webhook-POST-forespørsel.
  • x-ms-callback-url-headers: Inneholder en serialisert JSON i en streng-til-streng-ordliste som representerer overskrifter som sendes for webhook-forespørsler. Brukes bare når x-ms-callback-url er definert.

Returnerer: 202 ved angitt forespørsel er gyldig, ellers 400.

Svartekst:

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

{
    "RegistrationRequestId": "%GUID%"
}

Ellers tom brødtekst.

Definisjoner
Navn Beskrivelse
MobileAppId Identifikatoren for mobilprogrammet konfigurert i Customer Insights - Journeys.
Bruker-ID Bruker-IDen for kontakten, kundeemnet eller Customer Insights - Data-profilen fra Customer Insights - Journeys.
ApiToken API-tokenet for å godkjenne forespørselen.
ApnsDeviceToken Den unike enhetstokenidentifikatoren som genereres av iOS-programmet. Dette sendes bare for en iOS-enhet
FcmDeviceToken Den unike enhetstokenidentifikatoren som genereres av Android-programmet. Dette sendes bare for en Android-enhet

Enhetsregistrering (flere)

Brødteksten i den satsvise registreringen inneholder en matrise på opptil 100 objekter som representerer forespørsler om enhetsregistrering.

Eksempel på HTTP-forespørsel (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%"
    }
]

Eksempel på HTTP-forespørsel (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%"
    }
]

Topptekster:

  • x-ms-track-registration: Når sann blir informasjonen om registreringen av vellykket eller mislykket lagret og er tilgjengelig via API for registreringsstatus.
  • x-ms-callback-url: Når den ikke er tom, utløser en mislykket eller vellykket enhetsregistrering en webhook-POST-forespørsel.
  • x-ms-callback-url-headers: Inneholder en serialisert JSON i en streng-til-streng-ordliste som representerer overskrifter som sendes for webhook-forespørsler. Brukes bare når x-ms-callback-url defineres.

Returnerer: 202 ved angitt forespørsel er gyldig, ellers 400.

Svartekst:

Når x-ms-track-registration er sann: en matrise med elementer, hver elementordre samsvarer med ordre fra forespørselstekstmatrisen.

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

Ellers tom brødtekst.

Enhetsregistreringsstatus

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

Forespørselstekst:

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

Returnerer: 200 hvis angitt forespørsel er gyldig, ellers 400.

Svartekst – en matrise 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 elementordre tilsvarer ordren fra RegistrationRequestIds-matrisen.

Definisjoner
Navn Beskrivelse
RegistrationRequestIds En matrise med individuelle registreringsforespørsler. Verdiene tas fra svaret på registreringssamtalene. Dette angis bare når hodet x-ms-track-registration ble brukt til registrering
MobileAppId Identifikatoren for mobilprogrammet konfigurert i Customer Insights - Journeys.
Bruker-ID Bruker-IDen for kontakten, kundeemnet eller Customer Insights - Data-profilen fra Customer Insights - Journeys.

Viktig!

Det er tre mulige årsaker til at statusen kan bli stående fast i ventetilstand:

  1. Den opprinnelige registreringsforespørselen for enheten hadde et ugyldig API-token. For å hindre at ondsinnede personer utfører et DoS-angrep mot et miljø ved å kalle opp "registerenhet" og generere uendelig kvelning, genererer ikke slike forsøk lagring av registreringshistorikk. Det er derfor ingen informasjon om å kontrollere suksess.
  2. CRM forblir i en kvelt tilstand i flere timer og fører til at statusoppdateringsoperasjonen mislykkes under utføring av jobben etter flere forsøk.
  3. Forespørselen om enhetsregistrering ble utført uten at x-ms-track-registration-hodet er angitt.

Enhetsregistreringstatus, webhook

Hvis en x-ms-status-callback-url er angitt for URL-adressen når en enhetsregistrering er vellykket eller mislykket, får Customer Insights - Journeys tilgang til verdien i hodet.

POST til URL-adressen i x-ms-status-callback-url-hodet for forespørsel om enhetsregistrering.

Brødtekst:

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

Tips

Signaturen er HMACSHA256-hashen til URL-adressen for tilbakeringing beregnet ved hjelp av API-tokenet som en nøkkel. Bruk verdien til å kontrollere at Customer Insights - Journeys utførte oppkallet. Hash tilbakekallings-URL-adressen med API-tokenet på webhook-siden ved å bruke samme algoritme, og sammenligne verdiene.

Merk

Et forsøk på å opprette en forespørsel skjer én gang. Feil under kjøring av en forespørsel fører til at varselet går tapt. Feiltyper inkluderer feil URL-adresse for tilbakekall, REST- API-tidsavbrudd for oppkall eller uventet svarstatuskode.

Returnerer: 202 ved angitt forespørsel er gyldig, ellers 400.

Forventet tekst: tom tekst.

Enhetsopprydding (enkel)

Det er viktig å fjerne enheter som ikke lenger er gyldige, fra databasen, for å sikre at meldingen sendes. Bruk metoden nedenfor til å fjerne gamle enhets-, bruker- og programkombinasjoner fra 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%"
}

Returnerer: 202 ved angitt forespørsel er gyldig, ellers 400.

Definisjoner
Navn Beskrivelse
MobileAppId Identifikatoren for mobilprogrammet konfigurert i Customer Insights - Journeys.
ApiToken API-tokenet for å godkjenne forespørselen.
Bruker-ID Bruker-IDen for kontakten, kundeemnet eller Customer Insights - Data-profilen fra Customer Insights - Journeys.
DeviceToken Den unike enhetstokenidentifikatoren som genereres av programmet.

Enhetsopprydding (flere)

Det er viktig å fjerne enheter som ikke lenger er gyldige, fra databasen, for å sikre at meldingen sendes. Bruk metoden nedenfor til å fjerne gamle enhets-, bruker- og programkombinasjoner fra 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%"
}

Returnerer: 202 ved angitt forespørsel er gyldig, ellers 400.

Definisjoner
Navn Beskrivelse
MobileAppId Identifikatoren for mobilprogrammet konfigurert i Customer Insights - Journeys.
ApiToken API-tokenet for å godkjenne forespørselen.
Bruker-ID Bruker-IDen for kontakten, kundeemnet eller Customer Insights - Data-profilen fra Customer Insights - Journeys.
DeviceToken Den unike enhetstokenidentifikatoren som genereres av programmet.