Decisioning Migration API decisioning-migration-api

このページ: Decisioning Migration Service API を使用して、依存関係の自動分析やロールバックのサポートを備えたサンドボックス間で意思決定管理オブジェクトを移行します。これにより、データの整合性を保持しながら、環境間で意思決定コンテンツを移行できます。

Decisioning Migration Service API を使用すると、あるサンドボックスから別のサンドボックスに意思決定管理オブジェクトを移行できます。 移行プロセスは、依存関係の分析、実行、オプションのロールバック機能を含む非同期ワークフローとして実行されます。

この API を使用すると、データの整合性と関係を保持しながら、環境間で意思決定コンテンツをシームレスに移行できます。

意思決定管理と比較した決定のメリットと機能について詳しくは、このページを参照してください。

機能 capabilities

Decisioning Migration Service API には、次の機能が用意されています。

  • 依存関係分析 - 属性、セグメント、データセット要件など、ソースサンドボックスとターゲットサンドボックス間に必要なすべての依存関係を特定します。
  • 柔軟な移行スコープ - 必要に応じて、サンドボックス、オファー、決定レベルで移行を実行します。
  • ロールバックのサポート - 検証中に問題が検出された場合、完了した移行を元に戻します。

前提条件 prerequisites

必要な権限 permissions

Migration API を使用するには、ソースサンドボックスとターゲットサンドボックスの両方に適切な権限が必要です。

ソースサンドボックス - 意思決定管理オブジェクトへの読み取りアクセス権

ターゲットサンドボックス - 意思決定管理オブジェクトへの作成および編集アクセス権

一般的な権限は次のとおりです。

  • 意思決定の管理/表示
  • 決定の管理/表示
  • オファーの管理
  • ランキング戦略の管理
  • キャンペーンの管理(キャンペーン関連のアーティファクトを移行する場合)
  • データストリームの管理/表示(データストリームを作成する場合)
  • スキーマの管理/表示
NOTE
決定権限を割り当てる方法について詳しくは、この節を参照してください。 権限の完全なリストについて詳しくは、ビルトインの権限ページを参照してください。

ターゲットサンドボックスの準備 target-sandbox-preparation

移行を実行する前に、ターゲットサンドボックスが適切に設定されていることを確認します。

  • 属性 - 必要なプロファイル属性とコンテキスト属性がターゲットサンドボックスに存在することを確認するか、マッピングを準備します。
  • セグメント - 必要なセグメントがターゲットサンドボックスに存在することを確認するか、名前空間と ID を使用してセグメントをマッピングすることを計画します。
  • データセット - 移行に使用するデータセット名(dependency.datasetName)を特定します。
  • データストリーム - 移行でデータストリーム(createDataStream)を作成するかどうかを決定します。

サンドボックス管理について詳しくは、サンドボックスの使用と割り当てを参照してください。

NOTE
ターゲットサンドボックスは、ソースサンドボックスと同じにできます。 移行プロセスではこのシナリオに対応し、オブジェクトが同じサンドボックス内または別のサンドボックスに移行されるかどうかに関係なく、データの整合性が確保されます。

クロスサンドボックス移行の前提条件 cross-sandbox-prerequisites

ソースサンドボックス ≠ ターゲットサンドボックスの場合、次の項目は必須です。

  • プロファイル属性 - ターゲットサンドボックスに存在するか、事前定義済みのマッピングが必要です
  • セグメント ID - 古い ID → 新しい ID のマッピングを使用して、ターゲットサンドボックスに事前に作成する必要があります。
  • ID マッピング - 一貫性のある ID 解決のために設定する必要があります

API の基本 api-basics

ベース URL base-url

次のベース URLを使用します。

  • 本番:https://decisioning-migration.adobe.io

認証 authentication

すべての API リクエストには、次のヘッダーが必要です。

  • Authorization: Bearer <IMS_ACCESS_TOKEN>
  • x-gw-ims-org-id: <IMS_ORG_ID>
  • Content-Type: application/json

認証の設定手順について詳しくは、Journey Optimizer 認証ガイドを参照してください。

移行ワークフロー migration-workflow

移行プロセスは、依存関係の分析と移行の実行という 2 つの主な手順で構成されます。 移行を成功させるには、次の手順に従います。

手順 1:依存関係を分析 analyze-dependencies

移行前に、依存関係ワークフローを使用して、ターゲットサンドボックスの意思決定管理から決定にマッピングする必要がある項目を特定します。 この分析は、オブジェクト間の関係を理解し、必要なマッピングを準備するのに役立ちます。

依存関係ワークフローの作成 create-dependency-workflow

次の API 呼び出しを使用して、依存関係分析ワークフローを作成します。

API 形式

POST /workflows/generate-dependencies

サンドボックスレベルの依存関係(最初に推奨)

サンドボックスレベルの分析から始めて、すべての依存関係を包括的に把握します。

curl --request POST \
  --url "https://decisioning-migration.adobe.io/workflows/generate-dependencies?request-level=sandbox" \
  --header "Authorization: Bearer <IMS_ACCESS_TOKEN>" \
  --header "x-gw-ims-org-id: <IMS_ORG_ID>" \
  --header "Content-Type: application/json" \
  --data '{
    "imsOrgId": "<IMS_ORG_ID>",
    "sourceSandboxDetails": { "sandboxName": "<SOURCE_SANDBOX_NAME>" },
    "targetSandboxDetails": { "sandboxName": "<TARGET_SANDBOX_NAME>" }
  }'

