註冊歸因源

基本方法

歸因源的形式是您想要衡量其互動的內容中的連結、影像或指令碼（例如，它們可能是您想要衡量轉換的廣告）。當發生特定的使用者互動時，這些會使瀏覽器將源資料儲存在私有的本地快取中（僅瀏覽器可訪問）。不同的歸因源型別以不同的方式註冊並表示互動 — 它們被區分為：

• 導航源：當發生導航時，例如使用者點選連結或使用鍵盤啟用連結，或者由於 Window.open() 呼叫而發生導航時，瀏覽器會儲存源資料。有關示例，請參閱基於導航的歸因源。
• 事件源：當事件觸發時，瀏覽器會儲存源資料。有關示例，請參閱基於事件的歸因源。

在這兩種情況下，註冊源以及檢索和儲存源資料在幕後發生的過程是相同的：

1. 當用戶與歸因源互動時，它會在向衡量互動的伺服器（通常是廣告商的伺服器）發出的請求中傳送一個 Attribution-Reporting-Eligible 頭，這表明該響應有資格註冊源。例如：

   http

   Attribution-Reporting-Eligible: navigation-source
   

2. 當伺服器收到包含 Attribution-Reporting-Eligible 頭的請求時，它可以在響應中包含一個 Attribution-Reporting-Register-Source 頭以完成源註冊。其值是一個 JSON 字串，提供瀏覽器應儲存的有關發生互動的歸因源的資訊。此頭中包含的資訊還決定了瀏覽器將生成哪種型別的報告：

   • 以下示例將導致在將觸發器與源匹配時生成事件級報告：

     js

     res.set(
       "Attribution-Reporting-Register-Source",
       JSON.stringify({
         source_event_id: "412444888111012",
         destination: "https://advertiser.example",
         trigger_data: [0, 1, 2, 3, 4],
         trigger_data_matching: "exact",
         expiry: "604800",
         priority: "100",
         debug_key: "122939999",
         event_report_window: "86400",
       }),
     );
     

     在此上下文中，唯一必填的欄位是 destination，它指定了預計發生觸發器的 1-3 個站點。這些用於在與觸發器互動時將歸因觸發器與源匹配。上面指定的其他欄位執行以下操作：

     • "source_event_id": 一個字串，表示歸因源的 ID，當與歸因源互動時，可用於將其對映到其他資訊，或在報告端點聚合資訊（有關端點資訊，請參閱生成報告 > 基本過程）。
     • "trigger_data": 一個 32 位無符號整數陣列，表示描述可能與此源匹配的不同觸發事件的資料。例如，“使用者將商品新增到購物車”或“使用者訂閱郵件列表”可能是觸發器站點發生的行為，它們可能與此源匹配並指示廣告商試圖衡量的某種轉換。這些必須與觸發器中指定的 "trigger_data" 匹配，才能進行事件級歸因。

       注意：用於表示每個事件的值以及陣列中元素的數量完全是任意的，由您作為開發者定義。陣列可能包含未使用的值，但必須在陣列中存在值，以便瀏覽器在註冊觸發器時將其歸因於來源。

     • "trigger_data_matching": 一個字串，指定如何將觸發器的 "trigger_data" 與源的 "trigger_data" 匹配。"exact" 是您幾乎總是會使用的值，它匹配精確值。
     • "expiry": 一個字串，表示歸因源的過期時間（以秒為單位），在此之後它將不再活躍（即，後續觸發器將無法歸因於此源）。
     • "priority": 一個字串，表示歸因源的優先順序值。有關更多資訊，請參閱報告優先順序和限制。
     • "debug_key": 一個以 10 為基數的 64 位無符號整數，表示除錯金鑰。如果您想在關聯的歸因報告旁邊生成除錯報告，請設定此項。
     • "event_report_window": 一個字串，表示一個時間（以秒為單位），在此之後，後續觸發器將不再歸因於此源，以用於生成事件級報告。

     有關此頭中所有可用欄位的詳細說明，請參閱 Attribution-Reporting-Register-Source。

   • 要使瀏覽器在觸發器與源匹配時生成摘要報告，您需要除了生成事件級報告所需的欄位外，**額外**包含一些欄位。

     js

     res.set(
       "Attribution-Reporting-Register-Source",
       JSON.stringify({
         source_event_id: "412444888111012",
         destination: "https://advertiser.example",
         trigger_data: [0, 1, 2, 3, 4],
         trigger_data_matching: "exact",
         expiry: "604800",
         priority: "100",
         debug_key: "122939999",
         event_report_window: "86400",
     
         aggregation_keys: {
           campaignCounts: "0x159",
           geoValue: "0x5",
         },
         aggregatable_report_window: "86400",
       }),
     );
     

     此示例中的附加欄位是：

     • "aggregation_keys": 一個物件，包含使用者提供的金鑰，表示要聚合報告值的不同資料點。
     • "aggregatable_report_window": 一個字串，表示觸發資料不再包含在生成的聚合報告中的時間（以秒為單位）。

     同樣，有關此頭中所有可用欄位的詳細說明，請參閱 Attribution-Reporting-Register-Source。

