Platform Web SDK での A4T データのクライアントサイドログ

Last update: Tue Jul 23 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

トピック：

作成対象：

開発者

概要 overview

Adobe Experience Platform Web SDK を使用すると、web アプリケーションのクライアント側で Adobe Analytics for Target （A4T）データを収集できます。

クライアントサイドログとは、関連する Target データがクライアントサイドで返され、ユーザーがデータを収集して Analytics と共有できることを意味します。 Data Insertion API を使用して手動で Analytics にデータを送信する場合は、このオプションを有効にしてください。

NOTE

method.js を使用してこれを実行するAppMeasurementは、現在開発中で、近い将来に利用可能になる予定です。

このドキュメントでは、Web SDK のクライアントサイド A4T ログの設定手順を説明し、一般的なユースケースの実装例を示します。

前提条件 prerequisites

このチュートリアルは、パーソナライゼーションのために Web SDK を使用することに関連する基本的な概念とプロセスについて、十分に理解していることを前提としています。概要については、次のドキュメントを参照してください。

Analytics クライアントサイドログの設定 set-up-client-side-logging

次のサブセクションでは、Web SDK 実装に対して Analytics のクライアントサイドログを有効にする方法の概要を説明します。

Analytics クライアントサイドログを有効にする enable-analytics-client-side-logging

実装で Analytics クライアントサイドログが有効であると見なすには、データストリームでAdobe Analytics設定を無効にする必要があります。

Analytics データストリーム設定が無効

SDKA4T データを取得して、Analytics に送信します a4t-to-analytics

このレポート方法が正しく機能するには、Analytics ヒットの sendEvent コマンドから取得した A4T 関連データを送信する必要があります。

Target Edgeは、提案レスポンスを計算する際、Analytics のクライアントサイドログが有効になっているか（つまり、データストリームで Analytics が無効になっているか）を確認します。クライアントサイドログが有効になっている場合、システムは応答の各提案に Analytics トークンを追加します。

フローは次のようになります。

クライアントサイドログフロー

次に、Analytics クライアントサイドログが有効になっている場合の interact 応答の例を示します。 Analytics レポートを使用するアクティビティに関する提案の場合は、scopeDetails.characteristics.analyticsToken のプロパティが表示されます。

{
  "requestId": "1234",
  "handle": [
    {
      "payload": [
        {
          "id": "AT:eyJhY3Rpdml0eUlkIjoiNDM0Njg5IiwiZXhwZXJpZW5jZUlkIjoiMCJ9",
          "scope": "a4t-test",
          "scopeDetails": {
            "decisionProvider": "TGT",
            "activity": {
              "id": "434689"
            },
            "experience": {
              "id": "0"
            },
            "strategies": [
              {
                "algorithmID": "0",
                "trafficType": "0"
              }
            ],
            "characteristics": {
              "eventToken": "2lTS5KA6gj4JuSjOdhqUhGqipfsIHvVzTQxHolz2IpTMromRrB5ztP5VMxjHbs7c6qPG9UF4rvQTJZniWgqbOw==",
              "analyticsToken": "434689:0:0|2,434689:0:0|1"
            }
          },
          "items": [
            {
              "id": "1184844",
              "schema": "https://ns.adobe.com/personalization/html-content-item",
              "meta": {
                "geo.state": "bucuresti",
                "activity.id": "434689",
                "experience.id": "0",
                "activity.name": "a4t test form based activity",
                "offer.id": "1184844",
                "profile.tntId": "04608610399599289452943468926942466370-pybgfJ"
              },
              "data": {
                "id": "1184844",
                "format": "text/html",
                "content": "<div> analytics impressions </div>"
              }
            }
          ]
        },
        {
          "id": "AT:eyJhY3Rpdml0eUlkIjoiNDM0Njg5IiwiZXhwZXJpZW5jZUlkIjoiMCJ9",
          "scope": "a4t-test",
          "scopeDetails": {
            "decisionProvider": "TGT",
            "activity": {
              "id": "434689"
            },
            "characteristics": {
              "eventToken": "E0gb6q1+WyFW3FMbbQJmrg==",
              "analyticsToken": "434689:0:0|32767"
            }
          },
          "items": [
            {
              "id": "434689",
              "schema": "https://ns.adobe.com/personalization/measurement",
              "data": {
                "type": "click",
                "format": "application/vnd.adobe.target.metric"
              }
            }
          ]
        }
      ],
      "type": "personalization:decisions",
      "eventIndex": 0
    }
  ]
}

