Deli z drugimi prek

Registracija naprave za potisno obveščanje za razvijalce aplikacij

  • Članek

Če želite izvedeti več o splošnem pristopu k nastavitvi potisnih obvestil v Customer Insights - Journeys, obiščite pregled nastavitve potisnih obvestil.

Če želite omogočiti potisna obvestila v Customer Insights - Journeys, morate opraviti naslednje korake:

  1. Konfiguracija aplikacije za potisna obvestila
  2. Preslikava uporabnikov za potisna obvestila
  3. Registracija naprave za potisna obvestila
  4. Prejemanje potisnih obvestil na naprave
  5. Poročanje o interakciji za potisna obvestila

Ta diagram opisuje dva koraka, potrebna za registracijo naprav in uporabnikov v njih Customer Insights - Journeys.

Naprava za potisna obvestila in diagram registracije uporabnikov.

Registracija naprave

Za dokončanje konfiguracije mobilne aplikacije mora razvijalec registrirati naprave med strežniki. Morali bi že imeti žeton naprave, ID uporabnika od Customer Insights - Journeys (ID stika, ID potencialne stranke, Customer Insights - Data ID profila) in ID mobilne aplikacije od Customer Insights - Journeys.

Ob uspešnem klicu zahteve za registracijo naprave je odgovor 202. Odgovor 202 samo pomeni, da je bila zahteva sprejeta. Če želite potrditi uspešno zahtevo, morate preveriti stanje z uporabo webhooka ali neposredno klicati status končna točka.

API

Registracija naprave (enojna)

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

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

Glave:

  • x-ms-track-registration: ko je res, so informacije o uspešni/neuspešni registraciji shranjene in na voljo prek API-ja statusa registracije.
  • x-ms-callback-url: Če ni prazno, neuspešna ali uspešna registracija naprave sproži spletni kavelj zahteve POST.
  • x-ms-callback-url-headers: Vsebuje serializiran JSON slovarja od niza do niza, ki predstavlja glave, posredovane za zahteve webhook. Uporablja se le, če je definiran x-ms-callback-url.

Vrne: 202, če je podana zahteva veljavna, 400 sicer.

Telo odgovora:

Ko je x-ms-track-registration resnična:

{
    "RegistrationRequestId": "%GUID%"
}

V nasprotnem primeru prazno telo.

Definicije
Imenu Description
MobileAppId Identifikator mobilne aplikacije, konfigurirane v Customer Insights - Journeys.
IDUporabnika Identifikator uporabnika stika, potencialne stranke ali Customer Insights - Data profila od Customer Insights - Journeys.
ApiToken Vaš žeton API za odobritev zahteve.
ApnsDeviceToken Enolični identifikator žetona naprave, ki ga ustvari iOS aplikacija. To bo poslano samo za iOS napravo
FcmDeviceToken Enolični identifikator žetona naprave, ki ga ustvari Android aplikacija. To bo poslano samo za Android napravo

Registracija naprave (več)

Telo paketne registracije vsebuje matriko do 100 objektov, ki predstavljajo zahteve za registracijo naprave.

Primer zahteve 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%"
    }
]

Primer zahteve 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%"
    }
]

Glave:

  • x-ms-track-registration: Če je res, so informacije o uspešni ali neuspešni registraciji shranjene in na voljo prek API-ja statusa registracije.
  • x-ms-callback-url: Če ni prazen, neuspešna ali uspešna registracija naprave sproži POST request webhook.
  • x-ms-callback-url-headers: Vsebuje serializiran JSON slovarja od niza do niza, ki predstavlja glave, posredovane za zahteve webhook. Uporablja se le, če je x-ms-callback-url definiran.

Vrne: 202, če je podana zahteva veljavna, 400 sicer.

Telo odgovora:

Če je x-ms-track-registration true: matrika postavk, vsak vrstni red postavk ustreza vrstnemu redu iz matrike telesa zahteve.

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

V nasprotnem primeru prazno telo.

Stanje registracije naprave

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

Telo zahteve:

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

Vračilo: 200, če je podana zahteva veljavna, 400 sicer.