3. 成功註冊源後，瀏覽器會將其提供的源資料儲存在其私有本地快取中。

基於導航的歸因源

導航源對於衡量與連結的互動非常有用——例如，使用者可能會在釋出商頁面上看到廣告，然後點選它導航到廣告商頁面，在那裡有望發生轉換。

可以註冊幾種不同型別的基於導航的歸因源（例如，點選廣告）——基於 HTML 的（使用 attributionsrc 屬性）和基於 Window.open() 呼叫的（使用 attributionsrc 視窗功能）。

基於 HTML 的導航源

要註冊基於導航的歸因源，您可以將 attributionsrc 屬性新增到相應的 <a> 元素中，該屬性指定註冊請求將傳送到何處。

如果將屬性值留空，註冊請求將傳送到連結到的位置。也可以在值中指定一個或多個附加 URL 以傳送註冊請求；有關詳細資訊，請參閱在 attributionsrc 中指定 URL。

attributionsrc 可以宣告性地新增：

<a href="https://shop.example" attributionsrc target="_blank">
  Click to visit our shop
</a>

或透過 HTMLAnchorElement.attributionSrc 屬性新增：

const aElem = document.querySelector("a");
aElem.attributionSrc = "";

在這種情況下，當用戶點選連結並且瀏覽器收到響應時，交互發生，導致瀏覽器儲存與基於導航的歸因源關聯的源資料（如 Attribution-Reporting-Register-Source 響應頭中提供）。

基於 Window.open() 的導航源

您還可以將 attributionsrc 功能關鍵字新增到 Window.open() 呼叫的 features 屬性中。在此示例中，我們將其作為 click 事件觸發的響應執行：

elem.addEventListener("click", () => {
  window.open("https://shop.example", "_blank", "attributionsrc");
});

在這種情況下，當呼叫 Window.open() 並且瀏覽器收到響應時，交互發生，瀏覽器儲存源資料。

基於事件的歸因源

基於事件的歸因源使瀏覽器在某種事件觸發時儲存源資料，例如 <img> 或 <script> 元素（它們像我們上面看到的 <a> 元素一樣使用 attributionsrc 屬性）的 load 事件，或者您在 JavaScript 中設定的自定義事件。

基於 HTML 的事件源

基於 HTML 的事件源可用於衡量釋出商頁面首次載入時的互動——或者更準確地說，當 <img> 或 <script> 載入時。要透過 HTML 註冊基於事件的歸因源，您可以將 attributionsrc 屬性新增到相應的元素——<img> 或 <script>。

如果將屬性值留空，註冊請求將傳送到所請求資源所在的伺服器。也可以在值中指定一個或多個附加 URL 以傳送註冊請求；有關詳細資訊，請參閱在 attributionsrc 中指定 URL。

我們來看一個 <img> 元素示例：

<img src="advertising-image.png" attributionsrc />

您也可以透過 HTMLImageElement.attributionSrc 屬性實現這一點：

const imgElem = document.querySelector("img");
imgElem.attributionSrc = "";

當瀏覽器收到包含影像檔案的響應（即，當 load 事件發生時）時，瀏覽器會儲存歸因源資料。請記住，使用者不一定能夠完全感知影像——它可能是一個 1x1 的透明跟蹤畫素，僅用於歸因報告。

一個 <script> 示例可能如下所示：

<script src="advertising-script.js" attributionsrc></script>