オファーレベルの依存関係

特定のオファーの依存関係のみを分析するには、クエリ文字列に request-level=offer を含む同じエンドポイントを呼び出し、分析するオファー ID を含む offersList 配列を本文に指定します。

決定レベルの依存関係

特定の決定の依存関係のみを分析するには、クエリ文字列に request-level=decision を使用し、分析する決定 ID を含む decisionsList 配列を本文に指定します。

依存関係ワークフローのステータスの確認 poll-dependency-status

依存関係ワークフローをポーリングして、分析が完了した際に確認します。

API 形式

GET /workflows/generate-dependencies/{id}

リクエスト

curl --request GET \
  --url "https://decisioning-migration.adobe.io/workflows/generate-dependencies/<WORKFLOW_ID>" \
  --header "Authorization: Bearer <IMS_ACCESS_TOKEN>" \
  --header "x-gw-ims-org-id: <IMS_ORG_ID>"

「status」フィールドに Completed が表示されると、依存関係の分析の準備は完了です。 ワークフロー出力を使用して、移行依存関係マッピングを作成します。

  • profileAttributes - ソースプロファイル属性をターゲットプロファイル属性にマッピングします
  • contextAttributes - ソースコンテキスト属性をターゲットコンテキスト属性にマッピングします
  • segments - ソースセグメントキーをターゲットセグメント識別子({namespace, id})にマッピングします
  • datasetName - 移行に使用されるターゲットのエクスペリエンスイベントデータセット。 このスキーマは、Journey Optimizer Edge(Web SDK)呼び出しに対して有効になっているデータストリームに接続する必要があります。このスキーマは、移行されたコンテキスト属性の追加に使用されます。

これらのマッピングは、手順 2 の移行リクエストの dependency オブジェクトで指定します。

手順 2:移行を実行 execute-migration

依存関係を分析し、マッピングの準備が整ったら、移行を実行できます。

移行ワークフローの作成 create-migration-workflow

手順 1 の依存関係マッピングを使用して、移行を設定および実行します。

API 形式

POST /workflows/migration

サンドボックスレベルの移行

すべての決定オブジェクトをあるサンドボックスから別のサンドボックスに移行するには:

curl --request POST \
  --url 'https://decisioning-migration.adobe.io/workflows/migration?request-level=sandbox' \
  --header 'Authorization: Bearer <IMS_ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --header 'x-gw-ims-org-id: <IMS_ORG_ID>' \
  --data '{
    "imsOrgId": "<IMS_ORG_ID>",
    "sourceSandboxDetails": { "sandboxName": "<SOURCE_SANDBOX_NAME>" },
    "targetSandboxDetails": { "sandboxName": "<TARGET_SANDBOX_NAME>" },
    "createDataStream": true,
    "dependency": {
      "profileAttributes": {
        "sourceAttr1": "targetAttr1"
      },
      "segments": {
        "sourceSegmentKey1": {
          "namespace": "<TARGET_SEGMENT_NAMESPACE>",
          "id": "<TARGET_SEGMENT_ID>"
        }
      },
      "contextAttributes": {
        "sourceCtx1": "targetCtx1"
      },
      "datasetName": "<TARGET_DATASET_NAME>"
    }
  }'

オファーレベルの移行

特定のオファーのみを移行するには、クエリ文字列に request-level=offer を使用し、offersList 配列を本文に追加します。

"offersList": ["offer-id-1", "offer-id-2"]

決定レベルの移行

特定の決定のみを移行するには、クエリ文字列に request-level=decision を使用し、decisionsList 配列を本文に追加します。

"decisionsList": ["decision-id-1", "decision-id-2"]

リクエストフィールド

  • request-level(クエリ)- 移行範囲:sandbox、offer、decision。
  • imsOrgId(必須)- IMS 組織 ID。
  • sourceSandboxDetails.sandboxName(必須)- 意思決定管理エンティティを保持するソースサンドボックス。
  • targetSandboxDetails.sandboxName(必須)- 決定エンティティが作成されるターゲットサンドボックス。
  • dependency.datasetName(必須)- ターゲットのエクスペリエンスイベントデータセット。 このスキーマは、Journey Optimizer Edge(Web SDK)呼び出しに対して有効になっているデータストリームに接続する必要があります。このスキーマは、移行されたコンテキスト属性の追加に使用されます。
  • createDataStream - true は、新しい Journey Optimizer 対応データストリームを作成します。false は、既に dependency.datasetName のデータセットに添付されているものを再利用します。
  • dependency.profileAttributes - ソース → ターゲットプロファイル属性のマッピング。
  • dependency.contextAttributes - ソース → ターゲットコンテキスト属性のマッピング。
  • dependency.segments - ソースセグメントキー → ターゲットセグメント({namespace, id})のマッピング。
  • offersList[]/decisionsList[] - 移行するオファーまたは決定 ID。request-level がそれぞれ offer または decision である場合に必須です。

移行ステータスの監視 poll-migration-status

