Udostępnij za pośrednictwem

Rejestracje urządzeń powiadomień push dla deweloperów aplikacji

  • Artykuł

Aby dowiedzieć się więcej o ogólnym podejściu do konfigurowania powiadomień push w Customer Insights - Journeys, odwiedź stronę omówienia konfiguracji powiadomień push.

Aby włączyć powiadomienia push w Customer Insights - Journeys, należy obserwować następujące kroki:

  1. Konfigurowanie aplikacji powiadomienia push
  2. Mapowanie użytkownika na powiadomienia push
  3. Rejestracja urządzenia dla powiadomień push
  4. Otrzymywanie powiadomień push na urządzeniach
  5. Raportowanie interakcji w powiadomieniu push

Ten diagram zawiera opis dwóch kroków niezbędnych do zarejestrowania urządzeń i użytkowników w aplikacji Customer Insights - Journeys.

Diagram rejestracji użytkowników i urządzeń użytkownika.

Rejestracja urządzenia

Aby zakończyć konfigurację aplikacji mobilnej, deweloper musi rejestrować urządzenia na wszystkich serwerach. Prawdopodobnie masz już token urządzenia, identyfikator użytkownika z Customer Insights - Journeys (identyfikator kontaktu, identyfikator potencjalnego klienta, identyfikator profilu Customer Insights - Data) i identyfikator aplikacji mobilnej z Customer Insights - Journeys.

Po pomyślnym wywołaniu żądania rejestracji urządzenia pojawia się odpowiedź 202. Odpowiedź 202 wskazuje jedynie, że żądanie zostało zaakceptowane. Aby potwierdzić pomyślne żądanie, należy sprawdzić stan przy użyciu elementu webhook lub wywołując bezpośrednio punkt końcowy stanu.

Interfejs API

Rejestracja urządzenia (pojedyncza)

Przykładowe żądanie 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%"
}

Przykładowe żądanie 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%"
}

Nagłówki:

  • x-ms-track-registration: w przypadku wartości „true” informacje o sukcesie/niepowodzeniu rejestracji będą przechowywane i udostępniane za pośrednictwem interfejsu API stanu rejestracji.
  • x-ms-callback-url: gdy wartość nie jest pusta, nieudana lub pomyślna rejestracja urządzenia wyzwala element webhook żądania metody POST.
  • x-ms-callback-url-headers: Zawiera seryjny plik JSON ze słownikiem ciągów i ciągów reprezentujący nagłówki przekazywane dla żądań typu webhook. Używany tylko w przypadku, gdy zostanie zdefiniowany adres URL x-ms-callback.

Zwraca: 202, jeśli żądanie jest prawidłowe, w przeciwnym razie 400.

Treść odpowiedzi:

Jeśli x-ms-track-registration ma wartość „true”:

{
    "RegistrationRequestId": "%GUID%"
}

W przeciwnym razie treść jest pusta.

Definicje
Nazwa/nazwisko Podpis
MobileAppId Identyfikator aplikacji mobilnej skonfigurowanej w Customer Insights - Journeys.
Identyfikator użytkownika Identyfikator użytkownika kontaktu, potencjalnego klienta lub profilu Customer Insights - Data z Customer Insights - Journeys.
ApiToken Token interfejsu API do autoryzowania żądania.
ApnsDeviceToken Unikatowy identyfikator tokenu urządzenia wygenerowany przez aplikację iOS. To będzie wysyłane tylko dla urządzenia iOS
FcmDeviceToken Unikatowy identyfikator tokenu urządzenia wygenerowany przez aplikację Android. To będzie wysyłane tylko dla urządzenia Android

Rejestracja urządzenia (wielokrotna)

Treść rejestracji zbiorczej zawiera tablicę z maksymalnie 100 obiektami reprezentującymi żądania rejestracji urządzenia.

Przykładowe żądanie 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%"
    }
]

Przykładowe żądanie 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%"
    }
]

Nagłówki:

  • x-ms-track-registration: w przypadku wartości „true” informacje o sukcesie lub niepowodzeniu rejestracji będą przechowywane i udostępniane za pośrednictwem interfejsu API stanu rejestracji.
  • x-ms-callback-url: gdy wartość nie jest pusta, nieudana lub pomyślna rejestracja urządzenia wyzwala element webhook żądania metody POST.
  • x-ms-callback-url-headers:: zawiera seryjny plik JSON ze słownikiem ciągów i ciągów reprezentujący nagłówki przekazywane dla żądań typu webhook. Używane tylko w przypadku zdefiniowania x-ms-callback-url.

Zwraca: 202, jeśli żądanie jest prawidłowe, w przeciwnym razie 400.

Treść odpowiedzi:

Jeśli x-ms-track-registration ma wartość „true”: tablica elementów, każde zamówienie elementu odpowiada zamówieniu z tablicy treści żądania.

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