或透過 HTMLScriptElement.attributionSrc 屬性：

const scriptElem = document.querySelector("script");
scriptElem.attributionSrc = "";

在這種情況下，當瀏覽器收到包含指令碼的響應時，交互發生，瀏覽器儲存源資料。

基於 JavaScript 的事件源

基於指令碼的歸因源比基於 HTML 的歸因源更通用。您可以設定指令碼以根據適合您應用程式的任何請求發起一個有資格註冊歸因源的請求。這是一種靈活的方法，當您想要響應自定義互動（例如，點選自定義元素或提交表單）儲存源資料時非常有用。

要設定基於指令碼的歸因源，您可以選擇：

• 傳送包含 attributionReporting 選項的 fetch() 請求

  js

  const attributionReporting = {
    eventSourceEligible: true,
    triggerEligible: false,
  };
  
  // Optionally set keepalive to ensure the request outlives the page
  function triggerSourceInteraction() {
    fetch("https://shop.example/endpoint", {
      keepalive: true,
      attributionReporting,
    });
  }
  
  // Associate the interaction trigger with whatever
  // event makes sense for your code (does not have to be a
  // DOM event/user interaction)
  elem.addEventListener("click", triggerSourceInteraction);
  

• 傳送 XMLHttpRequest，並在請求物件上呼叫 setAttributionReporting()

  js

  const attributionReporting = {
    eventSourceEligible: true,
    triggerEligible: false,
  };
  
  function triggerSourceInteraction() {
    const req = new XMLHttpRequest();
    req.open("GET", "https://shop.example/endpoint");
    // Check availability of setAttributionReporting() before calling
    if (typeof req.setAttributionReporting === "function") {
      req.setAttributionReporting(attributionReporting);
      req.send();
    } else {
      throw new Error("Attribution reporting not available");
      // Include recovery code here as appropriate
    }
  }
  
  // Associate the interaction trigger with whatever
  // event makes sense for your code (does not have to be a
  // DOM event/user interaction)
  elem.addEventListener("click", triggerSourceInteraction);
  

在這種情況下，當瀏覽器收到來自 fetch 請求的響應時，交互發生，瀏覽器儲存源資料。

在 attributionsrc 中指定 URL

到目前為止，在我們看到的所有示例中，attributionsrc 屬性/功能或 attributionSrc 屬性都留空，取空字串值。如果持有請求資源的伺服器與您還希望處理註冊的伺服器是同一個伺服器，即接收 Attribution-Reporting-Eligible 頭並響應 Attribution-Reporting-Register-Source 頭，則此做法是可行的。

但是，所請求的資源可能不在您控制的伺服器上，或者您只是想在不同的伺服器上處理歸因源的註冊。在這種情況下，您可以將一個或多個 URL 指定為 attributionsrc 的值。當資源請求發生時，除了資源源之外，Attribution-Reporting-Eligible 頭將被髮送到 attributionsrc 中指定的 URL；這些 URL 隨後可以響應 Attribution-Reporting-Register-Source 以註冊源。

例如，對於 <a> 元素，您可以在 attributionsrc 屬性中宣告 URL：

<a
  href="https://shop.example"
  attributionsrc="https://a.example/register-source">
  Click to visit our shop
</a>

或在 JavaScript 中透過 attributionSrc 屬性：

// encode the URLs in case they contain special characters
// such as '=' that would be improperly parsed.
const encodedUrlA = encodeURIComponent("https://a.example/register-source");
const encodedUrlB = encodeURIComponent("https://b.example/register-source");

const aElem = document.querySelector("a");
aElem.attributionSrc = `${encodedUrlA} ${encodedUrlB}`;

對於 Window.open() 呼叫，不同的 URL 必須在 windowFeatures 引數中列為多個單獨的 attributionsrc 功能，用逗號或空格分隔：

// encode the URLs in case they contain special characters
// such as '=' that would be improperly parsed.
const encodedUrlA = encodeURIComponent("https://a.example/register-source");
const encodedUrlB = encodeURIComponent("https://b.example/register-source");

elem.addEventListener("click", () => {
  window.open(
    "https://ourshop.example",
    "_blank",
    `attributionsrc=${encodedUrlA},attributionsrc=${encodedUrlB}`,
  );
});

另見

• 歸因報告頭驗證工具