移行ワークフローをポーリングして、進行状況を追跡します。

API 形式

GET /workflows/migration/{id}

リクエスト

curl --request GET \
  --url "https://decisioning-migration.adobe.io/workflows/migration/<WORKFLOW_ID>" \
  --header "Authorization: Bearer <IMS_ACCESS_TOKEN>" \
  --header "x-gw-ims-org-id: <IMS_ORG_ID>"

移行結果

「status」フィールドに Completed が表示された場合、移行は成功しました。 ワークフロー result には、以下が含まれます。

  • 移行されたオブジェクトのマッピング
  • 移行中に発生した警告

「status」フィールドに Failed が表示された場合、errors[] 配列と「result.error」フィールドで、問題の詳細を確認します。

すべてのワークフロー(依存関係、移行、ロールバック)は、同じリソースフィールドを返します。

  • id - ワークフロー識別子(UUID)。一致する GET /{id} でステータスをポーリングします。
  • status - ライフサイクルの状態:New、Running、Completed、Failed。
  • result - Completed の際に表示されます。ワークフロー出力(例:移行されたオブジェクトのマッピングや警告)。
  • errors[] - Failed の際に表示されます。構造化エラーの詳細(result.error も参照)。
  • _links.self - ワークフローリソースの URL。

移行の検証 validate-migration

移行が正常に完了したら、すべてのオブジェクトが正しく移行されたことを確認します。

検証チェックリスト validation-checklist

  1. セグメント - 参照されているすべてのセグメントが、マッピングに従ってターゲットサンドボックスで正しく解決されていることを確認します。

  2. 属性 - すべてのプロファイル属性とコンテキスト属性がターゲットサンドボックスに存在し、正しくマッピングされていることを確認します。

  3. 決定オブジェクト - Journey Optimizer ユーザーインターフェイスで移行されたオブジェクトを確認します。

    • オファー(決定項目)
    • 実施要件ルール
    • ランキング式
    • 選択戦略
    • 決定ポリシー
  4. データストリームテスト - データストリームが作成された場合は、Edge Interact API を使用してランタイム配信をテストします。

例 test-runtime-delivery

移行でデータストリームを作成した場合は、次の例を使用してオファー配信をテストできます。

curl --request POST \
  --url "https://edge.adobedc.net/ee/or2/v1/interact?configId=<DATASTREAM_ID>" \
  --header "Content-Type: application/json" \
  --header "x-request-id: <uuid>" \
  --data '{ "events": [ ... ] }'

移行のロールバック rollback

検証中に問題が発生した場合は、完了した移行をロールバックして、ターゲットサンドボックスを以前の状態に復元できます。

ロールバックワークフローの作成 create-rollback-workflow

元に戻す移行を参照するロールバックワークフローを作成して、ロールバックを開始します。

API 形式

POST /workflows/rollback

リクエスト

curl --request POST \
  --url "https://decisioning-migration.adobe.io/workflows/rollback" \
  --header "Authorization: Bearer <IMS_ACCESS_TOKEN>" \
  --header "x-gw-ims-org-id: <IMS_ORG_ID>" \
  --header "Content-Type: application/json" \
  --data '{ "rollbackWorkflowId": "<MIGRATION_WORKFLOW_ID>" }'

<MIGRATION_WORKFLOW_ID> を、ロールバックする移行ワークフローの ID に置き換えます。

ロールバックステータスの監視 poll-rollback-status

ロールバックワークフローをポーリングして、進行状況を追跡します。

API 形式

GET /workflows/rollback/{rollbackWorkflowId}

リクエスト

curl --request GET \
  --url "https://decisioning-migration.adobe.io/workflows/rollback/<ROLLBACK_WORKFLOW_ID>" \
  --header "Authorization: Bearer <IMS_ACCESS_TOKEN>" \
  --header "x-gw-ims-org-id: <IMS_ORG_ID>"

同時ワークフローの処理 handle-concurrency

Migration API では、組織ごとに一度に 1 つのワークフローのみを実行できます。 別のワークフローが進行中の間に新しいワークフローを作成しようとすると、409 競合​エラー応答(「ワークフローは既に進行中です…」)が受信されます。

この場合、進行中のワークフローが完了するのを待つか、ワークフロー ID を取得してステータスをポーリングします。 現在のワークフローが完了したら、新しいワークフローを作成できます。

移行範囲とカバレッジ migration-scope

移行の範囲を把握することは、意思決定管理から決定への移行を計画し、検証するのに役立ちます。 この節では、移行プロセスで対象とする内容と、手動でのアクションが必要な内容の概要について説明します。

範囲内:対象とする内容 in-scope

