應用程式開發人員的推播通知裝置註冊

發行項
04/01/2024

若要深入了解在 Customer Insights - Journeys 中設定推播通知的整體方法，請瀏覽推播通知設定概觀。

若要在 Customer Insights - Journeys 中啟用推播通知，您必須完成下列步驟：

此圖說明在 Customer Insights - Journeys 中註冊裝置和使用者所需的兩個步驟。

推播通知裝置和使用者註冊圖表。

裝置註冊

若要完成行動裝置應用程式組態，開發人員必須跨伺服器註冊裝置。您必須已經有裝置權杖、Customer Insights - Journeys 的使用者識別碼 (連絡人識別碼、潛在客戶識別碼、Customer Insights - Data 設定檔識別碼) ， Customer Insights - Journeys 的行動應用程式識別碼。

成功呼叫裝置註冊要求時，會收到 202 回應。 202 回應僅指示已接受要求。若要確認要求成功，您必須使用 webhook 或直接呼叫狀態端點來檢查狀態。

API

裝置註冊 (單一)

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

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

標頭：

x-ms-track-registration：值為 true 時，儲存有關註冊成功/失敗的資訊，並透過註冊狀態 API 提供這些資訊。
x-ms-callback-url：非空白時，失敗或成功的裝置註冊會觸發 POST 要求 webhook。
x-ms-callback-url-headers：包含字串至字串字典的序列化 JSON，表示 webhook 要求傳遞的標頭。只有在定義 x-ms-callback-url 時才使用。

傳送值：如果提供的要求有效，則為 202，否則為 400。

回應本文：

當 x-ms-track-registration 為 true 時：

{
    "RegistrationRequestId": "%GUID%"
}

否則，本文空白。

定義

名稱	描述
MobileAppId	Customer Insights - Journeys 中設定的行動應用程式識別碼。
UserId	Customer Insights - Journeys 中連絡人、潛在客戶或 Customer Insights - Data 設定檔的使用者識別碼。
ApiToken	用於授權七求的 API 權杖。
ApnsDeviceToken	iOS 應用程式產生的唯一裝置權杖識別碼。這只針對 iOS 裝置進行傳送
FcmDeviceToken	Android 應用程式產生的唯一裝置權杖識別碼。這只針對 Android 裝置進行傳送

裝置註冊 (多個)

批次註冊的本文包含一個最多有 100 個表示裝置註冊要求的物件的陣列。

範例 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%"
    }
]

範例 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%"
    }
]

標頭：

x-ms-track-registration：值為 true 時，儲存有關註冊成功或失敗的資訊，並透過註冊狀態 API 提供這些資訊。
x-ms-callback-url：非空白時，失敗或成功的裝置註冊會觸發 POST 要求 webhook。
x-ms-callback-url-headers：包含字串對字串字典的序列化 JSON，表示 webhook 要求傳遞的標頭。僅在定義 x-ms-callback-url 時使用。

傳送值：如果提供的要求有效，則為 202，否則為 400。

回應本文：

當 x-ms-track-registration為 true 時：項目陣列，每個項目順序都對應至要求本文陣列中的順序。

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

否則，本文空白。

裝置註冊狀態

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

要求本文：

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

傳送值：如果提供的要求有效，則為 200，否則為 400。

回應本文 - 項目的陣列：

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

每個項目順序都對應至 RegistrationRequestIds 陣列中的順序。

定義

姓名	描述
RegistrationRequestIds	一系列個別註冊要求。這些值取自註冊呼叫的回應。只有在使用 x-ms-track-registration 標頭進行註冊時，才會提供此功能
MobileAppId	Customer Insights - Journeys 中設定的行動應用程式識別碼。
UserId	Customer Insights - Journeys 中連絡人、潛在客戶或 Customer Insights - Data 設定檔的使用者識別碼。

重要

狀態停滯在「擱置中」狀態的可能原因有三個：

原始裝置註冊要求的 API 權杖無效。為了防止惡意行為者藉由呼叫「註冊裝置」以及產生無限節流來對環境執行 DoS 攻擊，此類嘗試不會產生儲存註冊歷程記錄的動作。因此沒有用於檢查成功與否的資訊。
CRM 保持在節流狀態長達數小時，導致狀態更新作業在多次重試後仍無法執行其工作。
裝置註冊要求是在未提供 x-ms-track-registration 標頭的情況下提出。

裝置註冊狀態 webhook

如果在裝置註冊成功或失敗時提供 x-ms-status-callback-url，則 Customer Insights - Journeys 會存取標頭的值。

裝置註冊要求 x-ms-status-callback-url 標頭中所提供 URL 的 POST。

本文:

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

提示

簽章是使用 API 權杖做為金鑰計算得出之回撥 URL 的 HMACSHA256 雜湊。使用此值驗證 Customer Insights - Journeys 是否已進行呼叫。使用相同的演算法並比較這些值，在 webhook 端透過 API 權杖計算回撥 URL 的雜湊。

注意

發出要求的嘗試只會進行一次。任何無法執行要求的失敗都會導致通知遺失。失敗類型包括回撥 URL 不正確、REST API 呼叫逾時或回應狀態碼超乎預期。

傳送值：如果提供的要求有效，則為 202，否則為 400。

預期本文：空白本文。

裝置清理 (單一)

請務必從資料庫移除不再有效的裝置，以確保訊息傳送效能。使用下列方法從裝置資料表中移除舊的裝置、使用者與應用程式組合。

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

傳送值：如果提供的要求有效，則為 202，否則為 400。

定義

名稱	描述
MobileAppId	Customer Insights - Journeys 中設定的行動應用程式識別碼。
ApiToken	用於授權七求的 API 權杖。
UserId	Customer Insights - Journeys 中連絡人、潛在客戶或 Customer Insights - Data 設定檔的使用者識別碼。
DeviceToken	應用程式產生的唯一裝置權杖識別碼。

裝置清理 (多個)

請務必從資料庫移除不再有效的裝置，以確保訊息傳送效能。使用下列方法從裝置資料表中移除舊的裝置、使用者與應用程式組合。

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

傳送值：如果提供的要求有效，則為 202，否則為 400。

定義

名稱	描述
MobileAppId	Customer Insights - Journeys 中設定的行動應用程式識別碼。
ApiToken	用於授權七求的 API 權杖。
UserId	Customer Insights - Journeys 中連絡人、潛在客戶或 Customer Insights - Data 設定檔的使用者識別碼。
DeviceToken	應用程式產生的唯一裝置權杖識別碼。

共用方式為

應用程式開發人員的推播通知裝置註冊

裝置註冊

API

裝置註冊 (單一)

定義

裝置註冊 (多個)

裝置註冊狀態

定義

裝置註冊狀態 webhook

裝置清理 (單一)

定義

裝置清理 (多個)

定義

其他資源