Registrierung von Pushbenachrichtigungsgeräten für Anwendungsentwickler

Weitere Informationen zum allgemeinen Ansatz zum Einrichten von Pushbenachrichtigungen in Customer Insights – Journeys finden Sie in der Übersicht über die Einrichtung von Pushbenachrichtigungen.

Um Pushbenachrichtigungen in Customer Insights – Journeys zu aktivieren, müssen Sie die folgenden Schritte ausführen:

  1. Konfiguration der Pushbenachrichtigungsanwendung
  2. Benutzerzuordnung für Pushbenachrichtigungen
  3. Geräteregistrierung für Pushbenachrichtigungen
  4. Empfangen von Pushbenachrichtigungen auf Geräten
  5. Interaktionsberichte für Pushbenachrichtigungen

In diesem Diagramm werden die beiden Schritte beschrieben, die zum Registrieren von Geräten und Benutzern in Customer Insights – Journeys erforderlich sind.

Pushbenachrichtigungsgerät und Benutzerregistrierungsdiagramm.

Geräteregistrierung

Um die Konfiguration mobiler Apps abzuschließen, muss der Entwickler Geräte auf allen Servern registrieren. Sie sollten bereits über das Gerätetoken, die Benutzer-ID aus Customer Insights – Journeys (Kontakt-ID, Lead-ID, Customer Insights – Datenprofil-ID) und die mobile Anwendungs-ID aus Customer Insights - Journeys verfügen.

Bei einem erfolgreichen Aufruf einer Geräte-Registrierungsanforderung erfolgt eine 202-Antwort. Die Antwort 202 gibt nur an, dass die Anforderung akzeptiert wurde. Um eine erfolgreiche Anforderung zu bestätigen, müssen Sie den Status mithilfe eines Webhooks überprüfen oder den Statusendpunkt direkt aufrufen.

API

Geräteregistrierung (einzeln)

Beispiel-HTTP-Anforderung (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%"
}

Http-Beispielanforderung (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%"
}

Kopfzeilen:

  • x-ms-track-registration: Wenn wahr, werden die Informationen zum Registrierungserfolg/Fehler gespeichert und über die Registrierungsstatus-API verfügbar sein.
  • x-ms-callback-url: Wenn sie nicht leer ist, löst eine fehlgeschlagene oder erfolgreiche Geräteregistrierung einen Webhook mit einer POST-Anforderung aus.
  • x-ms-callback-url-headers: Enthält einen serialisierten JSON-Code eines Zeichenfolgen-zu-Zeichenfolge-Wörterbuchs, das Kopfzeilen darstellt, die für Webhook-Anforderungen übergeben werden. Wird nur verwendet, wenn x-ms-callback-url definiert ist.

Gibt zurück: 202, wenn die angegebene Anforderung gültig ist, andernfalls 400.

Antwortinhalt:

Wenn x-ms-track-registration wahr ist:

{
    "RegistrationRequestId": "%GUID%"
}

Ansonsten leerer Körper.

Definitionen
Name Description
MobileAppId Der Bezeichner der mobilen Anwendung, die in Customer Insights - Journeys konfiguriert ist.
Benutzer-ID Der Benutzerbezeichner des Kontakt-, Lead- oder Customer Insights - Data Profils aus Customer Insights - Journeys.
ApiToken Ihr API-Token zum Autorisieren der Anforderung.
ApnsDeviceToken Der eindeutige Gerätetokenbezeichner, der von der iOS-Anwendung generiert wird. Dies wird nur für ein iOS-Gerät gesendet.
FcmDeviceToken Der eindeutige Gerätetokenbezeichner, der von der Android-Anwendung generiert wird. Dies wird nur für ein Android-Gerät gesendet.

Geräteregistrierung (mehrfach)

Der Text der Batch-Registrierung enthält ein Array von bis zu 100 Objekten, die Geräteregistrierungsanforderungen darstellen.

Beispiel-HTTP-Anforderung (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%"
    }
]

Http-Beispielanforderung (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%"
    }
]

Kopfzeilen:

  • x-ms-track-registration: Wenn wahr, werden die Informationen zum Registrierungserfolg oder Fehler gespeichert und über die Registrierungsstatus-API verfügbar.
  • x-ms-callback-url: Wenn sie nicht leer ist, löst eine fehlgeschlagene oder erfolgreiche Geräteregistrierung einen POST Anforderungswebhook aus.
  • x-ms-callback-url-headers: Enthält einen serialisierten JSON-Code eines Zeichenfolgen-zu-Zeichenfolge-Wörterbuchs, das Kopfzeilen darstellt, die für Webhook-Anforderungen übergeben werden. Wird nur verwendet, wenn x-ms-callback-url definiert ist.

Gibt zurück: 202, wenn die angegebene Anforderung gültig ist, andernfalls 400.

Antwortinhalt:

Wenn x-ms-track-registration wahr ist: ein Array von Elementen, wobei die Reihenfolge jedes Elements derjenigen im Anforderungstextkörper-Array entspricht.

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

Ansonsten leerer Körper.

Geräteregistrierungsstatus

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

Anfrageinhalt:

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

Gibt zurück: 200, wenn die angegebene Anforderung gültig ist, andernfalls 400.

