1. Web
  2. Web API
  3. 歸因報告 API
  4. 生成歸因報告

生成歸因報告

本文解釋了歸因報告 API 報告（包括歸因報告和除錯報告）的生成方式，以及如何控制生成的報告。這包括處理噪聲、設定報告優先順序、過濾報告和生成除錯報告。

基本流程

當觸發器與源匹配時，瀏覽器會生成一份報告，並透過未經身份驗證的 POST 請求將其傳送到報告來源上的特定端點。

  • 對於事件級報告，端點是 <reporting-origin>/.well-known/attribution-reporting/report-event-attribution。
  • 對於彙總報告，端點是 <reporting-origin>/.well-known/attribution-reporting/report-aggregate-attribution。

<reporting-origin> 將與註冊源和觸發器的來源相同。

報告資料包含在 JSON 結構中。

事件級報告

事件級報告生成後，會安排在其所屬的報告視窗結束時傳送。報告視窗的長度由源的 Attribution-Reporting-Register-Source 頭部中設定的 "event_report_window" 或 "event_report_windows" 欄位的值決定。

如果這兩個欄位都沒有指定，報告視窗將回退到以下預設值：

  • 對於基於事件的源，預設報告視窗在源的過期時間結束，該時間在 Attribution-Reporting-Register-Source "expiry" 欄位中設定。如果未明確設定，則預設為註冊後 30 天。
  • 對於基於導航的源，預設報告視窗是 2 天、7 天和源的 "expiry"。

有關更多詳細資訊，請參閱自定義報告視窗。

一旦事件級報告在適當的端點收到，資料的處理、儲存和顯示方式完全由開發者決定。典型的事件級報告可能如下所示：

json
{
  "attribution_destination": "https://advertiser.example",
  "source_event_id": "412444888111012",
  "trigger_data": "4",
  "report_id": "123e4567-e89b-12d3-a456-426614174000",
  "source_type": "navigation",
  "randomized_trigger_rate": 0.34,
  "scheduled_report_time": "1692255696",
  "source_debug_key": 647775351539539,
  "trigger_debug_key": 647776891539539
}

屬性如下：

"attribution_destination"

一個字串，或一個包含 2-3 個字串的陣列，取決於源是否註冊了多個目標。這些字串表示在源註冊中透過關聯的 Attribution-Reporting-Register-Source 響應頭部設定的歸因 "destination" 站點。

"source_event_id"

一個字串，表示歸因源 ID。這等於在源註冊中設定的 "source_event_id"（透過關聯的 Attribution-Reporting-Register-Source 響應頭部）。

"trigger_data"

一個字串，表示源自歸因觸發器的資料，在觸發器註冊中設定（透過關聯的 Attribution-Reporting-Register-Trigger 響應頭部設定的 "trigger_data"）。

"report_id"

一個字串，表示此報告的通用唯一識別符號 (UUID)，可用於防止重複計數。

"source_type"

一個字串，等於 "navigation" 或 "event"，分別表示關聯的歸因源是基於導航的還是基於事件的。

"randomized_trigger_rate"

一個介於 0 和 1 之間的隨機數，表示對於此特定源配置，噪聲應用的頻率。

"scheduled_report_time"

一個字串，表示從 Unix Epoch 到瀏覽器最初計劃傳送報告的秒數（以避免由於離線裝置延遲報告而導致的不準確）。

"source_debug_key" 可選

一個 64 位無符號整數，表示歸因源的除錯鍵。這與關聯的 Attribution-Reporting-Register-Source 頭部中 "debug_key" 欄位設定的值相同。有關更多資訊，請參閱除錯報告。

"trigger_debug_key" 可選

一個 64 位無符號整數，表示歸因觸發器的除錯鍵。這與關聯的 Attribution-Reporting-Register-Trigger 頭部中 "debug_key" 欄位設定的值相同。有關更多資訊，請參閱除錯報告。

彙總報告

彙總報告由在適當端點收到的多個可聚合報告建立，然後進行批處理，以準備由聚合服務處理。一旦發生這種情況，資料的處理、儲存和顯示方式完全由開發者決定。

可聚合報告預設在觸發器互動後生成並安排傳送，並帶有隨機延遲以幫助模糊時間並提高隱私。對於給定的註冊歸因源，歸因源事件將從註冊到源過期一直記錄——這被稱為報告視窗。