フォームベースの Experience Composer アクティビティの提案では、コンテンツとクリック指標項目の両方を同じ提案の下に含めることができます。したがって、scopeDetails.characteristics.analyticsToken のプロパティでコンテンツ表示用の分析トークンを 1 つだけ用意するのではなく、scopeDetails.characteristics.analyticsDisplayToken プロパティと scopeDetails.characteristics.analyticsClickToken プロパティで、表示用とクリック用分析トークンの両方を指定することができます。

{
  "requestId": "1234",
  "handle": [
    {
      "payload": [
        {
          "id": "AT:eyJhY3Rpdml0eUlkIjoiNDM0Njg5IiwiZXhwZXJpZW5jZUlkIjoiMCJ9",
          "scope": "a4t-test",
          "scopeDetails": {
            "decisionProvider": "TGT",
            "activity": {
              "id": "434689"
            },
            "experience": {
              "id": "0"
            },
            "strategies": [
              {
                "algorithmID": "0",
                "trafficType": "0"
              }
            ],
            "characteristics": {
               "displayToken": "2lTS5KA6gj4JuSjOdhqUhGqipfsIHvVzTQxHolz2IpTMromRrB5ztP5VMxjHbs7c6qPG9UF4rvQTJZniWgqbOw==",
               "clickToken": "E0gb6q1+WyFW3FMbbQJmrg==",
               "analyticsDisplayToken": "434689:0:0|2,434689:0:0|1",
               "analyticsClickToken": "434689:0:0|32767"
            }
          },
          "items": [
            {
              "id": "1184844",
              "schema": "https://ns.adobe.com/personalization/html-content-item",
              "meta": {
                "geo.state": "bucuresti",
                "activity.id": "434689",
                "experience.id": "0",
                "activity.name": "a4t test form based activity",
                "offer.id": "1184844",
                "profile.tntId": "04608610399599289452943468926942466370-pybgfJ"
              },
              "data": {
                "id": "1184844",
                "format": "text/html",
                "content": "<div> analytics impressions </div>"
              }
            },
            {
              "id": "434689",
              "schema": "https://ns.adobe.com/personalization/measurement",
              "data": {
                "type": "click",
                "format": "application/vnd.adobe.target.metric"
              }
            }
          ]
        }
      ],
      "type": "personalization:decisions",
      "eventIndex": 0
    }
  ]
}

scopeDetails.characteristics.analyticsToken のすべての値と scopeDetails.characteristics.analyticsDisplayToken （表示されたコンテンツの場合）および scopeDetails.characteristics.analyticsClickToken （クリック指標の場合）は、A4T ペイロードで、Data Insertion API 呼び出しでタグとして収集し tnta 含める必要があります。

IMPORTANT

analyticsToken、analyticsDisplayToken、analyticsClickToken の各プロパティには、複数のトークンを含め、1 つのコンマで区切られた文字列として連結できます。

次の節に示す実装例では、複数の Analytics トークンが繰り返し収集されています。 Analytics トークンの配列を連結するには、次のような関数を使用します。

code language-javascript

code language-javascript
`var concatenateAnalyticsPayloads = function concatenateAnalyticsPayloads(analyticsPayloads) { if (analyticsPayloads.size > 1) { return [].concat(analyticsPayloads).join(','); } return [].concat(analyticsPayloads).join(); };`

var concatenateAnalyticsPayloads = function concatenateAnalyticsPayloads(analyticsPayloads) {
   if (analyticsPayloads.size > 1) {
       return [].concat(analyticsPayloads).join(',');
   }
   return [].concat(analyticsPayloads).join();
};

