部分 Privacy Sandbox 技術即將淘汰。

請參閱這篇文章，瞭解我們對 Privacy Sandbox 技術的計畫更新。

Privacy Sandbox 功能狀態提供個別 API 和平台功能的狀態資訊。

設定 Attribution Reporting 的偵錯報表

這是「偵錯 Attribution Reporting」系列文章的第 2 部分，設定偵錯報告。

詞彙

The reporting origin is the origin that sets the Attribution Reporting source and trigger headers. All reports generated by the browser are sent to this origin. In this guidance, we use https://adtech.example as the example reporting origin.
An attribution report (report for short) is the final report (event-level or aggregatable) that contains the measurement data you've requested.
A debug report contains additional data about an attribution report, or about a source or trigger event. Receiving a debug report does not necessarily mean that something is working incorrectly! There are two types of debug reports
A transitional debug report is a debug report that requires a cookie to be set in order to be generated and sent. Transitional debug reports will be unavailable if a cookie is not set, and once third-party cookies are deprecated. All debug reports described in this guide are transitional debug reports.
Success debug reports track successful generation of an attribution report. They relate directly to an attribution report. Success debug reports have been available since Chrome 101 (April 2022).
Verbose debug reports can track missing reports and help you determine why they're missing. They indicate cases where the browser did not record a source or trigger event, (which means it will not generate an attribution report), and cases where an attribution report can't be generated or sent for some reason. Verbose debug reports include a type field that describes the reason why a source event, trigger event or attribution report was not generated. Verbose debug reports are available starting in Chrome 109 (Stable in January 2023).
Debug keys are unique identifiers you can set on both the source side and the trigger side. Debug keys enable you to map cookie-based conversions and attribution-based conversions. When you've set up your system to generate debug reports and set debug keys, the browser will include these debug keys in all attribution reports and debug reports.

For more concepts and key terms used throughout our documentation, refer to the Privacy Sandbox glossary.

導入相關問題

如果在設定偵錯報告時遇到任何問題，請在開發人員支援存放區中建立問題，我們會協助您排解疑難。

準備設定偵錯報告

設定偵錯報告前，請按照下列步驟操作：

確認您已採用 API 整合最佳做法

確認程式碼是否受到功能偵測機制保護。如要確保 API 不會遭到 Permissions-Policy 封鎖，請執行下列程式碼：
```
if (document.featurePolicy.allowsFeature('attribution-reporting')) {
// the Attribution Reporting API is enabled
}
```
如果這項功能偵測檢查傳回 true，表示 API 可在執行檢查的環境 (網頁) 中使用。
(測試階段不需執行此步驟：請確認您已設定 Permissions-Policy)

修正基本整合問題

雖然偵錯報告有助於大規模偵測及分析損失，但有些整合問題可以在本機偵測到。如果來源和觸發標頭設定錯誤、JSON 剖析發生問題、環境不安全 (非 HTTPS)，以及其他導致 API 無法運作的問題，都會顯示在開發人員工具的「問題」分頁中。

開發人員工具問題的類型可能不同。如果遇到invalid header問題，請將標頭複製到標頭驗證工具。這有助於找出並修正導致問題的欄位。

驗證歸因報表標頭

您可以使用標頭驗證工具，驗證與 Attribution Reporting API 相關的標頭。您可以監控瀏覽器發生的驗證錯誤，以便進行 API 偵錯。

如要選擇接收偵錯報表，請在 Attribution-Reporting-Info 回應標頭中加入 report-header-errors。

Attribution-Reporting-Info: report-header-errors

請注意，Attribution-Reporting-Info 是字典結構的標頭Attribution-Reporting-Info，因此提供布林值 report-header-errors 鍵即表示值為 true。

偵錯報表會立即傳送至回報端點：

https://<reporting origin>/.well-known/attribution-reporting/debug/verbose

要求主體會以 JSON 物件清單的形式包含報表資料，格式如下：

