關於歸因報表偵錯作業的第 2 部分 (共 3 部分)。設定偵錯報表。
詞彙
- 報表來源是 [設定歸因報表來源和觸發事件標頭的「來源」。瀏覽器產生的所有報告都會傳送至這個來源。在本指南中，我們使用
https://adtech.example做為報表來源範例。 - 「歸因報表」 (簡稱「報表」) 是含有您要求評估資料的最終報表 (事件層級或可匯總報表)。
- 偵錯報表包含歸因報表或來源或觸發事件的其他相關資料。接收偵錯報表並不一定表示一切運作正常！偵錯報表分為兩種類型
- 轉換偵錯報表是偵錯報表，需要設定 Cookie 才能產生及傳送。如果未設定 Cookie，且第三方 Cookie 淘汰後，就無法使用轉換偵錯報表。本指南所述的所有偵錯報表都是轉換偵錯報表。
- 成功偵錯報表會追蹤歸因報表產生成功。 因為這些指標與歸因報表直接相關。成功偵錯報表自 Chrome 101 版 (2022 年 4 月) 起已提供。
- 詳細偵錯報表可追蹤遺失報表，協助您找出缺少報表的原因。能指出瀏覽器沒有記錄來源或觸發事件的情況 (也就是說，不會產生歸因報表)，以及因故無法產生或傳送歸因報表的情況。詳細偵錯報表包含一個
type欄位，說明無法產生來源事件、觸發事件或歸因報表的原因。詳細偵錯報表自 Chrome 109 版起開始提供 (2023 年 1 月的穩定版)。 - 「偵錯金鑰」是您可以在來源端和觸發條件端設定的專屬 ID。偵錯鍵可讓您對應 Cookie 型轉換和歸因型轉換。如果您已設定系統產生偵錯報表並設定偵錯金鑰，瀏覽器就會在所有歸因報表和偵錯報表中加入這些偵錯金鑰。
如要進一步瞭解我們的說明文件使用的其他概念和重要詞彙，請參閱 Privacy Sandbox 詞彙表。
是否有導入方面的問題？
如果您在設定偵錯報表時遇到任何問題，請在我們的開發人員支援存放區中建立問題，我們將協助您進行疑難排解。
準備設定偵錯報表
設定偵錯報表前，請按照下列步驟操作：
檢查是否已採用 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 問題，請將標頭複製到標頭驗證工具工具中。這樣做可協助您找出並修正造成問題的欄位。
設定偵錯報表：成功報表和詳細報表的常見步驟
針對報表來源設定下列 Cookie：
Set-Cookie: ar_debug=1; SameSite=None; Secure; Path=/; HttpOnly
瀏覽器會在來源和觸發事件登錄作業中，檢查這個 Cookie 是否存在。只有在兩個時間都存在 Cookie 時，系統才會產生成功偵錯報表。
請注意，模式 B 的瀏覽器可以啟用偵錯報表，在該模式停用第三方 Cookie，以便測試及準備第三方 Cookie 淘汰作業。針對模式 B 的瀏覽器，您不需要設定偵錯 Cookie 即可啟用偵錯報表。請跳至步驟 2，為成功偵錯報表設定偵錯金鑰。
步驟 2：設定偵錯金鑰
每個偵錯金鑰都必須是採 Base-10 字串格式的 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」。 - 在「Event-level Reports」(事件層級報表) 和「Aggregatable Reports」(可匯總報表) 分頁中，確認已勾選「Show Debug Reports」(顯示偵錯報表) 核取方塊。
- 開啟已導入歸因報表的網站。請完成您用來產生歸因報表的步驟；以上步驟將會產生成功的偵錯報表。
- 在
chrome://attribution-internals中：- 檢查歸因報表是否正確產生。
- 在「Event-level Reports」(事件層級報表) 和「Aggregatable Reports」(可匯總報表) 分頁中，檢查是否一併產生成功偵錯報表。請在清單中透過藍色的
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：確認設定後，系統就會產生詳細偵錯報表
雖然詳細偵錯報表有多種類型，但僅使用一種詳細偵錯報表來檢查詳細偵錯設定。如果系統正確產生及接收這類詳細偵錯報表，就表示所有詳細偵錯報表都使用相同的設定並傳送至相同的端點，因此也能正確產生及接收所有類型的偵錯報表。
- 在瀏覽器中開啟「
chrome://attribution-internals」。 - 在採用歸因報表設定的網站上，觸發歸因 (轉換)。由於在這個轉換前沒有廣告參與 (曝光或點擊)，因此您應該會產生
trigger-no-matching-source類型的詳細偵錯報表。 - 在
chrome://attribution-internals中開啟「Verbose debug reports」分頁，確認是否已產生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)