実装例 implementation-examples

次のサブセクションでは、一般的なユースケースに対する Analytics クライアントサイドログの実装方法について説明します。

フォームベースの Experience Composer アクティビティ form-based-composer

Web SDK を使用して、Adobe Target フォームベースの Experience Composer アクティビティからの提案の実行を制御できます。

特定の決定範囲の提案をリクエストすると、返される提案には、適切な Analytics トークンが含まれます。ベストプラクティスは、Platform Web SDK sendEvent コマンドを連結し、返された提案を繰り返し処理して、Analytics トークンを同時に収集しながら実行することです。

次のように、フォームベースの Experience Composer アクティビティ範囲に対して sendEvent コマンドをトリガーできます。

alloy("sendEvent", {
    "decisionScopes": ["a4t-test"],
    "xdm": {
      "web": {
        "webPageDetails": {
          "name": "Home Page"
        }
      }
    }
  }
).then(function(results) {
  for (var i = 0; i < results.propositions.length; i++) {
    //Execute the propositions and collect the Analytics payload
  }
});

ここから、提案を実行し、最終的に Analytics に送信されるペイロードを構築するコードを実装する必要があります。次に、results.propositions に含まれる可能性のある例を示します。

[
  {
    "id": "AT:eyJhY3Rpdml0eUlkIjoiNDM0Njg5IiwiZXhwZXJpZW5jZUlkIjoiMCJ9",
    "scope": "a4t-test",
    "scopeDetails": {
      "decisionProvider": "TGT",
      "activity": {
        "id": "434689"
      },
      "experience": {
        "id": "0"
      },
      "strategies": [
        {
          "algorithmID": "0",
          "trafficType": "0"
        }
      ],
      "characteristics": {
        "eventToken": "2lTS5KA6gj4JuSjOdhqUhGqipfsIHvVzTQxHolz2IpTMromRrB5ztP5VMxjHbs7c6qPG9UF4rvQTJZniWgqbOw==",
        "analyticsToken": "434689:0:0|2,434689:0:0|1"
      }
    },
    "items": [
      {
        "id": "1184844",
        "schema": "https://ns.adobe.com/personalization/html-content-item",
        "meta": {
          "geo.state": "bucuresti",
          "activity.id": "434689",
          "experience.id": "0",
          "activity.name": "a4t test form based activity",
          "offer.id": "1184844",
          "profile.tntId": "04608610399599289452943468926942466370-pybgfJ"
        },
        "data": {
          "id": "1184844",
          "format": "text/html",
          "content": "<div> analytics impressions </div>"
        }
      }
    ]
  },
  {
    "id": "AT:eyJhY3Rpdml0eUlkIjoiNDM0Njg5IiwiZXhwZXJpZW5jZUlkIjoiMCJ9",
    "scope": "a4t-test",
    "scopeDetails": {
      "decisionProvider": "TGT",
      "activity": {
        "id": "434689"
      },
      "characteristics": {
        "eventToken": "E0gb6q1+WyFW3FMbbQJmrg==",
        "analyticsToken": "434689:0:0|32767"
      }
    },
    "items": [
      {
        "id": "434689",
        "schema": "https://ns.adobe.com/personalization/measurement",
        "data": {
          "type": "click",
          "format": "application/vnd.adobe.target.metric"
        }
      }
    ]
  },
  {
    "id": "AT:eyJhY3Rpdml0eUlkIjoiNDM0Njg5IiwiZXhwZXJpZW5jZUlkIjoiMCJ9",
    "scope": "a4t-test",
    "scopeDetails": {
      "decisionProvider": "TGT",
      "activity": {
        "id": "434688"
      },
      "experience": {
        "id": "0"
      },
      "strategies": [
        {
          "algorithmID": "0",
          "trafficType": "0"
        }
      ],
      "characteristics": {
          "displayToken": "91TS5KA6gj4JuSjOdhqUhGqipfsIHvVzTQxHolz2IpTMromRrB5ztP5VMxjHbs7c6qPG9UF4rvQTJZniWgqgEt==",
          "clickToken": "Tagb6q1+WyFW3FMbbQJrtg==",
          "analyticsDisplayTokens": "434688:0:0|2,434688:0:0|1",
          "analyticsClickTokens": "434688:0:0|32767"
        }
      }
    },
    "items": [
      {
        "id": "1184845",
        "schema": "https://ns.adobe.com/personalization/html-content-item",
        "meta": {
          "geo.state": "bucuresti",
          "activity.id": "434688",
          "experience.id": "0",
          "activity.name": "a4t test form based activity 1",
          "offer.id": "1184845"
        },
        "data": {
          "id": "1184845",
          "format": "text/html",
          "content": "<div> analytics impressions 1</div>"
        }
      },
      {
        "id": "434688",
        "schema": "https://ns.adobe.com/personalization/measurement",
        "data": {
          "type": "click",
          "format": "application/vnd.adobe.target.metric"
        }
      }
    ]
  }
]

