1. Web
  2. Web API
  3. 歸因報告 API
  4. 註冊歸因觸發器

註冊歸因觸發器

本文件解釋瞭如何註冊歸因觸發器。

基本方法

在您註冊歸因來源之後，您需要註冊歸因觸發器。這些是用於衡量轉化的網站上的互動（例如，點選廣告商網站上的“購買”按鈕可能表明已發生轉化）。然後，瀏覽器將嘗試將歸因觸發器與儲存在私有本地儲存分割槽中的歸因來源條目進行匹配，並在找到匹配項時生成報告。

不同型別的歸因觸發器以不同的方式註冊，這些將在下面的各節中詳細介紹 — 請參閱基於 HTML 的歸因觸發器和基於 JavaScript 的歸因觸發器。

然而，在後臺發生的一切，例如註冊觸發器、查詢匹配項等，在所有情況下都是相同的。

  1. 所有觸發器型別都會在請求中傳送一個Attribution-Reporting-Eligible 標頭，該標頭表明響應有資格註冊觸發器。例如

    http
    Attribution-Reporting-Eligible: trigger

  2. 當伺服器收到包含 Attribution-Reporting-Eligible 標頭的請求時，它可以在響應中包含一個 Attribution-Reporting-Register-Trigger。其值是一個 JSON 字串，包含可以包含在生成的報告中的資料，例如觸發器的 ID、優先順序和去重值。

    以下示例旨在與事件級別報告歸因來源匹配

    js
    res.set(
  "Attribution-Reporting-Register-Trigger",
  JSON.stringify({
    event_trigger_data: [
      {
        trigger_data: "4",
        priority: "1000000000000",
        deduplication_key: "2345698765",
      },
    ],
    debug_key: "1115698977",
  }),
);

    此處指定的欄位如下

    • "event_trigger_data": 一個表示有關觸發器資料的物件。這包括
      • "trigger_data": 與觸發器關聯的資料，通常用於指示事件，例如“使用者將商品新增到購物車”或“使用者訂閱了郵件列表”。此值將包含在生成的報告（如果有）中，但可能會根據歸因來源的"trigger_data_matching" 欄位進行修改。

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

      • "priority": 一個表示歸因觸發器優先順序值的字串。有關更多資訊，請參閱報告優先順序和限制。
      • "deduplication_key": 一個表示唯一鍵的字串，可用於防止重複歸因 — 例如，如果使用者多次將同一商品新增到購物車。有關更多資訊，請參閱防止報告重複。
    • "debug_key": 一個表示除錯金鑰的數字。如果您想在關聯的歸因報告旁邊生成除錯報告，請設定此項。

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

    旨在與彙總報告歸因來源匹配的觸發器需要以下欄位

    js
    res.set(
  "Attribution-Reporting-Register-Trigger",
  JSON.stringify({
    aggregatable_trigger_data: [
      {
        key_piece: "0x400",
        source_keys: ["campaignCounts"],
      },
      {
        key_piece: "0xA80",
        source_keys: ["geoValue", "nonMatchingKeyIdsAreIgnored"],
      },
    ],
    aggregatable_values: {
      campaignCounts: 32768,
      geoValue: 1664,
    },
    debug_key: "1115698977",
  }),
);

    此示例中的欄位為

    • "aggregatable_trigger_data": 一個物件陣列，每個物件定義一個要應用於不同來源鍵的聚合鍵。
    • "aggregatable_values": 一個物件，包含表示 "aggregatable_trigger_data" 中定義的每個資料點的值的屬性。

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

  3. 當用戶與歸因觸發器互動時，瀏覽器會嘗試將觸發器與瀏覽器私有本地快取中儲存的任何歸因來源條目進行匹配。為了成功匹配，Attribution-Reporting-Register-Trigger 的"trigger_data" 必須與 Attribution-Reporting-Register-Source 的"trigger_data" 中提供的一個值匹配，並且註冊觸發器的頂層頁面的站點（方案 + eTLD+1）必須

    • 與源關聯資料中指定的至少一個 destination 的站點匹配。
    • 與指定來源註冊的請求同源。

    注意：這些要求提供了隱私保護，同時也帶來了靈活性 — 來源和觸發器都有可能嵌入在 <iframe> 中，或者位於頂層站點。

    還有許多其他因素會導致匹配失敗；例如

  4. 如果找到成功匹配，瀏覽器將生成一個報告，該報告基於來源和觸發器資料，並將其傳送到報告端點。

