アプリケーション開発者向けプッシュ通知のデバイス登録

[アーティクル]
04/01/2024

Customer Insights - Journeys でプッシュ通知を設定するための全体的なアプローチの詳細については、プッシュ通知設定の概要を参照してください。

Customer Insights - Journeys でプッシュ通知を有効にするには、次の手順を完了する必要があります。

以下の図は、Customer Insights - Journeys 内でデバイスとユーザーを登録するために必要な 2 つの手順を示しています。

プッシュ通知デバイスとユーザー登録の図。

デバイスの登録

モバイルアプリの構成を完了するには、開発者はサーバー間でデバイスを登録する必要があります。デバイストークン、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: webhook リクエストに渡されるヘッダーを表す、文字列対文字列辞書のシリアル化された JSON が含まれます。 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: webhook 要求に渡されるヘッダーを表す、文字列対文字列辞書のシリアル化された JSON が含まれます。 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 プロファイル。

重要

ステータスが「保留中」状態のままになる原因として、次の 3 つが考えられます:

元のデバイス登録要求には無効な API トークンがありました。悪意のある攻撃者が「デバイスの登録」を呼び出して、無限のスロットルを生成することによって、環境に対して DoS 攻撃を行うことを防ぐために、そのような試みは登録履歴の保存を生成しません。したがって、成功を確認するための情報はありません。
CRM は数時間にわたって調整された状態のままになるため、複数回再試行した後、ステータス更新操作がジョブの実行に失敗します。
デバイス登録要求は、x-ms-track-registration ヘッダーを指定せずに行われました。

デバイス登録のステータス webhook

デバイス登録が成功または失敗したときに x-ms-status-callback-url に 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 をハッシュします。

注意

要求の試行は 1 回だけ行われます。要求の実行に失敗すると、通知が失われます。失敗の種類には、不正なコールバック 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

デバイスのクリーンアップ (単体)

定義

デバイスのクリーンアップ (複数)

定義

その他のリソース