[{
  "type": "header-parsing-error",
  "body": {
    "context_site": "https://source.example",
    "header": "Attribution-Reporting-Register-Source",
    "value": "!!!", // header value received in the response
    "error": "invalid JSON" // optional error details that may vary across browsers or different versions of the same browser
  }
}]

設定偵錯報表：歸因成功報表和詳細報表的通用步驟

在報表來源中設定下列 Cookie：

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

瀏覽器會在來源和觸發條件登錄時檢查是否有這個 Cookie。只有在兩次都有 Cookie 的情況下，系統才會產生成功偵錯報表。

示範程式碼：debug cookie

請注意，您可以在模式 B 的瀏覽器中啟用偵錯報表，其中第三方 Cookie 已停用，方便您測試及為淘汰第三方 Cookie 做好準備。如果是模式 B 的瀏覽器，您不需要設定偵錯 Cookie 即可啟用偵錯報告。跳至步驟 2，設定成功偵錯報表的偵錯金鑰。

步驟 2：設定偵錯金鑰

每個偵錯金鑰都必須是採十進位字串格式的 64 位元無正負號整數。請為每個偵錯金鑰設定專屬 ID。只有在設定偵錯金鑰時，系統才會產生成功偵錯報表。

將來源端偵錯金鑰對應至您認為有助於偵錯的其他來源端資訊。
將觸發端偵錯鍵對應至您認為有助於偵錯的其他觸發時間資訊。

舉例來說，您可以設定下列偵錯鍵：

Cookie ID + 來源時間戳記做為來源偵錯鍵 (並在以 Cookie 為準的系統中擷取相同時間戳記)
Cookie ID + 觸發時間戳記做為觸發偵錯鍵 (並在以 Cookie 為基礎的系統中擷取相同時間戳記)

這樣一來，您就能使用以 Cookie 為準的轉換資訊，查詢對應的偵錯報表或歸因報表。詳情請參閱第 3 部分：食譜。

請將來源端的偵錯金鑰設為與 source_event_id 不同，這樣您就能區分具有相同來源事件 ID 的個別報表。

Attribution-Reporting-Register-Source:
{
// … Usual fields for Attribution-Reporting-Register-Source
"debug_key":"647775351539539"
}

Attribution-Reporting-Register-Trigger:
{
// … Usual fields for Attribution-Reporting-Register-Trigger
"debug_key":"938321351539743"
}

示範程式碼：來源偵錯金鑰 示範程式碼：觸發偵錯金鑰

設定成功偵錯報表

本節中的程式碼範例會產生事件層級和可彙整報表的成功偵錯報表。事件層級和可匯總報表使用相同的偵錯鍵。

步驟 3：設定端點，收集成功偵錯報告

設定端點來收集偵錯報表。這個端點應與主要歸因端點類似，路徑中會多出 debug 字串：

事件層級成功偵錯報表的端點： https://adtech.example/.well-known/attribution-reporting/debug/report-event-attribution
- 可匯總成功偵錯報表的端點： https://adtech.example/.well-known/attribution-reporting/debug/report-aggregate-attribution

當歸因觸發時，瀏覽器會立即使用 POST 要求，將偵錯報告傳送至這個端點。您的伺服器程式碼可能如下所示，可處理傳入的成功偵錯報告 (以下為節點端點)：

// Handle incoming event-Level Success Debug reports
adtech.post(
  '/.well-known/attribution-reporting/debug/report-event-attribution',
  async (req, res) => {
    // Debug report is in req.body
    res.sendStatus(200);
  }
);

// Handle incoming aggregatable Success Debug reports
adtech.post(
  '/.well-known/attribution-reporting/debug/report-aggregate-attribution',
  async (req, res) => {
    // Debug report is in req.body
    res.sendStatus(200);
  }
);

示範程式碼：事件層級偵錯報告端點

