Attribution-Reporting-Register-Source 頭

語法

Attribution-Reporting-Register-Source: <json-string>

指令

<json-string>

一個 JSON 字串，提供當歸因來源被互動時瀏覽器應儲存的資訊。可用欄位如下：

"source_event_id" 可選

一個表示歸因來源 ID 的字串，當與歸因來源互動時，該 ID 可用於將其對映到其他資訊，或在報告端點聚合資訊。該字串必須僅由一個基數為 10 格式的 64 位無符號整陣列成。

"destination"

單個字串或 1-3 個字串的陣列。這些字串必須包含完整的 URL，對應於預期會發生觸發事件的站點（方案 + eTLD+1）。當觸發事件被互動時，它們用於將歸因觸發事件與來源匹配。

"aggregation_keys" 可選

一個物件，包含使用者提供的鍵，表示要在其下聚合報告值的不同資料點。

"aggregatable_report_window" 可選

一個字串，表示一個時間（以秒為單位），在該時間之後，觸發資料將不再包含在生成的聚合報告中（這稱為報告視窗）。如果未設定，則預設為 "expiry" 值。

"debug_key" 可選

一個基數為 10 格式的 64 位無符號整數，表示一個除錯鍵。如果您想在關聯的歸因報告旁邊生成除錯報告，請設定此項。

"debug_reporting" 可選

一個布林值。如果設定了 debug_key，請將其設定為 true 以指定生成的除錯報告應為詳細除錯報告。

"event_level_epsilon" 可選

一個大於或等於 0 的數字，用於控制新增到報告中的噪聲量。較小的 epsilon 值會導致更多的噪聲，從而提供更大的隱私保護。最大值和預設值因實現而異；例如，Chrome 的最大值和預設值為 14。

"event_report_window" 可選

一個字串，表示一個時間（以秒為單位），在該時間之後，後續觸發事件將不再歸因於此來源，以便生成事件級報告（這稱為報告視窗）。如果未設定，則事件報告視窗將回退到 "expiry" 值。

注意：如果指定了 "event_report_window"，則不能指定 "event_report_windows"，否則來源註冊將失敗。

"event_report_windows" 可選

一個物件，表示一系列報告視窗，從 "start_time" 開始，此來源的報告在 "end_times" 中指定的每個結束時間之後交付。這可用於改變多個報告的報告交付時間。如果未設定，則事件報告視窗將回退到 "expiry" 值。屬性如下：

• "start_time" 可選：一個非負數，指定報告視窗的開始時間。如果未指定，則預設為 0。
• "end_times"：一個正數陣列，指定後續報告視窗的結束時間。這些值必須遞增，並且大於 "start_time"。

  注意：如果指定了 "event_report_windows"，則不能指定 "event_report_window"，否則來源註冊將失敗。

"expiry" 可選

一個字串，表示歸因來源的到期時間（以秒為單位），在此時間之後它將不再處於活動狀態（即，後續觸發事件將不再歸因於此來源）。允許的最大到期時間是 2592000 秒（30 天），這也是未明確設定 "expiry" 時的預設值。

"filter_data" 可選

一個物件，定義可用於過濾哪些轉換生成報告的自定義資料。有關更多詳細資訊，請參閱過濾器。

"max_event_level_reports" 可選

一個介於 0 和 20 之間（含）的數字，指定此來源可以生成的事件級報告總數。達到此最大值後，該來源將無法再生成任何新資料。如果未指定，導航型來源的 "max_event_level_reports" 預設為 3，事件型（基於影像或指令碼）來源預設為 1。

"priority" 可選

一個字串，表示歸因來源的優先順序值。預設情況下，轉換歸因於最近匹配的來源。對於事件級和摘要報告，您可以設定更高的優先順序數字來優先處理特定來源。例如，值 2 優先於預設值 1。有關更多資訊，請參閱報告優先順序和限制。

"trigger_data" 可選

一個 32 位無符號整數陣列，表示描述可能與此來源匹配的不同觸發事件的資料。例如，“使用者將商品新增到購物車”或“使用者訂閱郵件列表”可能是觸發站點上發生的動作，這些動作可能與此來源匹配，並指示廣告商試圖衡量某種型別的轉換。對於事件級歸因發生，這些必須與觸發器中指定的 "trigger_data" 進行匹配。如果省略，導航型來源的 "trigger_data" 預設為 [0, 1, 2, 3, 4, 5, 6, 7]，事件型（基於影像或指令碼）來源預設為 [0, 1]。

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

"trigger_data_matching" 可選

一個字串，指定觸發器中的 "trigger_data" 如何與來源的 "trigger_data" 匹配。可能的值有：

• "exact"：觸發器中的 "trigger_data" 必須與來源的 "trigger_data" 中包含的值完全匹配；如果沒有這樣的匹配，則不會發生事件級歸因。
• "modulus"：在這種情況下，執行以下計算 — d % allowedValues.size — 其中 d 是觸發器中的 "trigger_data"，allowedValues 是來源的 "trigger_data" 陣列中的值序列。如果此計算結果與來源的 "trigger_data" 陣列中的值匹配，則匹配成功。在這種情況下，值將始終匹配，除非 allowedValues 為空。

"modulus" 模式主要用於與 API 在引入 "exact" 之前的行為進行向後相容，因此您不太可能使用它。它在需要非常特定型別的壓縮從而導致更小的註冊頭的情況下仍然有用。當使用複雜的過濾邏輯，需要根據來源型別根據來源 "trigger_data" 專案的最大數量設定不同的觸發器資料時，可能需要這樣做。

注意：如果使用 "modulus"，則來源的 "trigger_data" 必須形成從 0 開始的連續整數序列。如果觸發器資料不形成這樣的序列，則會發生錯誤。

如果未指定，"trigger_data_matching" 預設為 "modulus"。同樣，這是為了向後相容：省略 "trigger_data_matching" 欄位需要產生與引入此欄位之前觀察到的相同行為。

示例

為事件級報告註冊來源

當觸發器與來源匹配時，Node.js 伺服器可能會如下設定 Attribution-Reporting-Register-Source 響應頭，以使瀏覽器生成事件級報告：

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

為摘要報告註冊來源

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

res.set(
  "Attribution-Reporting-Register-Source",
  JSON.stringify({
    source_event_id: "412444888111012",
    destination: "https://shop.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",
  }),
);

規範

瀏覽器相容性

另見

• Attribution-Reporting-Eligible
• Attribution-Reporting-Register-Trigger
• 歸因報告 API