Freigeben über

Registrierung von Geräten für Pushbenachrichtigungen für Anwendungsentwicklungsfachkräfte

  • Artikel

Um mehr über den grundlegenden Ansatz zum Einrichten von Pushbenachrichtigungen in Customer Insights - Journeys zu erfahren, gehen Sie zu Übersicht über die Einrichtung von Pushbenachrichtigungen.

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

  1. Anwendungskonfiguration für Pushbenachrichtigungen
  2. Benutzerzuordnung für Pushbenachrichtigungen
  3. Geräteregistrierung für Pushbenachrichtigungen
  4. Pushbenachrichtigungen auf Geräten erhalten
  5. Interaktionsberichte für Pushbenachrichtigungen

Dieses Diagramm beschreibt die beiden Schritte, die zum Registrieren von Geräten und Benutzenden in Customer Insights - Journeys erforderlich sind.

Diagramm für die Registrierung von Geräten und Benutzenden Push-Benachrichtigungen.

Geräteregistrierung

Um die Konfiguration der mobilen App abzuschließen, muss die Entwicklungsfachkraft Geräte serverübergreifend registrieren. Sie sollten bereits über das Gerätetoken, die Benutzer-ID von Customer Insights - Journeys (Kontakt-ID, Lead-ID, Customer Insights - Data Profil-ID) und die ID der mobilen Anwendung von Customer Insights - Journeys verfügen.

Bei erfolgreichem Aufruf einer Geräteregistrierungsanforderung erfolgt eine 202-Antwort. Die 202-Antwort zeigt lediglich an, dass die Anforderung angenommen wurde. Um eine erfolgreiche Anforderung zu bestätigen, müssen Sie den Status überprüfen, indem Sie einen Webhook verwenden 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%"
}

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

Header:

  • x-ms-track-registration: Wenn „true“, werden die Informationen über den Erfolg/Misserfolg der Registrierung gespeichert und sind über die Registrierungsstatus-API verfügbar.
  • x-ms-callback-url: Wenn nicht leer, löst eine fehlgeschlagene oder erfolgreiche Geräteregistrierung einen POST-Anforderungs-Webhook aus.
  • x-ms-callback-url-headers: Enthält ein serialisiertes JSON eines String-zu-String-Wörterbuchs, das Header darstellt, die für Webhook-Anfragen übergeben werden. Wird nur verwendet, wenn x-ms-callback-url definiert ist.

Gibt zurück: 202, wenn die bereitgestellte Anforderung gültig ist, sonst 400.

Antworttext:

Wenn x-ms-track-registration auf „true“ eingestellt ist:

{
    "RegistrationRequestId": "%GUID%"
}

Ansonsten leerer Text.

Definitionen
Name des Dataflows Eigenschaft
MobileAppId Die Kennung der mobilen Anwendung, die in Customer Insights - Journeys konfiguriert ist.
UserId Die Benutzerkennung des Kontakts, Leads oder Customer Insights - Data-Profils von Customer Insights - Journeys.
ApiToken Ihr API-Token zur Autorisierung der Anforderung.
ApnsDeviceToken Die eindeutige Geräte-Token-ID, die von der iOS-Anwendung generiert wird. Diese wird nur für ein iOS-Gerät gesendet
FcmDeviceToken Die eindeutige Geräte-Token-ID, die von der Android-Anwendung generiert wird. Diese 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%"
    }
]

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

Header:

  • x-ms-track-registration: Wenn „true“, werden die Informationen über den Erfolg oder Misserfolg der Registrierung gespeichert und sind über die Registrierungsstatus-API verfügbar.
  • x-ms-callback-url: Wenn nicht leer, löst eine fehlgeschlagene oder erfolgreiche Geräteregistrierung einen POST-Anforderungs-Webhook aus.
  • x-ms-callback-url-headers: Enthält ein serialisiertes JSON eines Zeichenfolge-zu-Zeichenfolge-Wörterbuchs, das Header darstellt, die für Webhook-Anforderungen übergeben werden. Wird nur verwendet, wenn x-ms-callback-url festgelegt ist.

Gibt zurück: 202, wenn die bereitgestellte Anforderung gültig ist, sonst 400.

Antworttext:

Wenn x-ms-track-registrierung auf „true“ festgelegt ist: ein Array von Elementen, entspricht die Reihenfolge der einzelnen Elemente der Reihenfolge aus dem Anforderungstext-Array.

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

Ansonsten leerer Text.

Geräteregistrierungsstatus

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

Anforderungstext:

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

Gibt zurück: 200, wenn die bereitgestellte Anforderung gültig ist, sonst 400.

