Experience Platform Web SDK中A4T資料的使用者端記錄

Last update: Tue Aug 12 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

主題：

建立對象：

開發人員

Adobe Experience Platform Web SDK可讓您在網頁應用程式的使用者端上收集Target (A4T)的Adobe Analytics資料。

使用者端記錄表示使用者端會傳回相關的Target資料，讓您收集資料並與Analytics共用。如果您打算使用資料插入API手動將資料傳送至Analytics，則應啟用此選項。

NOTE

使用AppMeasurement.js執行此工作的方法目前正在開發中，將於不久的將來提供。

本文介紹為Platform Web SDK設定使用者端A4T記錄的步驟，並提供常見使用案例的實施範例。

先決條件 prerequisites

本教學課程假設您熟悉有關使用Platform Web SDK進行個人化目的的基本概念和程式。如果您需要簡介，請檢閱下列檔案：

設定Analytics使用者端記錄 set-up-client-side-logging

下列子節概述如何為您的Analytics實作啟用Platform Web SDK使用者端記錄。

啟用Analytics使用者端記錄 enable-analytics-client-side-logging

若要考慮為您的實作啟用Analytics使用者端記錄，您必須停用Adobe Analytics資料流中的設定。

已停用Analytics資料流設定

從SDK擷取A4T資料並將其傳送到Analytics a4t-to-analytics

為了讓此報告方法正常運作，您必須傳送從A4T點選中的sendEvent命令擷取的Analytics相關資料。

當Target Edge計算主張回應時，它會檢查是否已啟用Analytics使用者端記錄（例如，在您的資料流中是否已停用Analytics）。如果啟用使用者端記錄，則系統會在回應中為每個主張新增Analytics權杖。

流量看起來類似這樣：

使用者端記錄流程

下列是啟用interact使用者端記錄時Analytics回應的範例。如果主張是針對具有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
    }
  ]
}

Form-based Experience Composer活動的主張可以同時包含相同主張下的內容和點按量度專案。因此，不是在scopeDetails.characteristics.analyticsToken屬性中顯示內容的單一分析權杖，這些屬性可以相應地在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裝載，並包含在tnta資料插入API呼叫中的標籤。

IMPORTANT

analyticsToken、analyticsDisplayToken、analyticsClickToken屬性可包含多個權杖，以單一逗號分隔的字串串串連。

在下節提供的實作範例中，正在反複收集多個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使用者端記錄。

Form-Based Experience Composer個活動 form-based-composer

您可以使用Platform Web SDK控制來自Adobe Target表單式體驗撰寫器活動的建議執行。

當您請求特定決定範圍的建議時，傳回的建議包含其適當的Analytics權杖。最佳實務是鏈結Experience Platform Web SDK sendEvent命令並重複處理傳回的主張，以便在同時收集Analytics權杖時執行這些建議。

您可以為sendEvent活動範圍觸發Form-Based Experience Composer命令，如下所示：

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屬性所指示。 Form-Based Experience Composer活動支援四個主張專案結構描述：

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

總而言之，使用Form-Based Experience Composer套用Experience Platform Web SDK活動時，必須執行下列步驟：

傳送擷取Form-Based Experience Composer活動選件的事件；
將內容變更套用至頁面；
傳送decisioning.propositionDisplay通知事件；
從SDK回應中收集Analytics顯示權杖，並建構點選Analytics的裝載；
使用Analytics資料插入API將裝載傳送至；
若已傳遞的建議中有任何點選量度，則應設定點選接聽程式，以便執行點選時傳送decisioning.propositionInteract通知事件。應設定onBeforeEventSend處理常式，以便在攔截decisioning.propositionInteract事件時會發生下列動作：
1. 正在從Analytics收集點選xdm._experience.decisioning.propositions權杖
2. 透過Analytics資料插入APIAnalytics，以收集的裝載傳送點選點選；

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 (VEC)活動 visual-experience-composer-acitivties

Platform Web SDK可讓您處理使用視覺化體驗撰寫器(VEC)編寫的選件。

NOTE

實作此使用案例的步驟與表單式體驗撰寫器活動的步驟非常類似。如需詳細資訊，請參閱上一節。

啟用自動轉譯時，您可以從頁面上執行的主張中收集Analytics權杖。最佳實務是鏈結Experience 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編寫的活動）。這兩種型別都是網頁上延遲的一般使用者互動。

若要解決此問題，最佳實務是使用Analytics onBeforeEventSend鉤點收集Adobe Experience Platform Web SDK裝載。 onBeforeEventSend連結應使用configure命令設定，並反映在透過資料流傳送的所有事件中。

以下是如何設定onBeforeEventSent以觸發Analytics點選的範例：

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

本指南涵蓋Platform Web SDK中A4T資料的使用者端記錄。如需如何在Edge Network上處理A4T資料的詳細資訊，請參閱伺服器端記錄的指南。

recommendation-more-help

6906415f-169c-422b-89d3-7118e147c4e3