示範程式碼：可匯總的偵錯報告端點

步驟 4：確認設定會產生成功偵錯報告

在瀏覽器中開啟 chrome://attribution-internals。
請務必在「事件層級報表」和「可匯總報表」分頁中，勾選「顯示偵錯報表」核取方塊。
開啟您已導入歸因報表的網站。完成產生歸因報表的步驟，這些步驟也會產生成功偵錯報表。
在 chrome://attribution-internals 中：
- 確認已正確產生出價策略報表。
- 在「事件層級報表」和「可匯總報表」分頁中，確認系統也產生了成功偵錯報表。在清單中，以藍色 debug 路徑辨識這些項目。

在伺服器上，確認端點會立即收到這些成功偵錯報表。請務必檢查事件層級和可彙整的成功偵錯報表。

步驟 5：觀察成功偵錯報表

歸因成功偵錯報表與歸因報表相同，包含來源端和觸發端偵錯金鑰。

{
  "attribution_destination": "https://advertiser.example",
  "randomized_trigger_rate": 0.0000025,
  "report_id": "7d76ef29-d59e-4954-9fff-d97a743b4715",
  "source_debug_key": "647775351539539",
  "source_event_id": "760938763735530",
  "source_type": "event",
  "trigger_data": "0",
  "trigger_debug_key": "156477391437535"
}

{
  "aggregation_service_payloads": [
    {
      "debug_cleartext_payload": "omRkYXRhgqJldmFsdWVEAACAAGZidWNrZXRQPPhnkD+7c+wm1RjAlowp3KJldmFsdWVEAAARMGZidWNrZXRQJFJl9DLxbnMm1RjAlowp3GlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "d5f32b96-abd5-4ee5-ae23-26490d834012",
      "payload": "0s9mYVIuznK4WRV/t7uHKquHPYCpAN9mZHsUGNiYd2G/9cg87Y0IjlmZkEtiJghMT7rmg3GtWVPWTJU5MvtScK3HK3qR2W8CVDmKRAhqqlz1kPZfdGUB4NsXGyVCy2UWapklE/r7pmRDDP48b4sQTyDMFExQGUTE56M/8WFVQ0qkc7UMoLI/uwh2KeIweQCEKTzw"
    }
  ],
  "shared_info": "{\"api\":\"attribution-reporting\",\"attribution_destination\":\"https://advertiser.example\",\"debug_mode\":\"enabled\",\"report_id\":\"4a04f0ff-91e7-4ef6-9fcc-07d000c20495\",\"reporting_origin\":\"https://adtech.example\",\"scheduled_report_time\":\"1669888617\",\"source_registration_time\":\"1669852800\",\"version\":\"0.1\"}",
  "source_debug_key": "647775351539539",
  "trigger_debug_key": "156477391437535"
}

設定詳細偵錯報表

步驟 3：在來源和觸發標頭中選擇詳細偵錯

在 Attribution-Reporting-Register-Source 和 Attribution-Reporting-Register-Trigger 中，將 debug_reporting 設為 true。

Attribution-Reporting-Register-Source:
{
// … Usual fields for Attribution-Reporting-Register-Source
"debug_key":"938321351539743",
"debug_reporting": true // defaults to false if not present
}

Attribution-Reporting-Register-Trigger:
{
// … Usual fields for Attribution-Reporting-Register-Trigger
"debug_key":"938321351539743",
"debug_reporting": true // defaults to false if not present
}

示範程式碼：來源標頭

示範程式碼：觸發標頭

步驟 4：設定端點，收集詳細的偵錯報告

設定端點來收集偵錯報表。這個端點應與主要歸因端點類似，路徑中會多出 debug/verbose 字串：

https://adtech.example/.well-known/attribution-reporting/debug/verbose

產生詳細偵錯報表時 (也就是未註冊來源或觸發條件時)，瀏覽器會立即使用 POST 要求，將詳細偵錯報表傳送到這個端點。處理傳入詳細偵錯報告的伺服器程式碼可能如下所示 (這裡是在節點端點上)：