Migration API は、次の項目と機能を処理します。

  • ユースケース - インバウンド/Edge 決定のユースケースのみが範囲内です。 Journey Optimizer メールチャネル移行のアウトバウンドまたは OD はサポートされていますが、手動での更新が必要です。
  • コードベースのエクスペリエンスキャンペーン - 移行中に自動的に作成され、移行後の決定範囲ごとに 1 つのキャンペーンがターゲットサンドボックスに作成されます。
  • チャネル設定/サーフェス - 意思決定管理プレースメントごとに作成されたチャネル設定/サーフェスで、決定応答の適切なルーティングが確保されます。
  • オファーコンテンツタイプ - コンテンツタイプが JSON またはテキストの場合にのみ、オファーが移行されます。 その他のコンテンツタイプには、手動での再作成が必要です。
  • オファー特性 - カスタムメタデータを維持しながら、「パーソナライズされたオファー項目 - エクスペリエンス決定」スキーマの offer_item_custom_attributes フィールドグループに保持されます。
  • コンテキスト属性 - トラッキングとパーソナライゼーション用に、custom_context_attributes フィールドグループのエクスペリエンスイベントスキーマに追加されました。
  • 決定範囲 - 1 つの意思決定管理の決定範囲が、1 つの選択戦略 + 1 つの決定ポリシー + 決定の 1 つのキャンペーンにマッピングされ、適切なエンティティ階層が確保されます。
  • API のみの実施要件ルール -(意思決定管理 UI ではなく)API 経由で作成された実施要件ルールは移行され、決定では API のみが維持されます。 また、UI 作成ルールも移行されます。

範囲外:対象としない内容または手動でのアクションが必要な内容 out-of-scope

次の項目は、手動でのアクションが必要ですが、移行ツールでサポートされていません。

  • 決定プレースメント - 移行ツールでプレースメントが作成されていません。 アーキテクチャに基づいて、移行前または移行後に決定でこれらを手動で作成する必要があります。
  • プレースメントレベルのキャップ - プレースメントレベルのフリークエンシーキャップは移行されません。
  • JSON /テキスト以外のオファーコンテンツ - JSON またはテキスト以外のコンテンツタイプ(例:HTML、画像)を含むオファーは移行されず、決定で手動での再作成が必要です。
  • プロファイル属性とセグメント - プロファイル属性とセグメントメンバーシップは、移行ツールで作成または編集されることはありません。 移行を実行する前に、これらはターゲットサンドボックスに既に存在している必要があります。
  • セグメント ID マッピング - セグメント ID は、ターゲットサンドボックスで事前に作成する必要があります。 セグメント解決の Migration API リクエストで古い ID → 新しい ID のマッピングを指定する必要があります。
  • データ収集コードの変更 - クライアントサイドおよびサーバーサイドのイベントトラッキングコードの変更は自動化されていません。 実装チームは、決定リクエスト/応答形式と決定イベントスキーマを使用するために、イベント収集を更新する必要があります。

エンティティマッピング参照 entity-mapping

意思決定管理から決定に移行する際、エンティティは次の表に従ってマッピングされます。 マッピングには、プライマリ決定エンティティと、移行中に作成または使用される追加の関連エンティティが含まれます。

意思決定管理から決定エンティティへのマッピング

意思決定管理エンティティ
決定エンティティ
追加エンティティ
決定
選択戦略
項目収集、実施要件ルール、ランキング式
決定ポリシー
項目数、選択戦略、フォールバックオファー項目
コードベースのエクスペリエンスキャンペーン
決定ポリシー、コンテンツ、チャネル設定、Journey Optimizer フラグメント
プレースメント
チャネル設定
—
コレクション
項目コレクション
統合タグ、オファー項目
コレクション修飾子
統合タグ
—
ルール
決定ルール
—
ランキング式
決定ランキング式
—
オファー
オファー項目
実施要件ルール、Journey Optimizer フラグメント、統合タグ、フリークエンシーキャップ
オファー項目スキーマ
—
Journey Optimizer フラグメント
—

命名規則

移行プロセスでは、一貫性を確保し、名前の競合を防ぐために、ExD_ 接頭辞を使用した命名規則が適用されます。

ソースオブジェクト
意思決定管理名パターン
決定名パターン
オファー
<offerName>
ExD_<offerName>
実施要件ルール
<ruleName>
ExD_<ruleName>
ランキング式
<formulaName>
ExD_<formulaName>
コレクション
<collectionName>
ExD_<collectionName>_<placementName>
決定 → 選択戦略
<decisionName>
ExD_<decisionName>_selection_strategy_<index>
決定 → 決定ポリシー
<decisionName>
ExD_<decisionName>_<placementName>
Journey Optimizer フラグメント
<offerName>
ExD_<offerName>_<placementName>_<index>
プレースメント → サーフェス
<placementName>
ExD_<placementName> (スペース/ドットはアンダースコアに変換されます)
統合タグ
<sourceName>, <targetName>
ExDMigration_<sourceName>_<targetName>
CBE キャンペーン
<decisionName>, <placementName>
Campaign for <decisionName> : <placementName>

その他の属性

ソース属性
ターゲットの場所
オファー属性
パーソナライズされたオファー項目スキーマの「migratedofferattributes」フィールド
コンテキスト属性
移行中に指定したデータセットに添付されたスキーマの「migratedcontextattributes」フィールド

リクエストと応答のモデル request-response-model

意思決定管理から決定に移行する場合は、新しいリクエスト形式と応答形式を使用するようにアプリケーションコードを更新する必要があります。 両方のシステムで Edge Network エンドポイントを使用しますが、ペイロード構造やフィールド名は異なります。

意思決定管理 Edge リクエスト(現在) dm-request

現在の意思決定管理 Edge リクエストは、次の構造に従います。

エンドポイント:

POST https://edge.adobedc.net/ee/v2/interact