Telo odgovora – nabor elementov:

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

Vsako naročilo elementa ustreza naročilu iz RegistrationRequestIds matrike.

Definicije
Imenu Description
RegistrationRequestIds Niz posameznih zahtevkov za registracijo. Vrednosti so vzete iz odziva na registracijske klice. To je na voljo le, če je bila za registracijo uporabljena glava x-ms-track-registration
MobileAppId Identifikator mobilne aplikacije, konfigurirane v Customer Insights - Journeys.
IDUporabnika Identifikator uporabnika stika, potencialne stranke ali Customer Insights - Data profila od Customer Insights - Journeys.

Pomembno

Obstajajo trije možni razlogi, zakaj se stanje lahko zatakne v stanju »V teku«:

  1. Prvotna zahteva za registracijo naprave je vsebovala neveljaven žeton API. Da bi preprečili zlonamernim akterjem, da izvedejo napad DoS na okolje s klicem »registracijske naprave« in ustvarjanjem neskončnega dušenja, takšni poskusi ne povzročijo shranjevanja zgodovine registracij. Zato ni podatkov za preverjanje uspeha.
  2. CRM ostane v dušenem stanju več ur, kar povzroči, da operacija posodobitve statusa ne izvede svojega opravila po večkratnih ponovnih poskusih.
  3. Zahteva za registracijo naprave je bila podana brez zagotovljene glave x-ms-track-registration .

Webhook stanja registracije naprave

Če je x-ms-status-callback-url naveden URL, ko je registracija naprave uspešna ali neuspešna, Customer Insights - Journeys dostopa do vrednosti glava.

OBJAVI na URL, naveden znotraj x-ms-status-callback-url glave zahteve za registracijo naprave.

Telo:

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

Nasvet

Podpis je zgoščena vrednost HMACSHA256 URL-ja povratnega klica, izračunana z uporabo žetona API kot ključa. Uporabite vrednost, da preverite, da je Customer Insights - Journeys izvedel klic. Zgostite URL povratnega klica z žetonom API na strani webhooka z uporabo istega algoritma in primerjajte vrednosti.

opomba,

Poskus vložitve zahteve se zgodi enkrat. Vsaka neizvedba zahteve povzroči izgubo obvestila. Vrste napak vključujejo napačen URL za povratni klic, REST API časovno omejitev klica ali nepričakovano statusno kodo odgovora.

Vrne: 202, če je podana zahteva veljavna, 400 sicer.

Pričakovano telo: prazno telo.

Čiščenje naprave (enojno)

Pomembno je, da iz zbirke podatkov odstranite naprave, ki niso več veljavne, da zagotovite učinkovito pošiljanje sporočil. Uporabite naslednji pristop, da odstranite stare kombinacije naprav, uporabnikov in aplikacij iz tabele naprav.

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

Vrne: 202, če je podana zahteva veljavna, 400 sicer.

Definicije
Imenu Description
MobileAppId Identifikator mobilne aplikacije, konfigurirane v Customer Insights - Journeys.
ApiToken Vaš žeton API za odobritev zahteve.
IDUporabnika Identifikator uporabnika stika, potencialne stranke ali Customer Insights - Data profila od Customer Insights - Journeys.
DeviceToken Enolični identifikator žetona naprave, ki ga ustvari aplikacija.

Čiščenje naprave (večkrat)

Pomembno je, da iz zbirke podatkov odstranite naprave, ki niso več veljavne, da zagotovite učinkovito pošiljanje sporočil. Uporabite naslednji pristop, da odstranite stare kombinacije naprav, uporabnikov in aplikacij iz tabele naprav.

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

Vrne: 202, če je podana zahteva veljavna, 400 sicer.

Definicije
Imenu Description
MobileAppId Identifikator mobilne aplikacije, konfigurirane v Customer Insights - Journeys.
ApiToken Vaš žeton API za odobritev zahteve.
IDUporabnika Identifikator uporabnika stika, potencialne stranke ali Customer Insights - Data profila od Customer Insights - Journeys.
DeviceToken Enolični identifikator žetona naprave, ki ga ustvari aplikacija.