過期時間由關聯的 Attribution-Reporting-Register-Source 頭部中設定的 expiry 值定義，如果未明確設定，則預設為註冊後 30 天。請記住，報告視窗的長度可以透過在 Attribution-Reporting-Register-Source 頭部中設定 aggregatable_report_window 值來進一步修改。有關更多詳細資訊，請參閱自定義報告視窗。

注意： 為了進一步保護使用者隱私，與每個歸因源關聯的彙總報告值具有有限的總值——這被稱為貢獻預算。此值在 API 的不同實現中可能有所不同；在 Chrome 中，它為 65,536。任何生成超過此限制的報告的轉換都不會被記錄。請務必跟蹤預算並在您嘗試衡量的不同指標之間共享。

典型的可聚合報告可能如下所示：

json
{
  "shared_info": "{\"api\":\"attribution-reporting\",\"attribution_destination\":\"https://advertiser.example\",\"report_id\":\"123e4567-e89b-12d3-a456-426614174000\",\"reporting_origin\":\"https://reporter.example\",\"scheduled_report_time\":\"1692255696\",\"source_registration_time\":\"1692230400\",\"version\":\"3\"}",
  "aggregation_service_payloads": [
    {
      "payload": "[base64-encoded HPKE encrypted data readable only by the aggregation service]",
      "key_id": "[string identifying public key used to encrypt payload]",
      "debug_cleartext_payload": "[base64-encoded unencrypted payload]"
    }
  ],
  "aggregation_coordinator_origin": "https://publickeyservice.aws.privacysandboxservices.com",
  "source_debug_key": 647775351539539,
  "trigger_debug_key": 647776891539539
}

屬性如下：

"shared_info"

這是一個序列化的 JSON 物件，提供聚合服務將用於彙總報告的資訊。此資料使用AEAD進行加密，以防止篡改。序列化字串中包含以下屬性：

"api"

一個列舉值，表示觸發報告生成的 API。目前它總是等於 "attribution-reporting"，但將來可能會擴充套件其他值以支援其他 API。

"attribution_destination"

一個字串，表示在源註冊中設定的歸因 "destination" URL（透過關聯的 Attribution-Reporting-Register-Source 響應頭部）。

"report_id"

一個字串，表示此報告的通用唯一識別符號 (UUID)，可用於防止重複計數。

"reporting_origin"

觸發報告生成的來源。

"scheduled_report_time"

一個字串，表示從 Unix Epoch 到瀏覽器最初計劃傳送報告的秒數（以避免由於離線裝置延遲報告而導致的不準確）。

"source_registration_time"

一個字串，表示從 Unix Epoch 到歸因源註冊的秒數，四捨五入到一整天。

"version"

一個字串，表示用於生成報告的 API 版本。

"aggregation_service_payloads"

一個物件陣列，表示包含聚合服務用於組裝報告中資料的直方圖貢獻的有效載荷物件。目前，每個報告僅支援一個由瀏覽器配置的有效載荷。將來可能會支援多個可自定義的有效載荷。每個有效載荷物件可以包含以下屬性：

"payload"

一個透過 HPKE 加密，然後進行 base64 編碼的 CBOR 對映，其結構如下（僅使用 JSON 進行表示）：

json
{
  "operation": "histogram",
  "data": [
    {
      "bucket": "<Encoded as a 16-byte (i.e. 128-bit) big-endian bytestring>",
      "value": "<Encoded as a 4-byte (i.e. 32-bit) big-endian bytestring>"
    }
    // …
  ]
}

operation 始終是 "histogram"；它允許服務將來支援其他操作。

"key_id"

一個字串，標識用於加密有效載荷的公鑰。

"debug_cleartext_payload" 可選

可選的除錯資訊。

"aggregation_coordinator_origin"

聚合服務的部署選項。

"source_debug_key" 可選

一個 64 位無符號整數，表示歸因源的除錯鍵。這與關聯的 Attribution-Reporting-Register-Source 頭部中 "debug_key" 欄位設定的值相同。有關更多資訊，請參閱除錯報告。

"trigger_debug_key" 可選