// Handle incoming verbose debug reports
adtech.post(
  '/.well-known/attribution-reporting/debug/verbose',
  async (req, res) => {
    // List of verbose debug reports is in req.body
    res.sendStatus(200);
  }
);

與成功偵錯報表不同，詳細報表只有一個端點。與事件層級和匯總報表相關的詳細報表，都會傳送至相同端點。

示範程式碼：詳細偵錯報表端點

步驟 5：確認設定會產生詳細的偵錯報告

詳細偵錯報表類型眾多，但您只需一種詳細偵錯報表，即可檢查詳細偵錯設定。如果系統能正確產生並接收這類詳細偵錯報表，表示系統也能正確產生並接收所有類型的詳細偵錯報表，因為所有詳細偵錯報表都使用相同的設定，且會傳送到相同的端點。

重點提示：挑選明顯的詳細偵錯報表進行測試。trigger-no-matching-source 是不錯的候選項目，因為您可以透過轉換產生。與觸發事件相關的詳細報表通常較適合；與來源事件相關的詳細報表則較難有目的地產生。

在瀏覽器中開啟 chrome://attribution-internals。
在已設定歸因報表的網站上觸發歸因 (轉換)。由於這項轉換前沒有任何廣告參與 (曝光或點擊)，因此系統應會產生詳細的偵錯報表 (類型為 trigger-no-matching-source)。
在 chrome://attribution-internals 中，開啟「詳細偵錯報表」分頁，並確認已產生 trigger-no-matching-source 類型的詳細偵錯報表。
在伺服器上，確認端點已立即收到這份詳細的偵錯報告。

步驟 6：查看詳細偵錯報表

在觸發事件發生時產生的詳細偵錯報表，會同時包含來源端和觸發事件端的偵錯金鑰 (如果觸發事件有相符的來源)。在來源時間產生的詳細偵錯報表會包含來源端偵錯金鑰。

以下是瀏覽器傳送的要求範例，其中包含詳細偵錯報表：

[
  {
    "body": {
      "attribution_destination": "http://arapi-advertiser.localhost",
      "randomized_trigger_rate": 0.0000025,
      "report_id": "92b7f4fd-b157-4925-999e-aad6361de759",
      "source_debug_key": "282273499788483",
      "source_event_id": "480041649210491",
      "source_type": "event",
      "trigger_data": "1",
      "trigger_debug_key": "282273499788483"
    },
    "type": "trigger-event-low-priority"
  },
  {
    "body": {
      "attribution_destination": "http://arapi-advertiser.localhost",
      "limit": "65536",
      "source_debug_key": "282273499788483",
      "source_event_id": "480041649210491",
      "source_site": "http://arapi-publisher.localhost",
      "trigger_debug_key": "282273499788483"
    },
    "type": "trigger-aggregate-insufficient-budget"
  }
]

每份詳細報表都包含以下欄位：

Type: 產生報表的原因。如要瞭解所有詳細報表類型，以及根據每種類型應採取的行動，請參閱「第 3 部分：偵錯食譜」中的詳細報表參考資料。
Body: 報表內文。視類型而定。請參閱第 3 部分：偵錯食譜中的詳細報表參考資料。

要求主體至少會包含一份詳細報表，最多兩份：

如果失敗只影響事件層級報表 (或只影響可匯總報表)，則為一份詳細報表。來源或觸發事件登錄失敗的原因只有一個，因此每個失敗事件和每種報表類型 (事件層級或可匯總) 都會產生一份詳細報表。
如果失敗影響事件層級和匯總報表，則會產生兩份詳細報表。但如果事件層級和匯總報表的失敗原因相同，則只會產生一份詳細報表 (例如：trigger-no-matching-source)

即將播放

第 3 部分：偵錯教戰手冊