Condividi tramite

Registrazione del dispositivo con notifiche push per gli sviluppatori di applicazioni

  • Articolo

Per ulteriori informazioni sull'approccio generale alla configurazione delle notifiche push in Customer Insights - Journeys, visita la panoramica sulla configurazione delle notifiche push.

Per abilitare le notifiche push in Customer Insights - Journeys, devi completare i seguenti passaggi:

  1. Configurazione dell'applicazione delle notifiche push
  2. Mapping utente per notifiche push
  3. Registrazione del dispositivo per le notifiche push
  4. Ricevere notifiche push sui dispositivi
  5. Report di interazione per notifiche push

Questo diagramma descrive i due passaggi necessari per registrare dispositivi e utenti in Customer Insights - Journeys.

Dispositivo con notifiche push e diagramma di registrazione dell'utente.

Registrazione dispositivo

Per completare la configurazione dell'app per dispositivi mobili, lo sviluppatore deve registrare i dispositivi sui server. Dovresti già avere il token del dispositivo, l'ID utente da Customer Insights - Journeys (ID contatto, ID lead, ID profilo Customer Insights - Data) e l'ID dell'applicazione per dispositivi mobili da Customer Insights - Journeys.

In caso di chiamata riuscita di una richiesta di registrazione del dispositivo, si verifica una risposta 202. La risposta 202 indica solo che la richiesta è stata accettata. Per confermare una richiesta andata a buon fine, è necessario verificare lo stato utilizzando un webhook o chiamando direttamente lo stato endpoint.

API

Registrazione del dispositivo (singolo)

Esempio di richiesta 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%"
}

Esempio di richiesta 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%"
}

Intestazioni:

  • x-ms-track-registration: se vero, le informazioni sull'esito positivo/errore della registrazione vengono archiviate e sono disponibili tramite l'API dello stato di registrazione.
  • x-ms-callback-url: se non è vuota, una registrazione del dispositivo non riuscita o riuscita attiverà il webhook della richiesta POST.
  • x-ms-callback-url-headers: contiene un JSON serializzato di un dizionario da stringa a stringa, che rappresenta le intestazioni passate per le richieste webhook. Utilizzato solo quando è definito x-ms-callback-url.

Restituisce: 202 se la richiesta specificata è valida, 400 in caso contrario.

Corpo della risposta:

Quando x-ms-registrazione-traccia è vero:

{
    "RegistrationRequestId": "%GUID%"
}

Altrimenti corpo vuoto.

Definizioni
Nome Descrzione
MobileAppId L'identificatore dell'applicazione per dispositivi mobili configurata in Customer Insights - Journeys.
ID utente L'identificatore utente del contatto, lead o profilo Customer Insights - Data da Customer Insights - Journeys.
ApiToken Il tuo token API per autorizzare la richiesta.
ApnsDeviceToken L'identificatore univoco del token del dispositivo generato dall'applicazione iOS. Verrà inviato solo per un dispositivo iOS
FcmDeviceToken L'identificatore univoco del token del dispositivo generato dall'applicazione Android. Verrà inviato solo per un dispositivo Android

Registrazione dispositivo (multiplo)

Il corpo della registrazione batch contiene una matrice di un massimo di 100 oggetti che rappresentano le richieste di registrazione del dispositivo.

Esempio di richiesta 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%"
    }
]

Esempio di richiesta 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%"
    }
]

Intestazioni:

  • x-ms-track-registration: se vero, le informazioni sull'esito positivo o negativo della registrazione vengono archiviate e sono disponibili tramite l'API dello stato di registrazione.
  • x-ms-callback-url: se non è vuota, una registrazione del dispositivo non riuscita o riuscita attiverà un webhook della richiesta POST.
  • x-ms-callback-url-headers: contiene un JSON serializzato di un dizionario da stringa a stringa, che rappresenta le intestazioni passate per le richieste webhook. Viene usato solo quando x-ms-callback-url è definito.

Restituisce: 202 se la richiesta specificata è valida, 400 in caso contrario.

Corpo della risposta:

Se x-ms-track-registrationa è vero: una matrice di elementi, ogni ordine di elemento corrisponde all'ordine dall'array del corpo della richiesta.

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

Altrimenti corpo vuoto.