一個 64 位無符號整數，表示歸因觸發器的除錯鍵。這與關聯的 Attribution-Reporting-Register-Trigger 頭部中 "debug_key" 欄位設定的值相同。有關更多資訊，請參閱除錯報告。

為報告新增噪聲

為了模糊與特定源相關的輸出，從而保護使用者隱私，報告中會新增噪聲。確切的源資料無法識別並歸因於單個使用者，但從資料中獲取的總體模式仍將提供相同的含義。

有關歸因報告中噪聲工作原理的資訊，請參閱：

報告優先順序和限制

預設情況下，所有歸因源具有相同的優先順序，歸因模型是最後一次觸控，這意味著轉換歸因於最近匹配的源事件。對於事件級報告和可聚合報告，您都可以透過在關聯的 Attribution-Reporting-Register-Source 頭部中設定 "priority" 欄位的新值來更改源優先順序。預設值為 0；如果您在特定源上設定 "priority" 值為 1，則該源將首先匹配，排在任何優先順序為 0 的源之前。優先順序為 "2" 的源將排在優先順序為 "1" 的源之前匹配，依此類推。

歸因觸發器優先順序的工作方式相同；您還可以透過在關聯的 Attribution-Reporting-Register-Trigger 頭部中新增 "priority" 欄位來設定觸發器優先順序，但僅適用於事件級報告。

不同的源型別具有不同的預設限制：

  • 基於導航的歸因源預設有三個報告限制。例如，假設使用者點選廣告並轉換了四次：他們訪問了廣告客戶網站主頁，然後訪問了產品頁面，註冊了新聞通訊，最後進行了購買。購買報告將被丟棄，因為它來自第四次轉換。
  • 基於事件的歸因源預設有一個報告限制。

注意： 報告限制可以透過在關聯的 Attribution-Reporting-Register-Source 頭的 "event_report_windows" 欄位中設定不同數量的 "end_times" 來調整。

當為給定源事件觸發歸因時，如果該源的歸因最大數量（點選為三次，影像/指令碼為一次）已達到，瀏覽器將：

  • 比較新報告的優先順序與該相同源的現有計劃報告的優先順序。
  • 刪除優先順序最低的報告，以安排新報告。如果新報告是優先順序最低的報告，則將其忽略，您將不會收到它。

如果未設定優先順序，瀏覽器將回退到其預設行為：對於點選，第三次轉換之後或對於檢視，第一次轉換之後發生的任何轉換都將被丟棄。

過濾器

您可以使用過濾器來定義哪些轉換生成報告。例如，您可以選擇僅計算特定產品類別的轉換，並過濾掉其他類別的轉換。

要宣告過濾器：

  1. 在源註冊時，向 Attribution-Reporting-Register-Source 頭部新增 filter_data 欄位，該欄位定義您將在觸發器端用於過濾轉換的過濾器鍵。這些是完全自定義的欄位。例如，要僅指定特定子域和特定產品的轉換：

    json
    {
  "filter_data": {
    "conversion_subdomain": [
      "electronics.megastore",
      "electronics2.megastore"
    ],
    "product": ["1234"]
  }
}

  2. 在觸發器註冊時，向 Attribution-Reporting-Register-Trigger 頭部新增 filters 欄位。例如，以下內容導致觸發器互動與上述源註冊匹配，因為它們都包含 "electronics.megastore" "conversion_subdomain" 欄位。另一方面，當嘗試匹配時，"directory" 過濾器被忽略，因為它未包含在上述源註冊中。

    json
    {
  "filters": {
    "conversion_subdomain": ["electronics.megastore"],
    "directory": ["/store/electronics"]
  }
}

如果 "filter_data" 和 "filters" 欄位包含匹配的子欄位（如上例中的 "conversion_subdomain"），但所有子欄位的值都不匹配，則觸發器將被忽略，導致不匹配。

過濾觸發器資料

Attribution-Reporting-Register-Trigger 頭部中的 event_trigger_data 欄位可以擴充套件以進行選擇性過濾，從而根據 Attribution-Reporting-Register-Source 頭部中定義的 filter_data 設定 trigger_data、priority 或 deduplication_key。

例如

json
{
  "event_trigger_data": [
    {
      "trigger_data": "2",
      "filters": { "source_type": ["navigation"] }
    },
    {
      "trigger_data": "1",
      "filters": { "source_type": ["event"] }
    }
  ]
}

