Phần 2/3 về cách gỡ lỗi Báo cáo phân bổ. Thiết lập báo cáo gỡ lỗi.
Bảng thuật ngữ
- Nguồn gốc báo cáo là nguồn gốc đặt nguồn và tiêu đề điều kiện kích hoạt trong Báo cáo phân bổ.
Tất cả báo cáo do trình duyệt tạo sẽ được gửi đến nguồn này. Trong hướng dẫn này, chúng tôi sử dụng
https://adtech.examplelàm nguồn gốc báo cáo mẫu. - Báo cáo phân bổ (gọi tắt là báo cáo) là báo cáo cuối cùng (cấp sự kiện hoặc tổng hợp) chứa dữ liệu đo lường mà bạn đã yêu cầu.
- Báo cáo gỡ lỗi chứa dữ liệu bổ sung về báo cáo phân bổ hoặc về nguồn hay sự kiện điều kiện kích hoạt. Việc nhận được báo cáo gỡ lỗi không nhất thiết có nghĩa là có gì đó đang hoạt động không chính xác! Có hai loại báo cáo gỡ lỗi
- Báo cáo gỡ lỗi chuyển đổi là một báo cáo gỡ lỗi yêu cầu bạn phải đặt cookie để có thể tạo và gửi. Các báo cáo gỡ lỗi chuyển đổi sẽ không có sẵn nếu bạn không đặt cookie và sau khi cookie của bên thứ ba không được dùng nữa. Tất cả báo cáo gỡ lỗi được mô tả trong hướng dẫn này đều là báo cáo gỡ lỗi chuyển đổi.
- Báo cáo gỡ lỗi thành công theo dõi việc tạo báo cáo phân bổ thành công. Chúng liên quan trực tiếp đến báo cáo phân bổ. Báo cáo gỡ lỗi thành công đã có từ Chrome 101 (tháng 4 năm 2022).
- Báo cáo gỡ lỗi chi tiết có thể theo dõi các báo cáo bị thiếu và giúp bạn xác định lý do các báo cáo đó bị thiếu. Những báo cáo này cho biết các trường hợp trình duyệt không ghi lại sự kiện nguồn hoặc sự kiện kích hoạt, (nghĩa là trình duyệt sẽ không tạo báo cáo phân bổ) và các trường hợp không thể tạo hoặc gửi báo cáo phân bổ vì lý do nào đó.
Báo cáo gỡ lỗi chi tiết bao gồm một trường
typemô tả lý do không tạo được một sự kiện nguồn, sự kiện liên quan đến điều kiện kích hoạt hoặc báo cáo phân bổ. Báo cáo gỡ lỗi chi tiết sẽ có từ phiên bản Chrome 109 (Ổn định vào tháng 1 năm 2023). - Khoá gỡ lỗi là các giá trị nhận dạng duy nhất mà bạn có thể đặt ở cả phía nguồn và phía điều kiện kích hoạt. Khoá gỡ lỗi cho phép bạn liên kết các lượt chuyển đổi dựa trên cookie và các lượt chuyển đổi dựa trên mô hình phân bổ. Khi bạn đã thiết lập hệ thống để tạo báo cáo gỡ lỗi và đặt khoá gỡ lỗi, trình duyệt sẽ đưa các khoá gỡ lỗi này vào tất cả báo cáo phân bổ và báo cáo gỡ lỗi.
Để biết thêm các khái niệm và thuật ngữ chính được dùng trong tài liệu của chúng tôi, hãy tham khảo bảng chú giải thuật ngữ Hộp cát về quyền riêng tư.
Bạn có câu hỏi về việc triển khai?
Nếu bạn gặp vấn đề khi thiết lập báo cáo gỡ lỗi, hãy tạo vấn đề trên kho lưu trữ hỗ trợ nhà phát triển của chúng tôi và chúng tôi sẽ giúp bạn khắc phục sự cố.
Chuẩn bị thiết lập báo cáo gỡ lỗi
Trước khi thiết lập báo cáo gỡ lỗi, hãy làm theo các bước sau:
Kiểm tra để đảm bảo bạn đã áp dụng các phương pháp hay nhất để tích hợp API
Kiểm tra để đảm bảo rằng mã của bạn bị hạn chế khi dùng tính năng phát hiện tính năng. Để đảm bảo API không bị Permissions-Policy chặn, hãy chạy mã sau:
if (document.featurePolicy.allowsFeature('attribution-reporting')) { // the Attribution Reporting API is enabled }Nếu quy trình kiểm tra để phát hiện tính năng này trả về giá trị true, thì API sẽ được cho phép trong ngữ cảnh (trang) nơi quy trình kiểm tra được thực hiện.
(Không bắt buộc trong giai đoạn kiểm thử: Kiểm tra để đảm bảo bạn đã đặt Permissions-Policy)
Khắc phục các vấn đề cơ bản về quá trình tích hợp
Mặc dù báo cáo gỡ lỗi rất hữu ích để giúp bạn phát hiện và phân tích tổn thất trên quy mô lớn, nhưng bạn có thể phát hiện một số vấn đề tích hợp cục bộ. Các vấn đề về cấu hình sai tiêu đề nguồn và điều kiện kích hoạt, vấn đề phân tích cú pháp JSON, ngữ cảnh không an toàn (không phải HTTPS) và các vấn đề khác khiến API không hoạt động sẽ xuất hiện trong thẻ Vấn đề của DevTools.
Các vấn đề về DevTools có thể thuộc nhiều loại. Nếu bạn gặp vấn đề về invalid header, hãy sao chép tiêu đề vào công cụ xác thực tiêu đề. Điều này sẽ giúp bạn xác định và khắc phục trường đang gây ra vấn đề.
Xác thực tiêu đề báo cáo phân bổ
Bạn có thể sử dụng trình xác thực tiêu đề để xác thực các tiêu đề có liên quan đến API Báo cáo phân bổ. Bạn có thể theo dõi các lỗi xác thực bắt nguồn từ trình duyệt để tạo điều kiện gỡ lỗi API.
Để chọn nhận báo cáo gỡ lỗi, hãy phản hồi bằng report-header-errors trong tiêu đề phản hồi Attribution-Reporting-Info.
Attribution-Reporting-Info: report-header-errors
Xin lưu ý rằng Attribution-Reporting-Info là một tiêu đề có cấu trúc theo từ điểnAttribution-Reporting-Info, vì vậy, việc cung cấp khoá report-header-errors boolean ngụ ý một giá trị thực.
Báo cáo gỡ lỗi được gửi ngay lập tức đến điểm cuối báo cáo:
https://<reporting origin>/.well-known/attribution-reporting/debug/verbose
Dữ liệu báo cáo được đưa vào nội dung yêu cầu dưới dạng danh sách JSON chứa các đối tượng có biểu mẫu này:
[{
"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
}
}]
Thiết lập báo cáo gỡ lỗi: các bước chung cho báo cáo thành công và báo cáo chi tiết
Đặt cookie sau đây trên nguồn báo cáo:
Set-Cookie: ar_debug=1; SameSite=None; Secure; Path=/; HttpOnly
Trình duyệt sẽ kiểm tra xem cookie này có trên cả nguồn và đăng ký điều kiện kích hoạt hay không. Báo cáo gỡ lỗi thành công sẽ chỉ được tạo nếu có cookie ở cả hai thời điểm.
Xin lưu ý rằng bạn có thể bật báo cáo gỡ lỗi cho các trình duyệt ở Chế độ B, trong đó cookie của bên thứ ba bị tắt để tạo điều kiện cho việc kiểm thử và chuẩn bị cho việc ngừng sử dụng cookie của bên thứ ba. Đối với trình duyệt ở Chế độ B, bạn không cần đặt cookie gỡ lỗi để bật báo cáo gỡ lỗi. Hãy chuyển sang bước 2 để thiết lập khoá gỡ lỗi cho báo cáo gỡ lỗi thành công.
Bước 2: Đặt khoá gỡ lỗi
Mỗi khoá gỡ lỗi phải là một số nguyên 64 bit chưa ký có định dạng chuỗi cơ sở 10. Đặt mỗi khoá gỡ lỗi là một mã nhận dạng duy nhất. Báo cáo gỡ lỗi thành công sẽ chỉ được tạo nếu bạn đã đặt khoá gỡ lỗi.
- Liên kết khoá gỡ lỗi phía nguồn với thông tin thời gian nguồn bổ sung mà bạn nghĩ là phù hợp để gỡ lỗi.
- Liên kết khoá gỡ lỗi phía trình kích hoạt với thông tin bổ sung về thời gian kích hoạt mà bạn nghĩ là phù hợp để gỡ lỗi.
Ví dụ: bạn có thể đặt các khoá gỡ lỗi sau:
- Mã cookie + Dấu thời gian nguồn làm khoá gỡ lỗi nguồn (và ghi lại cùng một dấu thời gian đó trong hệ thống dựa trên cookie)
- Mã nhận dạng cookie + Dấu thời gian của điều kiện kích hoạt làm khoá gỡ lỗi cho điều kiện kích hoạt (và ghi lại cùng dấu thời gian đó trong hệ thống dựa trên cookie)
Nhờ tính năng này, bạn có thể sử dụng thông tin lượt chuyển đổi dựa trên cookie để tìm kiếm báo cáo gỡ lỗi hoặc báo cáo phân bổ tương ứng. Tìm hiểu thêm trong Phần 3: Sách dạy nấu ăn.
Hãy đặt khoá gỡ lỗi phía nguồn khác với source_event_id để bạn có thể phân biệt các báo cáo riêng lẻ có cùng mã sự kiện nguồn.
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"
}
Mã minh hoạ: khoá gỡ lỗi nguồn Mã minh hoạ: khoá gỡ lỗi kích hoạt
Thiết lập báo cáo gỡ lỗi thành công
Mã mẫu trong phần này tạo báo cáo gỡ lỗi thành công cho cả báo cáo cấp sự kiện và báo cáo tổng hợp. Báo cáo cấp sự kiện và báo cáo tổng hợp sử dụng cùng một khoá gỡ lỗi.
Bước 3: Thiết lập điểm cuối để thu thập báo cáo gỡ lỗi thành công
Thiết lập một điểm cuối để thu thập báo cáo gỡ lỗi. Điểm cuối này phải tương tự như điểm cuối phân bổ chính, với một chuỗi debug bổ sung trong đường dẫn:
- Điểm cuối cho báo cáo gỡ lỗi thành công ở cấp sự kiện:
https://adtech.example/.well-known/attribution-reporting/debug/report-event-attribution- Điểm cuối cho báo cáo gỡ lỗi thành công có thể tổng hợp:
https://adtech.example/.well-known/attribution-reporting/debug/report-aggregate-attribution
- Điểm cuối cho báo cáo gỡ lỗi thành công có thể tổng hợp:
Khi một lượt phân bổ được kích hoạt, trình duyệt sẽ ngay lập tức gửi báo cáo gỡ lỗi qua yêu cầu POST đến điểm cuối này. Mã máy chủ của bạn để xử lý các báo cáo gỡ lỗi thành công đến có thể có dạng như sau (ở đây là điểm cuối của nút):
// 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);
}
);
Mã minh hoạ: điểm cuối báo cáo gỡ lỗi ở cấp sự kiện
Mã minh hoạ: điểm cuối của báo cáo gỡ lỗi tổng hợp
Bước 4: Xác nhận rằng chế độ thiết lập của bạn sẽ tạo báo cáo gỡ lỗi thành công
- Mở
chrome://attribution-internalstrong trình duyệt. - Đảm bảo bạn đã đánh dấu vào hộp đánh dấu Hiển thị báo cáo gỡ lỗi trong cả thẻ Báo cáo cấp sự kiện và Báo cáo tổng hợp.
- Mở những trang web mà bạn đã triển khai Báo cáo phân bổ. Hoàn tất các bước bạn sử dụng để tạo báo cáo phân bổ; các bước này cũng sẽ tạo báo cáo gỡ lỗi thành công.
- Trong
chrome://attribution-internals:- Kiểm tra để đảm bảo báo cáo phân bổ được tạo chính xác.
- Trong thẻ Báo cáo ở cấp sự kiện và thẻ Báo cáo tổng hợp, hãy kiểm tra để đảm bảo rằng các báo cáo gỡ lỗi thành công cũng đã được tạo. Nhận ra các thiết bị này trong danh sách bằng đường dẫn
debugmàu xanh dương.
- Trên máy chủ, hãy xác minh rằng điểm cuối của bạn nhận được ngay các báo cáo gỡ lỗi thành công này. Hãy nhớ kiểm tra cả báo cáo gỡ lỗi thành công ở cấp sự kiện và báo cáo tổng hợp.
Bước 5: Quan sát báo cáo gỡ lỗi thành công
Báo cáo gỡ lỗi thành công giống với báo cáo phân bổ và chứa cả khoá gỡ lỗi phía nguồn và phía điều kiện kích hoạt.
{
"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"
}
Thiết lập báo cáo gỡ lỗi chi tiết
Bước 3: Chọn gỡ lỗi chi tiết trong tiêu đề nguồn và điều kiện kích hoạt
Đặt debug_reporting thành true trong cả Attribution-Reporting-Register-Source và Attribution-Reporting-Register-Trigger.
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
}
Mã minh hoạ: tiêu đề điều kiện kích hoạt
Bước 4: Thiết lập điểm cuối để thu thập báo cáo gỡ lỗi chi tiết
Thiết lập một điểm cuối để thu thập báo cáo gỡ lỗi. Điểm cuối này phải tương tự như điểm cuối phân bổ chính, với một chuỗi debug/verbose bổ sung trong đường dẫn:
https://adtech.example/.well-known/attribution-reporting/debug/verbose
Khi báo cáo gỡ lỗi chi tiết được tạo, tức là khi một nguồn hoặc điều kiện kích hoạt không được đăng ký, trình duyệt sẽ ngay lập tức gửi báo cáo gỡ lỗi chi tiết thông qua yêu cầu POST đến điểm cuối này. Mã máy chủ của bạn để xử lý các báo cáo gỡ lỗi chi tiết đến có thể có dạng như sau (ở đây là điểm cuối của nút):
// 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);
}
);
Không giống như báo cáo gỡ lỗi thành công, báo cáo chi tiết chỉ có một điểm cuối. Tất cả các báo cáo chi tiết liên quan đến báo cáo tổng hợp và báo cáo cấp sự kiện đều sẽ được gửi đến cùng một điểm cuối.
Mã minh hoạ: điểm cuối của báo cáo gỡ lỗi chi tiết
Bước 5: Xác nhận rằng chế độ thiết lập của bạn sẽ tạo báo cáo gỡ lỗi chi tiết
Mặc dù có nhiều loại báo cáo gỡ lỗi chi tiết, nhưng bạn chỉ cần kiểm tra chế độ thiết lập gỡ lỗi chi tiết bằng một loại báo cáo gỡ lỗi chi tiết là đủ. Nếu một loại báo cáo gỡ lỗi chi tiết này được tạo và nhận chính xác, thì tất cả các loại báo cáo gỡ lỗi chi tiết cũng sẽ được tạo và nhận chính xác, vì tất cả các báo cáo gỡ lỗi chi tiết đều sử dụng cùng một cấu hình và được gửi đến cùng một điểm cuối.
- Mở
chrome://attribution-internalstrong trình duyệt. - Kích hoạt mô hình phân bổ (chuyển đổi) trên trang web được thiết lập bằng Báo cáo phân bổ. Do không có lượt tương tác với quảng cáo (lượt hiển thị hoặc lượt nhấp) trước lượt chuyển đổi này, nên bạn sẽ thấy một báo cáo gỡ lỗi chi tiết thuộc loại
trigger-no-matching-sourceđược tạo. - Trong
chrome://attribution-internals, hãy mở thẻ Báo cáo gỡ lỗi chi tiết và kiểm tra để đảm bảo rằng bạn đã tạo báo cáo gỡ lỗi chi tiết thuộc loạitrigger-no-matching-source. - Trên máy chủ của bạn, hãy xác minh rằng điểm cuối của bạn đã ngay lập tức nhận được báo cáo gỡ lỗi chi tiết này.
Bước 6: Quan sát báo cáo gỡ lỗi chi tiết
Báo cáo gỡ lỗi chi tiết được tạo tại thời điểm kích hoạt bao gồm cả khoá gỡ lỗi phía nguồn và phía điều kiện kích hoạt (nếu có nguồn phù hợp cho điều kiện kích hoạt). Báo cáo gỡ lỗi chi tiết được tạo tại thời điểm nguồn bao gồm khoá gỡ lỗi phía nguồn.
Ví dụ về yêu cầu chứa báo cáo gỡ lỗi chi tiết do trình duyệt gửi:
[
{
"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"
}
]
Mỗi báo cáo chi tiết chứa các trường sau:
Type- Lý do khiến báo cáo được tạo. Để tìm hiểu về tất cả các loại báo cáo chi tiết và hành động cần thực hiện tuỳ theo từng loại, hãy xem tài liệu tham khảo về báo cáo chi tiết trong Phần 3: Sách dạy nấu ăn về gỡ lỗi.
Body- Nội dung của báo cáo. Điều này sẽ phụ thuộc vào loại điểm phát sóng. Xem lại tài liệu tham khảo về báo cáo chi tiết trong Phần 3: Sách dạy nấu ăn về gỡ lỗi.
Nội dung của yêu cầu sẽ chứa ít nhất một và tối đa hai báo cáo chi tiết:
- Một báo cáo chi tiết nếu lỗi chỉ ảnh hưởng đến các báo cáo cấp sự kiện (hoặc nếu lỗi chỉ ảnh hưởng đến các báo cáo tổng hợp). Lỗi đăng ký nguồn hoặc điều kiện kích hoạt chỉ có một lý do; do đó, hệ thống có thể tạo một báo cáo chi tiết cho mỗi lỗi và mỗi loại báo cáo (cấp sự kiện hoặc tổng hợp).
- Hai báo cáo chi tiết nếu lỗi ảnh hưởng đến cả báo cáo ở cấp sự kiện và báo cáo tổng hợp, ngoại trừ trường hợp: nếu lý do lỗi giống nhau đối với báo cáo ở cấp sự kiện và báo cáo tổng hợp, thì chỉ một báo cáo chi tiết được tạo (ví dụ:
trigger-no-matching-source)