コンテンツ項目を含む提案から Analytics トークンを抽出するには、次のような関数を実装します。

function getDisplayAnalyticsPayload(proposition) {
  if (!proposition || !proposition.scopeDetails || !proposition.scopeDetails.characteristics) {
    return;
  }
  var characteristics = proposition.scopeDetails.characteristics;
  if (characteristics.analyticsDisplayToken) {
    return characteristics.analyticsDisplayToken;
  }
  return characteristics.analyticsToken;
}

提案には、問題の項目の schema プロパティで示されるように、様々なタイプの項目を含めることができます。フォームベースの Experience Composer アクティビティでは、次の 4 つの提案項目スキーマがサポートされます。

var HTML_SCHEMA = "https://ns.adobe.com/personalization/html-content-item";
var MEASUREMENT_SCHEMA = "https://ns.adobe.com/personalization/measurement";
var JSON_SCHEMA = "https://ns.adobe.com/personalization/json-content-item";
var REDIRECT_SCHEMA = "https://ns.adobe.com/personalization/redirect-item";

HTML_SCHEMA と JSON_SCHEMA はオファーのタイプを反映するスキーマで、MEASUREMENT_SCHEMA は DOM 要素に添付する必要がある指標を反映します。

クリック指標に対する Analytics ペイロードは、訪問者が以前に表示されたコンテンツを実際にクリックした瞬間に、コンテンツ項目とは別に収集して Analytics に送信する必要があります。

この場合、クリック指標の A4T ペイロードを取得するための次のヘルパー関数が便利です。

function getClickAnalyticsPayload(proposition) {
  if (!proposition || !proposition.scopeDetails || !proposition.scopeDetails.characteristics) {
    return;
  }
  var characteristics = proposition.scopeDetails.characteristics;
  if (characteristics.analyticsClickToken) {
    return characteristics.analyticsClickToken;
  }
  return characteristics.analyticsToken;
}

実装の概要 implementation-summary

要約すると、Platform Web SDK でフォームベースの Experience Composer アクティビティを適用する場合は、次の手順を実行する必要があります。

フォームベースの Experience Composer アクティビティオファーを取得するイベントを送信する。
ページにコンテンツの変更を適用する。
decisioning.propositionDisplay 通知イベントの送信
SDK 応答から Analytics 表示トークンを収集し、Analytics ヒットのペイロードを作成します。
Data Insertion API を使用してペイロードを Analytics に送信する
配信された提案にクリック指標がある場合は、クリックが実行されたときに decisioning.propositionInteract の通知イベントが送信されるようにクリックリスナーを設定する必要があります。 onBeforeEventSend ハンドラーは、イベントをインターセプトすると次のアクションが発生するように設定 decisioning.propositionInteract る必要があります。
1. xdm._experience.decisioning.propositions からのクリック分析トークンの収集
2. Data Insertion API を介して、収集された Analytics ペイロードでクリック Analytics ヒットを送信する