注意：與歸因來源一樣，歸因觸發器不能註冊在 <a> 元素或 Window.open() 呼叫上。

基於 HTML 的歸因觸發器

基於 HTML 的歸因觸發器可用於在頁面載入時 — 或者更準確地說，在 <img> 或 <script> 載入時 — 檢測頁面上的轉化。例如，如果使用者在釋出商頁面上點選了歸因來源連結並導航到廣告商頁面，您可以在廣告商頁面載入時註冊歸因觸發器，並讓瀏覽器嘗試與儲存的來源條目進行匹配。

您可以透過將 attributionsrc 屬性新增到適當的元素來註冊歸因觸發器。這可以應用於 <img> 和 <script> 元素。

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

這是一個 <img> 元素示例

html
<img
  src="https://shop.example/conversion/4rghshdh5"
  width="1"
  height="1"
  attributionsrc />

您也可以透過 HTMLImageElement.attributionSrc 屬性實現此目的

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

在這種情況下，當瀏覽器接收到包含影像檔案的響應（當 load 事件觸發時）時，它將嘗試將觸發器與已儲存的歸因來源進行匹配。請記住，使用者不一定能看到該影像 — 它可能是一個 1x1 的透明跟蹤畫素，僅用於歸因報告。

<script> 示例可能如下所示

html
<script src="advertising-script.js" attributionsrc></script>
js
const scriptElem = document.querySelector("script");
scriptElem.attributionSrc = "";

在這種情況下，當瀏覽器接收到包含指令碼的響應時，它將嘗試將觸發器與已儲存的歸因來源進行匹配。

基於 JavaScript 的歸因觸發器

基於 JavaScript 的歸因觸發器比基於 HTML 的歸因觸發器更具多功能性。您可以根據自定義互動觸發瀏覽器嘗試與已儲存來源匹配，例如，點選自定義元素或提交表單。

要註冊基於指令碼的歸因觸發器，您可以選擇以下任一方式：

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

    js
    const attributionReporting = {
  eventSourceEligible: false,
  triggerEligible: true,
};

// Optionally set keepalive to ensure the request outlives the page
function triggerMatching() {
  fetch("https://shop.example/endpoint", {
    keepalive: true,
    attributionReporting,
  });
}

// Associate the interaction trigger with whatever
// element and event makes sense for your code
elem.addEventListener("click", triggerMatching);

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

    js
    const attributionReporting = {
  eventSourceEligible: false,
  triggerEligible: true,
};

function triggerMatching() {
  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
// element and event makes sense for your code
elem.addEventListener("click", triggerMatching);

在這種情況下，當瀏覽器接收到 fetch 請求的響應時，它將嘗試將觸發器與已儲存的歸因來源進行匹配。

注意：請求可以是任何資源。它不需要直接與 Attribution Reporting API 相關，可以是 JSON、純文字、影像 blob 或任何對您的應用程式有意義的內容。

在 attributionsrc 中指定 URL

在上述示例中，attributionsrc 屬性留空，值為一個空字串。如果託管請求資源的伺服器與您希望處理註冊的伺服器相同（即，接收 Attribution-Reporting-Eligible 標頭並響應 Attribution-Reporting-Register-Trigger 標頭），則此設定是可以的。

然而，也可能存在託管請求資源的伺服器並非您控制的伺服器，或者您只是想在不同的伺服器上處理歸因觸發器的註冊。在這種情況下，您可以指定一個或多個 URL 作為 attributionsrc 的值。當發生資源請求時，Attribution-Reporting-Eligible 標頭將傳送到 attributionsrc 中指定的 URL 以及資源源；然後，這些 URL 可以響應 Attribution-Reporting-Register-Trigger 以完成註冊。

例如，在 <img> 元素的情況下，您可以在 attributionsrc 屬性中宣告 URL

html
<img
  src="https://shop.example/conversion/4rghshdh5"
  attributionsrc="https://my-separate-tracking-site.example.com"
  width="1"
  height="1" />

或者在 JavaScript 中透過 attributionSrc 屬性

js
const imgElem = document.querySelector("img");
imgElem.attributionSrc = "https://my-separate-tracking-site.example.com";

另見

幫助改進 MDN

瞭解如何貢獻

此頁面最後修改於 ，由 MDN 貢獻者修改。

在 GitHub 上檢視此頁面 • 報告此內容的問題
© . Content available under a Creative Commons license.