Dijeli putem

Registracija uređaja za automatske obavijesti za programere aplikacija

  • Članak

Da biste saznali više o cjelokupnom pristupu postavljanju push obavijesti Customer Insights - Journeys, posjetite pregled postavljanja push obavijesti.

Da biste omogućili automatske obavijesti Customer Insights - Journeys, morate izvršiti sljedeće korake:

  1. Konfiguracija aplikacije za automatske obavijesti
  2. Mapiranje korisnika za push obavijesti
  3. Registracija uređaja za push obavijesti
  4. Primanje push obavijesti na uređajima
  5. Izvješćivanje o interakciji za push obavijesti

Ovaj dijagram opisuje dva koraka potrebna za registraciju uređaja i korisnika unutar Customer Insights - Journeys.

Dijagram automatskih obavijesti uređaja i registracije korisnika.

Registracija uređaja

Da bi dovršio konfiguraciju mobilne aplikacije, razvojni programer mora registrirati uređaje na svim poslužiteljima. Već biste trebali imati token uređaja, korisnički ID pošiljatelja Customer Insights - Journeys (ID kontakta, ID potencijalnog klijenta, Customer Insights - Data ID profila) i ID mobilne aplikacije iz Customer Insights - Journeys.

Nakon uspješnog poziva na zahtjev za registraciju uređaja, dolazi do odgovora 202. U odgovoru iz 202. navodi se samo da je zahtjev prihvaćen. Da biste potvrdili uspješan zahtjev, morate provjeriti status pomoću web-dojavnika ili izravnog pozivanja statusa krajnja točka.

API

Registracija uređaja (jednostruka)

Ogledni HTTP zahtjev (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%"
}

Ogledni HTTP zahtjev (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%"
}

Zaglavlja:

  • x-ms-track-registration: kada je to istina, informacije o uspjehu / neuspjehu registracije pohranjuju se i dostupne su putem API-ja statusa registracije.
  • x-ms-callback-url: Kada nije prazan, neuspjela ili uspješna registracija uređaja pokreće web-dojavnik zahtjeva POST.
  • x-ms-callback-url-headers: Sadrži serijalizirani JSON rječnika niza u niz, koji predstavlja zaglavlja proslijeđena za zahtjeve web-dojavnika. Koristi se samo kada je definiran x-ms-callback-url.

Vraća: 202 ako je dostavljeni zahtjev valjan, 400 inače.

Tijelo odgovora:

Kada je x-ms-track-registration istinita:

{
    "RegistrationRequestId": "%GUID%"
}

Inače, prazno tijelo.

Definicije
Ime/naziv Opis
MobileAppId Identifikator mobilne aplikacije konfigurirane u Customer Insights - Journeys.
ID korisnika Korisnički identifikator kontakta, potencijalnog klijenta ili Customer Insights - Data profila iz Customer Insights - Journeys.
ApiToken Vaš API token za autorizaciju zahtjeva.
ApnsDeviceToken Jedinstveni identifikator tokena uređaja koji generira iOS aplikacija. Ovo će biti poslano samo za uređaj iOS
FcmDeviceToken Jedinstveni identifikator tokena uređaja koji generira Android aplikacija. Ovo će biti poslano samo za uređaj Android

Registracija uređaja (višestruko)

Tijelo skupne registracije sadrži niz do 100 objekata koji predstavljaju zahtjeve za registraciju uređaja.

Ogledni HTTP zahtjev (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%"
    }
]

Ogledni HTTP zahtjev (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%"
    }
]

Zaglavlja:

  • x-ms-track-registration: Kada su istinite, informacije o uspjehu ili neuspjehu registracije pohranjuju se i dostupne su putem API-ja statusa registracije.
  • x-ms-callback-URL: Kada nije prazan, neuspjela ili uspješna registracija uređaja pokreće web-dojavnik POST zahtjeva.
  • x-ms-callback-url-headers: Sadrži serijalizirani JSON rječnika niza u niz, koji predstavlja zaglavlja proslijeđena za zahtjeve web-dojavnika. Koristi se samo kada x-ms-callback-url je definirano.

Vraća: 202 ako je dostavljeni zahtjev valjan, 400 inače.

Tijelo odgovora:

Kada je x-ms-track-registration istinita: niz stavki, svaki redoslijed artikala odgovara narudžbi iz polja tijela zahtjeva.

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

Inače, prazno tijelo.