Stato registrazione dispositivo

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

Corpo della richiesta:

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

Restituisce: 200 se la richiesta specificata è valida, 400 in caso contrario.

Corpo della risposta - una matrice di elementi:

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

Ogni ordine di articolo corrisponde all'ordine dalla matrice RegistrationRequestIds.

Definizioni
Nome Descrzione
RegistrationRequestIds Una serie di richieste di registrazione individuali. I valori sono presi dalla risposta delle chiamate di registrazione. Questo viene fornito solo quando l'intestazione x-ms-track-registration è stata utilizzata per la registrazione
MobileAppId L'identificatore dell'applicazione per dispositivi mobili configurata in Customer Insights - Journeys.
ID utente L'identificatore utente del contatto, lead o profilo Customer Insights - Data da Customer Insights - Journeys.

Importante

Esistono tre possibili ragioni per cui lo stato può rimanere bloccato come "In sospeso":

  1. La richiesta di registrazione del dispositivo originale aveva un token API non valido. Per impedire a utenti malintenzionati di eseguire un attacco DoS contro un ambiente chiamando "registra dispositivo" e generando limitazioni infinite, tali tentativi non producono l'archiviazione della cronologia di registrazione. Pertanto, non ci sono informazioni per verificare il completamento.
  2. Il CRM rimane in uno stato limitato per più ore, causando la mancata esecuzione del processo di aggiornamento dello stato dopo più tentativi.
  3. La richiesta di registrazione del dispositivo è stata effettuata senza l'intestazione x-ms-track-registration fornita.

Webhook dello stato di registrazione del dispositivo

Se viene fornito l'URL x-ms-status-callback-url quando la registrazione del dispositivo ha esito positivo o negativo, Customer Insights - Journeys accede al valore dell'intestazione.

POST all'URL fornito all'interno dell'intestazione x-ms-status-callback-url della richiesta di registrazione del dispositivo.

Testo:

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

Suggerimento

La firma è l'hash HMACSHA256 dell'URL di callback calcolato utilizzando il token API come chiave. Utilizza il valore per verificare che Customer Insights - Journeys abbia effettuato la chiamata. Esegui l'hashing dell'URL di callback con il token API sul lato del webhook utilizzando lo stesso algoritmo e confrontando i valori.

Nota

Il tentativo di effettuare una richiesta avviene una volta. Qualsiasi mancata esecuzione di una richiesta comporta la perdita della notifica. I tipi di errore includono un URL di callback errato, timeout della chiamata API REST o codice di stato di risposta imprevisto.

Restituisce: 202 se la richiesta specificata è valida, 400 in caso contrario.

Corpo previsto: corpo vuoto.

Pulizia dispositivo (singola)

È importante rimuovere i dispositivi che non sono più validi dal database per garantire un invio di messaggi efficiente. Utilizza il seguente approccio per rimuovere le vecchie combinazioni di dispositivo, utente e applicazione dalla tabella dei dispositivi.

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

Restituisce: 202 se la richiesta specificata è valida, 400 in caso contrario.

Definizioni
Nome Descrzione
MobileAppId L'identificatore dell'applicazione per dispositivi mobili configurata in Customer Insights - Journeys.
ApiToken Il tuo token API per autorizzare la richiesta.
ID utente L'identificatore utente del contatto, lead o profilo Customer Insights - Data da Customer Insights - Journeys.
DeviceToken L'identificatore univoco del token del dispositivo generato dall'applicazione.

Pulizia dispositivo (multipla)

È importante rimuovere i dispositivi che non sono più validi dal database per garantire un invio di messaggi efficiente. Utilizza il seguente approccio per rimuovere le vecchie combinazioni di dispositivo, utente e applicazione dalla tabella dei dispositivi.

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

Restituisce: 202 se la richiesta specificata è valida, 400 in caso contrario.

Definizioni
Nome Descrzione
MobileAppId L'identificatore dell'applicazione per dispositivi mobili configurata in Customer Insights - Journeys.
ApiToken Il tuo token API per autorizzare la richiesta.
ID utente L'identificatore utente del contatto, lead o profilo Customer Insights - Data da Customer Insights - Journeys.
DeviceToken L'identificatore univoco del token del dispositivo generato dall'applicazione.