注意： "source_type" 是源 "filter_data" 上自動填充的欄位。

注意： 也支援 not_filters，它透過否定進行過濾。

在此上下文中，filters 可以是物件或物件陣列。指定列表時，只需匹配一個字典即可視為觸發器匹配。

json
{
  "event_trigger_data": [
    {
      "trigger_data": "2",
      "filters": [
        {
          "product": ["1234"],
          "conversion_subdomain": ["electronics.megastore"]
        },
        {
          "product": ["4321"],
          "conversion_subdomain": ["electronics4.megastore"]
        }
      ]
    }
  ]
}

如果過濾器與任何事件觸發器都不匹配，則不會建立事件級報告。如果過濾器與多個事件觸發器匹配，則使用第一個匹配的事件觸發器。

除錯報告

您可以啟用除錯報告以返回有關歸因報告的故障排除資訊。例如，這些報告可用於檢查您的設定是否正常工作，並瞭解您的舊版基於 Cookie 的實現與新版歸因報告實現之間測量結果的差距。除錯報告會立即傳送；它們不受事件級報告和彙總報告的相同排程限制。

有兩種不同型別的除錯報告：

  • 成功除錯報告跟蹤特定歸因報告的成功生成。成功除錯報告在相應觸發器註冊後立即生成併發送。
  • 詳細除錯報告讓您更深入地瞭解與歸因報告關聯的歸因源和歸因觸發器事件。它們使您能夠確保源已成功註冊，或跟蹤缺失的報告並確定其缺失的原因（例如由於源或觸發器事件註冊失敗或傳送或生成報告失敗）。詳細除錯報告在源或觸發器註冊後立即傳送。

注意： 要使用除錯報告，報告來源需要設定一個 cookie。如果配置為接收報告的來源是第三方，則此 cookie 將是第三方 cookie，這意味著在停用/不可用第三方 cookie 的瀏覽器中，除錯報告將不可用。

使用除錯報告

要使用除錯報告，您需要：

  1. 在您的報告來源上設定 ar_debug cookie。這在源註冊和觸發器註冊期間都需要存在。

    http
    Set-Cookie: ar_debug=1; SameSite=None; Secure; Path=/; HttpOnly

  2. 在任何您希望公開除錯資訊的歸因報告相關的 Attribution-Reporting-Register-Source 和 Attribution-Reporting-Register-Trigger 響應頭部中設定 debug_key 欄位。每個 debug_key 值必須是格式化為十進位制字串的 64 位無符號整數。使每個除錯鍵成為唯一的 ID——例如，您可以將每個鍵設定為 Cookie ID + 源/觸發器時間戳（如果您想比較兩者，可以在舊的基於 Cookie 的系統中捕獲相同的時間戳）。

    json
    {
  "debug_key": "647775351539539"
}

    注意： 使源側除錯鍵與 source_event_id 不同，這樣您就可以區分具有相同源事件 ID 的單個報告。

  3. （可選）在 Attribution-Reporting-Register-Source 和 Attribution-Reporting-Register-Trigger 頭部中將 debug_reporting 欄位設定為 true。如果這樣做，將生成一份詳細除錯報告。如果未這樣做，將生成一份反映您正在生成的歸因報告型別（事件級或可聚合）的成功除錯報告。

    json
    {
  "debug_key": "647775351539539",
  "debug_reporting": true
}

  4. 設定適當的端點以接收您要生成的除錯報告。除錯報告發送到報告來源中的三個單獨端點：

    • 事件級成功除錯報告的端點：<reporting-origin>/.well-known/attribution-reporting/debug/report-event-attribution
    • 可聚合成功除錯報告的端點：<reporting-origin>/.well-known/attribution-reporting/debug/report-aggregate-attribution
    • 詳細除錯報告的端點：<reporting-origin>/.well-known/attribution-reporting/debug/verbose

生成的成功除錯報告與歸因報告相同，並在 "source_debug_key" 和 "trigger_debug_key" 欄位中分別包含源側和觸發器側除錯鍵。

有關更多資訊和示例，請參閱：

幫助改進 MDN

瞭解如何貢獻

此頁面上次修改於 ，由 MDN 貢獻者完成。

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