应用程序开发人员的推送通知设备注册

项目
04/01/2024

要了解有关在 Customer Insights - Journeys 中设置推送通知的总体方法的更多信息，请访问推送通知设置概述。

要在 Customer Insights - Journeys 中启用推送通知，您需要完成以下步骤：

此图描述了在 Customer Insights - Journeys 中注册设备和用户所需的两个步骤。

推送通知设备和用户注册关系图。

设备注册

要完成移动应用配置，开发人员必须跨服务器注册设备。您应该已经有设备令牌、Customer Insights - Journeys 中的用户 ID（联系人 ID、潜在顾客 ID、Customer Insights - Data 配置文件 ID）和 Customer Insights - Journeys 中的移动应用程序 ID。

在成功调用设备注册请求后，会有一个 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 中配置的移动应用程序的标识符。
用户 ID	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 中配置的移动应用程序的标识符。
用户 ID	Customer Insights - Journeys 中的联系人、潜在顾客或 Customer Insights - Data 配置文件的用户标识符。

重要提示

状态可能会卡在“挂起”状态的原因有三个：

原始设备注册请求具有无效 API 令牌。为了防止恶意行为者通过调用“注册设备”并生成无限限制来对环境执行 DoS 攻击，这种尝试不会产生注册历史记录的存储。因此，没有任何信息可以用来检查是否成功。
CRM 会在受限状态下停留数小时，导致状态更新操作在多次重试后无法执行作业。
设备注册请求发出时没有 x-ms-track-registration 标头。

设备注册状态 Webhook

如果在设备注册成功或失败时向 x-ms-status-callback-url 提供了 URL，Customer Insights - Journeys 将访问标头的值。

POST 到设备注册请求的 x-ms-status-callback-url 标头中提供的 URL。

正文:

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

小费

签名是使用 API 令牌作为密钥计算的回调 URL 的 HMACSHA256 哈希。使用此值验证 Customer Insights - Journeys 是否进行了调用。使用相同的算法并比较值，将回调 URL 与 webhook 一侧的 API 令牌进行哈希。

备注

发出请求的尝试只发生一次。任何执行请求的失败都会导致通知丢失。失败类型包括不正确的回调 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 令牌。
用户 ID	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 令牌。
用户 ID	Customer Insights - Journeys 中的联系人、潜在顾客或 Customer Insights - Data 配置文件的用户标识符。
DeviceToken	应用程序生成的唯一设备令牌标识符。

通过

应用程序开发人员的推送通知设备注册

设备注册

API

设备注册（单个）

定义

设备注册（多个）

设备注册状态

定义

设备注册状态 Webhook

设备清理（单个）

定义

设备清理（多个）

定义

其他资源