Status registracije uređaja

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

Tijelo zahtjeva:

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

Vraća: 200 ako je navedeni zahtjev valjan, 400 inače.

Tijelo odgovora - niz stavki:

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

Svaki nalog artikla odgovara narudžbi iz polja RegistrationRequestIds .

Definicije
Ime/naziv Opis
RegistracijaRequestIds Niz pojedinačnih zahtjeva za registraciju. Vrijednosti su preuzete iz odgovora na registracijske pozive. To se daje samo kada je za registraciju korišteno zaglavlje registracije x-ms-tracka
MobileAppId Identifikator mobilne aplikacije konfigurirane u Customer Insights - Journeys.
ID korisnika Korisnički identifikator kontakta, potencijalnog klijenta ili Customer Insights - Data profila iz Customer Insights - Journeys.

Važno

Tri su moguća razloga zašto se status može zaglaviti u stanju "na čekanju":

  1. Izvorni zahtjev za registraciju uređaja imao je API token koji nije valjan. Kako bi se spriječilo zlonamjerne aktere da izvedu DoS napad na okruženje nazivajući "uređaj za registraciju" i generirajući beskonačno ograničavanje, takvi pokušaji ne proizvode pohranu povijesti registracije. Stoga nema informacija za provjeru uspjeha.
  2. CRM ostaje u prigušenom stanju više sati, zbog čega operacija ažuriranja statusa ne uspijeva izvršiti svoj posao nakon višestrukih pokušaja.
  3. Zahtjev za registraciju uređaja podnesen je bez navedenog zaglavlja registracije x-ms-track.

Web-dojavnik statusa registracije uređaja

Ako je URL naveden x-ms-status-callback-url , kada je registracija uređaja uspješna ili neuspješna, Customer Insights - Journeys pristupa vrijednosti zaglavlja.

POST na URL koji se nalazi u zaglavlju x-ms-status-callback-url zahtjeva za registraciju uređaja.

Tijelo:

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

Savjet

Potpis je HMACSHA256 raspršivanje URL-a povratnog poziva izračunatog pomoću API tokena kao ključa. Pomoću vrijednosti provjerite je Customer Insights - Journeys li upućen poziv. Raspršite URL povratnog poziva pomoću API tokena na strani web-dojavnika pomoću istog algoritma i usporedbe vrijednosti.

Napomena

Pokušaj podnošenja zahtjeva događa se jednom. Svako neizvršavanje zahtjeva uzrokuje gubitak obavijesti. Vrste neuspjeha uključuju neispravan URL povratnog poziva, vremensko ograničenje poziva REST API ili neočekivani kod stanja odgovora.

Vraća: 202 ako je dostavljeni zahtjev valjan, 400 inače.

Očekivano tijelo: prazno tijelo.

Čišćenje uređaja (jednostruko)

Važno je ukloniti uređaje koji više nisu valjani iz baze podataka kako biste osigurali slanje poruka izvođača. Pomoću sljedećeg pristupa uklonite stare kombinacije uređaja, korisnika i aplikacija iz tablice uređaja.

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

Vraća: 202 ako je dostavljeni zahtjev valjan, 400 inače.

Definicije
Ime/naziv Opis
MobileAppId Identifikator mobilne aplikacije konfigurirane u Customer Insights - Journeys.
ApiToken Vaš API token za autorizaciju zahtjeva.
ID korisnika Korisnički identifikator kontakta, potencijalnog klijenta ili Customer Insights - Data profila iz Customer Insights - Journeys.
Token uređaja Jedinstveni identifikator tokena uređaja koji generira aplikacija.

Čišćenje uređaja (višestruko)

Važno je ukloniti uređaje koji više nisu valjani iz baze podataka kako biste osigurali slanje poruka izvođača. Pomoću sljedećeg pristupa uklonite stare kombinacije uređaja, korisnika i aplikacija iz tablice uređaja.

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

Vraća: 202 ako je dostavljeni zahtjev valjan, 400 inače.

Definicije
Ime/naziv Opis
MobileAppId Identifikator mobilne aplikacije konfigurirane u Customer Insights - Journeys.
ApiToken Vaš API token za autorizaciju zahtjeva.
ID korisnika Korisnički identifikator kontakta, potencijalnog klijenta ili Customer Insights - Data profila iz Customer Insights - Journeys.
Token uređaja Jedinstveni identifikator tokena uređaja koji generira aplikacija.