W przeciwnym razie treść jest pusta.

Stan rejestracji urządzenia

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

Treść żądania:

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

Zwraca: 200, jeśli żądanie jest prawidłowe, w przeciwnym razie 400.

Treść odpowiedzi — tablica elementów:

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

Każde zamówienie elementu odpowiada zamówieniu z tablicy RegistrationRequestIds.

Definicje
Nazwa/nazwisko Podpis
RegistrationRequestIds Tablica poszczególnych żądań rejestracji. Wartości te pochodzi z odpowiedzi na rozmowy telefoniczne podjęte w związku z rejestracją. Dzieje się tak tylko w przypadku, gdy do rejestracji został użyty nagłówek x-ms-track-registration
MobileAppId Identyfikator aplikacji mobilnej skonfigurowanej w Customer Insights - Journeys.
Identyfikator użytkownika Identyfikator użytkownika kontaktu, potencjalnego klienta lub profilu Customer Insights - Data z Customer Insights - Journeys.

Ważne

Istnieją trzy możliwe przyczyny zablokowania w stanie „Oczekujące”:

  1. Oryginalne żądanie rejestracji urządzenia zawiera nieprawidłowy token interfejsu API. Aby zapobiec atakowi DoS na środowisko za pomocą wywoływania polecenia „register device” i generowania niekończącego się ograniczania, takie próby nie powodują przechowywania historii rejestracji. Dlatego nie ma żadnych informacji potwierdzających powodzenie.
  2. System CRM pozostaje w stanie ograniczenia przez wiele godzin, co powoduje niepowodzenie wykonywania operacji aktualizacji stanu po wielu próbach.
  3. Żądanie rejestracji urządzenia została wykonane bez podanego nagłówka x-ms-track-registration.

Element webhook stanu rejestracji urządzenia

Jeśli w x-ms-status-callback-url zostanie podany adres URL, gdy rejestracja urządzenia się powiedzie lub nie powiedzie się, Customer Insights - Journeys oceni wartość nagłówka.

POST do adresu URL podanego w nagłówku x-ms-status-callback-url żądania rejestracji urządzenia.

Treść:

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

Porada

Podpis to skrót HMACSHA256 adresu URL wywołania obliczanego przy użyciu tokenu interfejsu API jako klucza. Użyj wartości do sprawdzenia, czy aplikacja Customer Insights - Journeys przeprowadziła wywołanie. Użyj skrótu adresu URL wywołania z tokenem interfejsu API po stronie webhook, używając tego samego algorytmu i porównując wartości.

Uwaga

Próba żądania występuje raz. Niepowodzenia realizacji żądania spowodują, że powiadomienie zostanie utracone. Typy niepowodzenia zawierają niepoprawny adres URL wywołania, limit czasu wywołania interfejs API REST lub kod stanu nieoczekiwanej odpowiedzi.

Zwraca: 202, jeśli żądanie jest prawidłowe, w przeciwnym razie 400.

Oczekiwana treść: pusta treść.

Czyszczenie urządzenia (pojedyncze)

Ważne jest, aby usuwać z bazy danych urządzenia, które nie są już ważne, aby zapewnić wysyłanie komunikatów o wynikach. Skorzystaj z poniższego podejścia, aby usunąć stare kombinacje urządzenia, użytkownika i aplikacji z tabeli urządzeń.

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

Zwraca: 202, jeśli żądanie jest prawidłowe, w przeciwnym razie 400.

Definicje
Nazwa/nazwisko Podpis
MobileAppId Identyfikator aplikacji mobilnej skonfigurowanej w Customer Insights - Journeys.
ApiToken Token interfejsu API do autoryzowania żądania.
Identyfikator użytkownika Identyfikator użytkownika kontaktu, potencjalnego klienta lub profilu Customer Insights - Data z Customer Insights - Journeys.
DeviceToken Unikatowy identyfikator tokenu urządzenia wygenerowany przez aplikację.

Czyszczenie urządzenia (wielokrotne)

Ważne jest, aby usuwać z bazy danych urządzenia, które nie są już ważne, aby zapewnić wysyłanie komunikatów o wynikach. Skorzystaj z poniższego podejścia, aby usunąć stare kombinacje urządzenia, użytkownika i aplikacji z tabeli urządzeń.

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

Zwraca: 202, jeśli żądanie jest prawidłowe, w przeciwnym razie 400.

Definicje
Nazwa/nazwisko Podpis
MobileAppId Identyfikator aplikacji mobilnej skonfigurowanej w Customer Insights - Journeys.
ApiToken Token interfejsu API do autoryzowania żądania.
Identyfikator użytkownika Identyfikator użytkownika kontaktu, potencjalnego klienta lub profilu Customer Insights - Data z Customer Insights - Journeys.
DeviceToken Unikatowy identyfikator tokenu urządzenia wygenerowany przez aplikację.