Antwortkörper - ein Array aus Elementen:

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

Jede Elementreihenfolge entspricht der Reihenfolge aus dem RegistrationRequestIds-Array .

Definitionen
Name Description
RegistrationRequestIds Ein Array einzelner Registrierungsanforderungen. Die Werte werden aus der Antwort der Registrierungsaufrufe entnommen. Dies wird nur bereitgestellt, wenn der x-ms-track-registration-Header für die Registrierung verwendet wurde.
MobileAppId Der Bezeichner der mobilen Anwendung, die in Customer Insights - Journeys konfiguriert ist.
Benutzer-ID Der Benutzerbezeichner des Kontakt-, Lead- oder Customer Insights - Data Profils aus Customer Insights - Journeys.

Important

Es gibt drei mögliche Gründe, warum der Status auf "Ausstehend" hängen bleibt.

  1. Die ursprüngliche Geräteregistrierungsanforderung hatte ein ungültiges API-Token. Um zu verhindern, dass bösartige Akteure einen DoS-Angriff auf eine Umgebung durchführen, indem sie "Gerät registrieren" aufrufen und unbegrenzte Drosselung erzeugen, erfolgt keine Speicherung des Registrierungsverlaufs bei solchen Versuchen. Daher gibt es keine Informationen, um den Erfolg zu überprüfen.
  2. Das CRM bleibt mehrere Stunden lang in einem gedrosselten Zustand, wodurch der Statusaktualisierungsvorgang nach mehreren Wiederholungen fehlschlägt.
  3. Die Geräteregistrierungsanforderung wurde ohne den bereitgestellten x-ms-track-registration-Header vorgenommen.

Geräteregistrierungsstatus-Webhook

Wenn eine x-ms-status-callback-url bereitgestellt wird, ruft Customer Insights - Journeys beim Erfolgen oder Scheitern einer Geräteregistrierung den Wert des Headers ab.

Senden Sie eine POST-Anfrage an die in der x-ms-status-callback-url-Header der Geräteregistrierungsanforderung enthaltene URL.

Körper:

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

Tip

Die Signatur ist der HMACSHA256 Hash der Rückruf-URL, die mit dem API-Token als Schlüssel berechnet wird. Verwenden Sie den Wert, um zu überprüfen, ob Customer Insights – Journeys den Anruf getätigt haben. Hashen Sie die Rückruf-URL mit dem API-Token auf der Webhook-Seite mithilfe desselben Algorithmus und vergleichen Sie die Werte.

Note

Ein Versuch, eine Anforderung vorzunehmen, erfolgt einmal. Alle Fehler beim Ausführen einer Anforderung führen dazu, dass die Benachrichtigung verloren geht. Fehlertypen umfassen eine falsche Rückruf-URL, ein REST-API-Anruf-Timeout oder einen unerwarteten Antwortstatuscode.

Gibt zurück: 202, wenn die angegebene Anforderung gültig ist, andernfalls 400.

Erwarteter Textkörper: leerer Text.

Gerätebereinigung (single)

Es ist wichtig, Geräte zu entfernen, die nicht mehr gültig sind, aus der Datenbank, um sicherzustellen, dass eine leistungsfähige Nachricht gesendet wird. Verwenden Sie den folgenden Ansatz, um alte Geräte-, Benutzer- und Anwendungskombinationen aus der Gerätetabelle zu entfernen.

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

Gibt zurück: 202, wenn die angegebene Anforderung gültig ist, andernfalls 400.

Definitionen
Name Description
MobileAppId Der Bezeichner der mobilen Anwendung, die in Customer Insights - Journeys konfiguriert ist.
ApiToken Ihr API-Token zum Autorisieren der Anforderung.
Benutzer-ID Der Benutzerbezeichner des Kontakt-, Lead- oder Customer Insights - Data Profils aus Customer Insights - Journeys.
DeviceToken (Geräte-Token) Der eindeutige Gerätetokenbezeichner, der von der Anwendung generiert wird.

Important

Wenn eine Customer Insights-Reise versucht, eine Pushbenachrichtigung an ein abgelaufenes Geräteregistrierungstoken zu senden, bereinigt das System automatisch das abgelaufene Token.

Gerätebereinigung (mehrere)

Es ist wichtig, Geräte zu entfernen, die nicht mehr gültig sind, aus der Datenbank, um sicherzustellen, dass eine leistungsfähige Nachricht gesendet wird. Verwenden Sie den folgenden Ansatz, um alte Geräte-, Benutzer- und Anwendungskombinationen aus der Gerätetabelle zu entfernen.

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

Gibt zurück: 202, wenn die angegebene Anforderung gültig ist, andernfalls 400.

Definitionen
Name Description
MobileAppId Der Bezeichner der mobilen Anwendung, die in Customer Insights - Journeys konfiguriert ist.
ApiToken Ihr API-Token zum Autorisieren der Anforderung.
Benutzer-ID Der Benutzerbezeichner des Kontakt-, Lead- oder Customer Insights - Data Profils aus Customer Insights - Journeys.
DeviceToken (Geräte-Token) Der eindeutige Gerätetokenbezeichner, der von der Anwendung generiert wird.
  • Last updated on