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 bất kỳ vấn đề nào trong khi thiết lập báo cáo gỡ lỗi, hãy tạo vấn đề trên dịch vụ hỗ trợ nhà phát triển của chúng tôi kho lưu trữ 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 bạn 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ị Quyền-Chính sách chặn, hãy chạy mã sau:
if (document.featurePolicy.allowsFeature('attribution-reporting')) { // the Attribution Reporting API is enabled }Nếu kết quả kiểm tra để phát hiện tính năng này trả về giá trị true, thì API này được phép trong ngữ cảnh (trang) nơi chạy quy trình kiểm tra.
(Không bắt buộc trong giai đoạn thử nghiệm: Kiểm tra xem 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 trong việc giúp bạn phát hiện và phân tích tổn thất trên quy mô lớn, có thể phát hiện thấy một số vấn đề tích hợp trên thiết bị. Tiêu đề nguồn và điều kiện kích hoạt vấn đề cấu hình sai, 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 ngăn API hoạt động sẽ được hiển thị trong Thẻ Vấn đề của công cụ cho nhà phát triển.
Các vấn đề trong Công cụ cho nhà phát triển có thể thuộc nhiều loại. Nếu bạn gặp invalid header
hãy sao chép tiêu đề vào trình xác thực tiêu đề
công cụ. Chiến dịch này
sẽ giúp bạn xác định và khắc phục trường gây ra vấn đề.
Thiết lập báo cáo gỡ lỗi: các bước phổ biến để tạo báo cáo thành công và báo cáo chi tiết
Đặt cookie sau trên nguồn gốc báo cáo:
Set-Cookie: ar_debug=1; SameSite=None; Secure; Path=/; HttpOnly
Trình duyệt sẽ kiểm tra sự hiện diện của cookie này trên cả nguồn và đăng ký điều kiện kích hoạt. Báo cáo gỡ lỗi thành công sẽ chỉ được tạo nếu cookie xuất hiện ở cả hai thời điểm.
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 thử nghiệm và chuẩn bị việc ngừng sử dụng cookie của bên thứ ba. Đối với các 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. Chuyển sang bước 2 để thiết lập khoá gỡ lỗi để có 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 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 bổ sung về thời gian nguồn mà bạn nghĩ là phù hợp để bạn gỡ lỗi.
- Liên kết khoá gỡ lỗi phía điều kiện 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 để bạn 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à thu thập cùng một khoá trong hệ thống dựa trên cookie)
- Mã cookie + Dấu thời gian kích hoạt làm khoá gỡ lỗi điều kiện kích hoạt (và thu thập cùng trong hệ thống dựa trên cookie)
Với điều này, bạn có thể sử dụng thông tin lượt chuyển đổi dựa trên cookie để tra cứu 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ổ tay nấu ăn.
Tạo khoá gỡ lỗi phía nguồn khác với source_event_id để bạn có thể
để phân biệt từng 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ạ: gỡ lỗi nguồn khoá Mã minh hoạ: kích hoạt gỡ lỗi khoá
Thiết lập báo cáo gỡ lỗi thành công
Mã ví dụ trong phần này sẽ tạo báo cáo gỡ lỗi thành công cho cả hai các báo cáo tổng hợp và báo cáo cấp sự kiện. Sử dụng báo cáo cấp sự kiện và báo cáo tổng hợp 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ự
đến đ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 các báo cáo gỡ lỗi thành công tổng hợp:
https://adtech.example/.well-known/attribution-reporting/debug/report-aggregate-attribution
- Điểm cuối cho các báo cáo gỡ lỗi thành công tổng hợp:
Khi một mô hình phân bổ được kích hoạt, trình duyệt sẽ gửi ngay một tệp gỡ lỗi
báo cáo qua yêu cầu POST đến điểm cuối này. Mã máy chủ bạn cần xử lý
báo cáo gỡ lỗi thành công sắp tới 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ạ: báo cáo gỡ lỗi cấp sự kiện điểm cuối
Mã minh hoạ: báo cáo gỡ lỗi tổng hợp điểm cuối
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. - Hãy đảm bảo rằng bạn đã chọn hộp đánh dấu Show Debug Reporting (Hiển thị báo cáo gỡ lỗi), trong cả Báo cáo ở cấp sự kiện và thẻ 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 mà bạn dùng để tạo báo cáo phân bổ; các bước tương tự này 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,
kiểm tra để đảm bảo các báo cáo gỡ lỗi thành công cũng được tạo. Nhận ra người hâm mộ
trong danh sách bằng đường dẫn
debugmàu xanh dương.
- 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 những thông báo này các báo cáo gỡ lỗi. Hãy nhớ kiểm tra cả cấp sự kiện và cấp tổng hợp báo cáo gỡ lỗi thành công.
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à khoá gỡ lỗi 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 sử dụng tính năng 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ả hai 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ạ: kích hoạt tiêu đề
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ự
đến đ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, đó là khi nguồn hoặc điều kiện kích hoạt không
đã đă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ý thông tin chi tiết đến
báo cáo gỡ lỗi 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ả 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ạ: báo cáo gỡ lỗi chi tiết điểm cuối
Bước 5: Xác nhận rằng thông tin thiết lập của bạn sẽ tạo các 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 vẫn có thể hãy kiểm tra chế độ thiết lập gỡ lỗi chi tiết bằng chỉ một loại gỡ lỗi chi tiết báo cáo. Nếu loại báo cáo gỡ lỗi chi tiết này được tạo chính xác và điều này có nghĩa là tất cả các loại báo cáo gỡ lỗi chi tiết sẽ được được tạo và nhận bởi vì tất cả các báo cáo gỡ lỗi chi tiết đều sử dụng cùng một 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ột mô hình phân bổ (chuyển đổi) trên trang web được thiết lập bằng tính năng Phân bổ
Báo cáo. 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, bạn sẽ thấy một báo cáo gỡ lỗi chi tiết thuộc loại
trigger-no-matching-sourcesẽ đượ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 một báo cáo gỡ lỗi chi tiết thuộc loạitrigger-no-matching-sourceđã được tạo. - Trên máy chủ của bạn, hãy xác minh rằng điểm cuối của bạn đã nhận được thông tin này ngay lập tức báo cáo gỡ lỗi chi tiết.
Bước 6: Quan sát báo cáo gỡ lỗi chi tiết
Các 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ả báo cáo phía nguồn và khoá gỡ lỗi 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 cả 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 thông tin chi tiết và hành động cần thực hiện tuỳ thuộc vào từng loại, hãy xem xét tài liệu tham khảo về báo cáo chi tiết trong Phần 3: Gỡ lỗi sổ tay nấu ăn.
Body- Nội dung của báo cáo. Điều này sẽ phụ thuộc vào loại điểm truy cập. Xem lại thông tin chi tiết tài liệu tham khảo về báo cáo trong Phần 3: Gỡ lỗi sổ tay nấu ăn.
Phần 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 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 duy nhất; do đó, có thể tạo một báo cáo chi tiết cho mỗi lỗi và theo từng loại báo cáo (cấp sự kiện hoặc tổng hợp).
- 2 báo cáo chi tiết nếu lỗi ảnh hưởng đến cả cấp sự kiện và tổng hợp
báo cáo—với ngoại lệ: nếu lý do không thành công giống nhau cho cấp sự kiện
và báo cáo tổng hợp, thì chỉ có một báo cáo chi tiết được tạo (ví dụ:
trigger-no-matching-source)