alloy("sendEvent", {
    "decisionScopes": ["a4t-test"],
    "xdm": {
      "web": {
        "webPageDetails": {
          "name": "Home Page"
        }
      }
    }
  }
).then(function(results) {
  var analyticsPayload = new Set();
  results.propositions.forEach(function (proposition) {
    proposition.items.forEach(function (item) {
      if (item.schema === HTML_SCHEMA) {
        // 1. Apply offer
        // 2. Collect executed propositions and send the decisioning.propositionDisplay notification event
        // 3. Collect the display Analytics tokens
      }
      if (item.schema === MEASUREMENT_SCHEMA) {
        // Setup click listener, so that when clicked:
        // 1. Collect clicked propositions and send the decisioning.propositionInteract notification event
        // Note: onBeforeEventSend handler should be configured, so that when intercepting decisioning.propositionInteract events:
        //   1. Collect the click Analytics tokens from xdm._experience.decisioning.propositions
        //   2. Send the click Analytics hit with the collected Analytics payload via Data Insertion API
      }
    });
  });
  // Send the page view Analytics hit with the collected display Analytics payload via Data Insertion API
});

Visual Experience Composer アクティビティ visual-experience-composer-acitivties

Web SDK を使用すると、Visual Experience Composer （VEC）を使用して作成されたオファーを処理できます。

NOTE

このユースケースの実装手順は、フォームベースの Experience Composer アクティビティの手順と非常によく似ています。詳しくは、前の節を参照してください。

自動レンダリングが有効になっている場合は、ページで実行された提案から Analytics トークンを収集できます。ベストプラクティスは、Platform Web SDK sendEvent コマンドを連結し、返された提案を繰り返し処理して、Web SDK がレンダリングしようとしたものをフィルタリングすることです。

例

alloy("sendEvent", {
    "renderDecisions": true,
    "xdm": {
      "web": {
        "webPageDetails": {
          "name": "Home Page"
        }
      }
    }
  }
).then(function (results) {
  var analyticsPayloads = new Set();

  for (var i = 0; i < results.propositions.length; i++) {

    var proposition = propositions[i];
    var renderAttempted = proposition.renderAttempted;

    if (renderAttempted === true) {
      var analyticsPayload = getDisplayAnalyticsPayload(proposition);

      if (analyticsPayload !== undefined) {
        analyticsPayloads.add(analyticsPayload);
      }
    }
  }
  var analyticsPayloadsToken = concatenateAnalyticsPayloads(analyticsPayloads);
  // Send the page view Analytics hit with collected Analytics payload via Data Insertion API
});

`onBeforeEventSend` を使用したページ指標の処理 using-onbeforeeventsend

Adobe Target アクティビティを使用すると、DOM に手動で添付するか、DOM （VEC が作成したアクティビティ）に自動的に添付するかして、ページ上で異なる指標を設定できます。どちらのタイプも、web ページ上でのエンドユーザーのインタラクションが遅延します。

これに対処するために、ベストプラクティスは、onBeforeEventSend Adobe Experience Platform Web SDK フックを使用して Analytics ペイロードを収集することです。 onBeforeEventSend フックは、configure コマンドを使用して設定する必要があり、データストリームを通じて送信されるすべてのイベントに反映されます。

次に、Analytics のヒットをトリガーにす onBeforeEventSent ように設定する方法の例を示します。

alloy("configure", {
  datastreamId: "datastream configuration ID",
  orgId: "adobe ORG ID",
  onBeforeEventSend: function(options) {
    const xdm = options.xdm;
    const eventType = xdm.eventType;
    if (eventType === "decisioning.propositionInteract") {
      const analyticsPayloads = new Set();
      const propositions = xdm._experience.decisioning.propositions;

      for (var i = 0; i < propositions.length; i++) {
        var proposition = propositions[i];
        analyticsPayloads.add(getClickAnalyticsPayload(proposition));
      }
      // Trigger the Analytics hit
    }
  }
});

次の手順 next-steps

このガイドでは、Web SDK の A4T データのクライアントサイドログについて説明しました。サーバー上の A4T データの処理方法について詳しくは、Edge Networkサイドログに関するガイドを参照してください。

recommendation-more-help

ad108910-6329-42f1-aa1d-5920a2b13636