ヘッダー:

  • Authorization: Bearer <IMS_ACCESS_TOKEN>
  • x-api-key: <API_KEY>(Developer Console から)
  • x-gw-ims-org-id: <IMS_ORG_ID>(形式:{ORG_ID}@AdobeOrg)
  • x-request-id: <UNIQUE_REQUEST_ID>(トレースと重複排除の場合)
  • Content-Type: application/vnd.adobe.xdm+json; schema="…/decision-request;version=1.0"
  • Accept: application/vnd.adobe.xdm+json; schema="…/decision-response;version=1.0"
  • x-sandbox-name: <SANDBOX_NAME>(例:本番、開発)

リクエスト本文パラメーター:

  • xdm:dryRun(true/false)- レポートを汚染せずにリクエストをテスト

  • xdm:propositionRequests[] - 決定リクエストの配列:

    • activityId - 決定アクティビティ識別子
    • placementId - プレースメント識別子
    • itemCount - 返されるオファーの最大数
  • xdm:profiles[].xdm:identityMap - ID マッピング(メール、ECID など)

  • xdm:validateContextData - 厳密なコンテキストデータ検証フラグ

  • xdm:responseFormat.xdm:includeContent - 実際のコンテンツと ID のみを含める

リクエスト本文の例:

{
  "xdm": {
    "dryRun": false,
    "propositionRequests": [
      { "activityId": "<ACTIVITY_ID>", "placementId": "<PLACEMENT_ID>", "itemCount": 3 }
    ],
    "profiles": [
      { "identityMap": { "ECID": [ { "id": "<ECID>", "primary": true } ] } }
    ],
    "validateContextData": true,
    "responseFormat": { "includeContent": true }
  }
}
NOTE
完全な意思決定管理(OD)リクエスト/応答の参照について詳しくは、Edge Decisioning API(Web SDK/Edge バリアント。activityId と placementId を含む base64 エンコードされた decisionScopes を使用)を参照してください。

決定 Edge リクエスト(移行後) decisioning-request

移行後、同じ Edge Network エンドポイント経由で決定リクエスト形式を使用します。

エンドポイント:

POST https://edge.adobedc.net/ee/v2/interact

主なリクエストフィールド:

  • query.identity.fetch - 解決する ID タイプの配列(例:["ECID"])
  • event.xdm.environment.type - 環境タイプ:"browser"、"app"、"server"
  • event.xdm.environment.browserDetails - ブラウザーメタデータ(viewportWidth、viewportHeight、userAgent)
  • event.xdm.identityMap - 意思決定管理と同じ ID マッピング
  • event.xdm.timestamp - ISO 8601 タイムスタンプ
  • query.personalization.surfaces - ターゲットサーフェスの配列(例:["web://site.com/homepage"])- decisionScopeを置き換え
  • query.personalization.schemas - 返されるコンテンツスキーマ(例:["json-content-item", "html-content-item"])
  • data.__adobe.ajo.allowDuplicateDecisionItems - 重複排除コントロール(デフォルトは true。false に設定すると、複数のサーフェスで選定される項目は 1 回のみ返され、他のサーフェスではフォールバック/空の項目を受信します)。 意思決定管理の allowDuplicatePropositions を置き換えます。
  • data.__adobe.ajo.dryRun - テストフラグ。レポートカウンターとキャップカウンターの両方のフィードバックイベントを抑制します。 意思決定管理の xdm:dryRun を置き換えます。 本番前に削除します。

リクエスト本文の例(サーバーサイド):

{
  "events": [
    {
      "query": {
        "identity": { "fetch": ["ECID"] },
        "personalization": {
          "surfaces": ["web://my-web/IP_NLI_HP_GET_LOAN_WIDGET"],
          "schemas": [
            "https://ns.adobe.com/personalization/json-content-item",
            "https://ns.adobe.com/personalization/html-content-item"
          ]
        }
      },
      "xdm": {
        "eventType": "decisioning.propositionFetch",
        "environment": {
          "type": "browser",
          "browserDetails": { "viewportWidth": 1280, "viewportHeight": 900, "userAgent": "<USER_AGENT>" }
        },
        "identityMap": {
          "ECID": [ { "id": "<ECID>", "authenticatedState": "ambiguous", "primary": true } ]
        },
        "timestamp": "2025-09-08T12:00:00.000Z"
      },
      "data": {
        "__adobe": { "ajo": { "allowDuplicateDecisionItems": false } }
      }
    }
  ],
  "meta": {
    "state": {
      "domain": "my-web",
      "cookiesEnabled": true,
      "entries": [
        { "key": "kndctr_<ORG>_AdobeOrg_identity", "value": "<identity-cookie>" },
        { "key": "kndctr_<ORG>_AdobeOrg_cluster", "value": "<cluster-cookie>" }
      ]
    }
  }
}
NOTE
完全な Journey Optimizer 決定 Web SDK/Edge 参照について詳しくは、 コードベースのエクスペリエンス:実装での決定を参照してください。

決定 Edge 応答 decisioning-response

決定の応答には、懸念事項のタイプ(personalization:decisions(オファー)、locationHint:result、state:store(永続化する Cookie))別に整理された複数のハンドルが含まれます。

応答構造:

{
  "requestId": "<REQUEST_ID>",
  "handle": [
    {
      "type": "personalization:decisions",
      "eventIndex": 0,
      "payload": [
        {
          "id": "103ae599-e6d8-4631-baf3-51dd8c6ed4c1",
          "scope": "web://my-web/IP_NLI_HP_GET_LOAN_WIDGET",
          "scopeDetails": {
            "decisionProvider": "AJO",
            "correlationID": "<CORRELATION_ID>",
            "characteristics": {
              "eventToken": "<base64 message-level event token>",
              "subPropositions": "<base64-encoded array of decision items>"
            },
            "rank": 1,
            "activity": {
              "id": "<campaignId>#<actionId>",
              "priority": 0,
              "matchedSurfaces": ["web://my-web/IP_NLI_HP_GET_LOAN_WIDGET"]
            }
          },
          "items": [
            {
              "id": "36646bab-af1b-44c6-b632-bbfb9c357919",
              "schema": "https://ns.adobe.com/personalization/json-content-item",
              "data": { "content": "{ ...offer JSON... }" }
            }
          ]
        }
      ]
    },
    {
      "type": "locationHint:result",
      "payload": [
        { "scope": "EdgeNetwork", "hint": "ind1", "ttlSeconds": 1800 }
      ]
    },
    {
      "type": "state:store",
      "payload": [
        { "key": "kndctr_<ORG>_AdobeOrg_cluster", "value": "<cluster-cookie>", "maxAge": 1800 },
        { "key": "kndctr_<ORG>_AdobeOrg_identity", "value": "<identity-cookie>", "maxAge": 34128000 }
      ]
    }
  ]
}

主な応答フィールド:

  • handle[].type - ハンドルタイプ(personalization:decisions、locationHint:result、state:store)
  • payload[].id - 一意の提案インスタンス ID - 表示/操作イベント時にエコーバック
  • payload[].scope - 提案が解決されたサーフェス URI
  • payload[].scopeDetails.decisionProvider - エンジンが AJO であることを確認
  • payload[].scopeDetails.correlationID - 決定インスタンスを配信イベントにリンク
  • payload[].scopeDetails.rank/payload[].scopeDetails.activity - 提案のランクおよびキャンペーン/アクションメタデータ
  • payload[].scopeDetails.characteristics.eventToken - メッセージレベルのトラッキングトークン
  • payload[].scopeDetails.characteristics.subPropositions - Base64 エンコードされた​決定項目の配列。各項目には、項目ごとに独自の token が含まれます。 これらの項目ごとのトークンは、表示/操作イベントで propositionAction.tokens に渡されるものです
  • payload[].items[].schema/payload[].items[].data.content - レンダリングするコンテンツスキーマと実際のオファーコンテンツ(JSON/HTML)
  • state:store ペイロード - 後続のリクエストで永続化および転送する ID およびクラスター Cookie(サーバーサイド)

characteristics.subPropositions 文字列を base64 デコードすると、各項目に対応する token を含む、配信される項目の配列になります。

[
  {
    "id": "1ae75277-8832-4c23-bbbc-09f01cfe6c8b",
    "scope": "web://my-web/IP_NLI_HP_GET_LOAN_WIDGET",
    "scopeDetails": { "decisionProvider": "EXD", "correlationID": "<CORRELATION_ID>-0", "rank": 1 },
    "items": [
      { "id": "dps:<schema>:1be64ff83a612488", "name": "ExD_Personal Loan Offer", "score": 997.0, "token": "CLaefQnVLcLbCtzEXV3Jeg" },
      { "id": "dps:<schema>:1be6516838e1248c", "name": "ExD_Home Loan Offer",     "score": 995.0, "token": "ALlB5KV1B0e+CpHoahi7Ew" },
      { "id": "dps:<schema>:1be650da3cd06e98", "name": "ExD_Auto Loan Offer",     "score": 994.0, "token": "koJTRQcwFkR92AqbZ88ytQ" },
      { "id": "dps:<schema>:1be65612d5a1248d", "name": "ExD_Fallback Offer",      "itemSelection": { "selectionDetail": { "selectionType": "fallback" } }, "token": "GHo4ow7h6iCzBOhYR1+6jg" }
    ]
  }
]

実装パターン implementation-patterns

決定では、次の 3 つの実装アプローチをサポートしています。

クライアントサイド実装(Web SDK/Mobile SDK) client-side

Web SDK または Mobile SDK は、すべてのリクエストと cookie 管理を自動的に処理します。 SDK は、ID とクラスターの両方の Cookie を各リクエストに保存して転送します。

cookie 処理:​自動 - Web SDK は kndctr_<OrgId>_identity および kndctr_<OrgId>_cluster の Cookie を管理します。

サーバーサイド実装(Edge Network API) server-side

アプリケーションサーバーは、Edge Network に POST を直接実行し、cookie 転送を手動で管理する必要があります。 サーバーは、受信リクエストからブラウザーの Cookie を抽出し、meta.state.entries[] 経由で Edge Network に転送して、応答で Cookie を返します。

cookie 処理:​手動 - アプリサーバーは、ブラウザーのリクエストから Cookie を抽出し、リクエスト本文で Edge Network に転送し、応答に設定する必要があります。 ID の一貫性を確保するために、Cookie は meta.state.entries で明示的に転送する必要があります。