Anforderungstext: Ein Array von 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 Artikelbestellung entspricht der Bestellung des RegistrationRequestIds-Arrays.

Definitionen
Name des Dataflows Eigenschaft
RegistrationRequestIds Eine Reihe individueller Registrierungsanforderungen. Die Werte werden aus der Antwort der Registrierungsaufrufe übernommen. Diese wird nur bereitgestellt, wenn zur Registrierung der Header x-ms-track-registration verwendet wurde
MobileAppId Die Kennung der mobilen Anwendung, die in Customer Insights - Journeys konfiguriert ist.
UserId Die Benutzerkennung des Kontakts, Leads oder Customer Insights - Data-Profils von Customer Insights - Journeys.

Wichtig

Es gibt drei mögliche Gründe, warum der Status eventuell im Status „Ausstehend“ hängen bleibt:

  1. Die ursprüngliche Geräteregistrierungsanforderung enthielt ein ungültiges API-Token. Um zu verhindern, dass böswillige Akteure einen DoS-Angriff auf eine Umgebung durchführen, indem sie „Gerät registrieren“ aufrufen und eine unbegrenzte Drosselung erzeugen, führen solche Versuche nicht zu einer Speicherung des Registrierungsverlaufs. Damit liegen keine Informationen vor, um den Erfolg zu überprüfen.
  2. Das CRM bleibt mehrere Stunden lang in einem gedrosselten Zustand, was dazu führt, dass der Statusaktualisierungsvorgang seinen Auftrag nach mehreren Wiederholungsversuchen nicht ausführen kann.
  3. Die Geräteregistrierungsanforderung wurde ohne x-ms-track-registrierung-Header bereitgestellt.

Status-Webhook für Geräteregistrierung

Bei einer x-ms-Status-callback-url wird die URL bereitgestellt, wenn eine Geräteregistrierung erfolgreich oder fehlgeschlagen ist, Customer Insights - Journeys greift auf den Wert des Headers zu.

POST an die im x-ms-Status-callback-url-Header bereitgestellte URL der Geräteregistrierungsanforderung.

Textkörper:

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

Tipp

Die Signatur ist der HMACSHA256-Hash der Rückruf-URL, der unter Verwendung des API-Tokens als Schlüssel berechnet wird. Verwenden Sie den Wert, um zu überprüfen, ob Customer Insights - Journeys den Aufruf wirklich tätigt. Hashen Sie die Rückruf-URL mit dem API-Token auf der Seite des Webhooks, indem Sie denselben Algorithmus verwenden und die Werte vergleichen.

Anmerkung

Der Versuch, eine Anforderung zu stellen, erfolgt einmal. Wenn eine Anforderung nicht ausgeführt wird, geht die Benachrichtigung verloren. Zu den Fehlertypen gehören eine falsche Rückruf-URL, ein REST-API-Aufruf-Timeout oder ein unerwarteter Antwortstatuscode.

Gibt zurück: 202, wenn die bereitgestellte Anforderung gültig ist, sonst 400.

Erwarteter Text: Textfeld leer.

Gerätebereinigung (einzeln)

Es ist wichtig, Geräte, die nicht mehr gültig sind, aus der Datenbank zu entfernen, um eine leistungsstarke Nachrichtenübermittlung sicherzustellen. 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 bereitgestellte Anforderung gültig ist, sonst 400.

Definitionen
Name des Dataflows Eigenschaft
MobileAppId Die Kennung der mobilen Anwendung, die in Customer Insights - Journeys konfiguriert ist.
ApiToken Ihr API-Token zur Autorisierung der Anforderung.
UserId Die Benutzerkennung des Kontakts, Leads oder Customer Insights - Data-Profils von Customer Insights - Journeys.
DeviceToken Die eindeutige Geräte-Token-ID, die von der Anwendung generiert wird.

Gerätebereinigung (mehrfach)

Es ist wichtig, Geräte, die nicht mehr gültig sind, aus der Datenbank zu entfernen, um eine leistungsstarke Nachrichtenübermittlung sicherzustellen. 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 bereitgestellte Anforderung gültig ist, sonst 400.

Definitionen
Name des Dataflows Eigenschaft
MobileAppId Die Kennung der mobilen Anwendung, die in Customer Insights - Journeys konfiguriert ist.
ApiToken Ihr API-Token zur Autorisierung der Anforderung.
UserId Die Benutzerkennung des Kontakts, Leads oder Customer Insights - Data-Profils von Customer Insights - Journeys.
DeviceToken Die eindeutige Geräte-Token-ID, die von der Anwendung generiert wird.