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

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

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	アプリケーションによって生成された一意のデバイストークン識別子。

その他のリソース

ドキュメント

アプリケーション開発者向けプッシュ通知の概要 - Dynamics 365 Customer Insights

Dynamics 365 Customer Insights - Journeys における通知の仕組みについて説明します。
モバイルデバイスでプッシュ通知を受け取る - Dynamics 365 Customer Insights

開発者: Customer Insights - Journeys からプッシュ通知を受信する方法について説明します。
アプリケーション開発者向けプッシュ通知ユーザーマッピング - Dynamics 365 Customer Insights

Dynamics 365 Customer Insights - Journeys におけるプッシュ通知の開発者設定ユーザーマッピングについて説明します。
プッシュ通知のアプリケーションを設定する - Dynamics 365 Customer Insights

Customer Insights - Journeys のプッシュ通知アプリケーションを設定する方法について
プッシュ通知の対話追跡を実装する - Dynamics 365 Customer Insights

開発者: Customer Insights - Journeys でプッシュ通知の対話を実装する方法について説明します。

トレーニング

モジュール

Implement device registration - Training

This module examines the process of device restrigration and discusses how to register and enroll devices in Active Directory.

次の方法で共有

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

デバイスの登録

API

デバイス登録 (単体)

定義

デバイス登録 (複数)

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

定義

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

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

定義

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

定義

その他のリソース