ハイブリッド実装 hybrid

サーバーサイドレンダリング(初期ページ読み込み)とクライアントサイド SDK(それ以降のインタラクション)を組み合わせます。 サーバーが Edge Network 経由で初期コンテンツをレンダリングし、それ以降のパーソナライゼーションリクエストについては Web SDK が引き継ぎます。

cookie 処理:​混在 - サーバーサイドでは Edge Network への手動の cookie 転送が必要ですが、クライアントサイドでは Web SDK によって自動的に処理されます。 一貫性のある ID 解決のために、サーバーサイドレンダリングからの ID トークンをクライアントサイド SDK で使用できるようにします。

イベントトラッキングとデータ収集 event-tracking

決定結果を適切に帰属させ、フリークエンシーキャップを有効にし、AI ベースのランキングの最適化を強化するには、決定イベントスキーマを使用してイベントトラッキングを実装する必要があります。

必須イベントフィールド event-fields

eventType と _experience.decisioning.propositionEventType の両方が必須です。 いずれかが欠落している場合、対応する表示/操作カウンターは増分されません。

  • eventType - イベントカテゴリを指定します。

    • decisioning.propositionDisplay - インプレッションイベント(ユーザーに表示されるオファー)
    • decisioning.propositionInteract - インタラクションイベント(ユーザーがオファーをクリックまたはエンゲージ)
  • _experience.decisioning.propositionEventType - イベントサブタイプをフラグ付けします。 1 に設定されたイベントタイプキーを、正確に 1 つ​含めます(各値は 1 または 0 です。同じオブジェクト内で複数のイベントタイプを 1 に設定しないでください)。

    • { "display": 1 } - インプレッションイベント
    • { "interact": 1 } - インタラクションイベント
    • display/interact/dismiss がすべて 0 であるか、eventType が decisioning.proposition<Display|Interact|Dismiss> 以外の値である場合、そのイベントは​ カスタムイベント ​として処理されます。
  • _experience.decisioning.propositionAction.tokens[] - 次のカウンターを増分する配信項目を特定する、項目ごとのトークン:

    • デコードされた subPropositions 配列から各項目の token をコピーします。scopeDetails.characteristics.eventToken はメッセージレベルの別のトークンなので、使用​ しない ​でください。
    • トークンは、受信したとおりに、変更せずに正確に渡します。
    • **操作イベント:**正確に 1 つ​のトークン(クリックされた項目)を指定します。
    • 表示イベント:​オプション - 特定の項目を増分するトークンを指定するか、tokens を​ 省略 ​して subPropositions 内の​ すべて ​の項目のカウンターを増分します。
  • _experience.decisioning.propositions[] - 応答から配信された提案(id、scope、完全 なscopeDetails を含む)をエコーバックします(これには、characteristics.subPropositions が含まれ、decisionProvider が必要です)。 明示的な items[] 配列を作成する必要はありません。

スキーマ要件 schema-requirements

移行前に、決定フィールドグループをイベントデータセットスキーマに関連付けます。

  1. Experience Platform で、イベントデータセットスキーマを開きます

  2. Experience Event - Proposition Details フィールドグループを追加します

  3. 次のフィールドがマッピングされていることを確認します。

    • _experience.decisioning.* フィールド
    • _experience.decisioning.propositionAction.tokens
    • _experience.decisioning.propositionEventType

トラッキングトークンの処理 tracking-token

トラッキングトークンは、次の要件に従って処理する必要があります。

  • 項目ごとのトークンでカウンターを推進 - propositionAction.tokens の値は、メッセージレベルの characteristics.eventToken ではなく、subPropositions から配信される各項目の token です。
  • 操作イベント - 正確に 1 つのトークン(クリックされた項目)を指定します。
  • 表示イベント - トークンはオプションです。subPropositions のすべての項目を増分する場合は省略するか、特定の項目のみを増分する特定のトークンを指定します。
  • トークンを変更しない - 受信した値を正確に渡します。エンコード、解析、変更しないでください。

決定イベントの例 event-examples

各例は、配信された提案(characteristics.subPropositions を持つ scopeDetails を含む)をエコーバックし、eventType と propositionEventType の両方を設定します。 subPropositions の項目に対してカウンターが増分されます。対象となる項目は、propositionAction.tokens によって選択されます。

表示イベント

表示イベントは、オファーがユーザーに表示された際に、決定に通知します。 表示されている項目のトークンを指定するか、tokens を省略して、subPropositions のすべての項目の表示カウンターを増分します。

{
  "header": {
    "imsOrgId": "YOUR_ORG_ID",
    "sandboxId": "sandbox-id",
    "sandboxName": "sandbox-name",
    "source": { "name": "ajo-inbound" }
  },
  "body": {
    "xdmEntity": {
      "identityMap": {
        "ECID": [ { "id": "ecid-123", "primary": true } ]
      },
      "eventType": "decisioning.propositionDisplay",
      "_experience": {
        "decisioning": {
          "propositionEventType": { "display": 1 },
          "propositionAction": {
            "id": "b96f842b-5dd9-4c55-9dae-647d96250028",
            "tokens": ["CLaefQnVLcLbCtzEXV3Jeg", "ALlB5KV1B0e+CpHoahi7Ew"]
          },
          "propositions": [
            {
              "id": "103ae599-e6d8-4631-baf3-51dd8c6ed4c1",
              "scope": "web://my-web/IP_NLI_HP_GET_LOAN_WIDGET",
              "scopeDetails": {
                "decisionProvider": "AJO",
                "characteristics": {
                  "eventToken": "<base64 eventToken from response>",
                  "subPropositions": "<base64 subPropositions from response>"
                }
              }
            }
          ]
        }
      }
    }
  }
}

操作(クリック)イベント

操作イベントは、ユーザーが表示されたオファーをクリックまたはエンゲージしたタイミングを追跡します。 クリックされた項目を特定する​ 正確に 1 つ ​のトークンを指定する​ 必要 ​があります。

{
  "header": {
    "imsOrgId": "YOUR_ORG_ID",
    "sandboxId": "sandbox-id",
    "sandboxName": "sandbox-name",
    "source": { "name": "ajo-inbound" }
  },
  "body": {
    "xdmEntity": {
      "identityMap": {
        "ECID": [ { "id": "ecid-123", "primary": true } ]
      },
      "eventType": "decisioning.propositionInteract",
      "_experience": {
        "decisioning": {
          "propositionEventType": { "interact": 1 },
          "propositionAction": {
            "id": "b96f842b-5dd9-4c55-9dae-647d96250028",
            "tokens": ["CLaefQnVLcLbCtzEXV3Jeg"]
          },
          "propositions": [
            {
              "id": "103ae599-e6d8-4631-baf3-51dd8c6ed4c1",
              "scope": "web://my-web/IP_NLI_HP_GET_LOAN_WIDGET",
              "scopeDetails": {
                "decisionProvider": "AJO",
                "characteristics": {
                  "eventToken": "<base64 eventToken from response>",
                  "subPropositions": "<base64 subPropositions from response>"
                }
              }
            }
          ]
        }
      }
    }
  }
}

カスタムイベント

カスタムイベントでは、顧客定義の eventType(decisioning.proposition<Display|Interact|Dismiss> 以外の任意の値)を使用し、propositionEventType では display/interact/dismiss のすべてを 0 に設定します(OTHER として分類されます)。 カスタムイベントは、subPropositions に対して表示イベント(マルチトークンフィルタリング)のようにデコードされ、設定された PQL 経由で評価されます。

{
  "header": {
    "imsOrgId": "YOUR_ORG_ID",
    "sandboxId": "sandbox-id",
    "sandboxName": "sandbox-name",
    "originalTimestamp": 1700000
  },
  "body": {
    "xdmEntity": {
      "identityMap": {
        "ECID": [ { "id": "ecid-123", "primary": true } ]
      },
      "eventType": "add-to-cart",
      "_experience": {
        "decisioning": {
          "propositionEventType": { "display": 0, "interact": 0, "dismiss": 0 },
          "propositionAction": {
            "id": "b96f842b-5dd9-4c55-9dae-647d96250028",
            "tokens": ["CLaefQnVLcLbCtzEXV3Jeg"]
          },
          "propositions": [
            {
              "id": "103ae599-e6d8-4631-baf3-51dd8c6ed4c1",
              "scope": "web://my-web/IP_NLI_HP_GET_LOAN_WIDGET",
              "scopeDetails": {
                "decisionProvider": "AJO",
                "characteristics": {
                  "eventToken": "<base64 eventToken from response>",
                  "subPropositions": "<base64 subPropositions from response>"
                }
              }
            }
          ]
        }
      }
    }
  }
}

これらのイベントにより、決定でのフリークエンシーキャップ、標準のレポート、AI 駆動型のランキング最適化が可能になります。 Web SDK を使用して提案イベントを送信する方法について詳しくは、コードベースのエクスペリエンス:実装での決定を参照してください。

エンドツーエンドの移行プロセス migration-process

  1. 前提条件を検証 - 移行を開始する前に、ターゲットサンドボックスが準備され、すべての前提条件の依存関係(プロファイル属性、セグメント ID、ID マッピング)が特定され、準備が整っていることを確認します。

  2. Migration API を呼び出し - 準備した前提条件とマッピングを使用して Migration API を実行し、意思決定管理オブジェクトを決定に移行します。

  3. ドラフトの決定エンティティの生成 - ツールが、エンティティマッピングごとに、キャンペーン、決定ポリシー、選択戦略、オファー項目などをドラフト状態で作成します。 生成されたすべての決定オブジェクトをターゲットサンドボックスで確認します。 命名、エンティティタイプ、参照が正しいことを検証します。 顧客向けの機能はまだ公開されていませんが、意思決定管理では引き続きライブトラフィックを配信しています。

  4. クライアントとサーバーのコードを更新 - 新しい決定リクエスト/応答形式を使用するために必要なコード変更を実装し、必須フィールドを含むイベントトラッキングを実装します。

  5. アクティブ化とカットオーバー - 決定オブジェクト(戦略、ポリシー、キャンペーン、サーフェス)をアクティブ化し、独自のタイムラインで意思決定管理からトラフィックを移行します。

recommendation-more-help
journey-optimizer-help