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 chú giải thuật ngữ
- Nguồn gốc báo cáo là nguồn gốc [đặt tiêu đề nguồn cho Báo cáo phân bổ và trình kích hoạt.
Tất cả báo cáo do trình duyệt tạo đều được gửi đến nguồn gốc này. Trong hướng dẫn này, chúng tôi dùng
https://adtech.examplelàm ví dụ về nguồn gốc báo cáo. - 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ề sự kiện nguồn hoặc đ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ó sự cố nào đó đ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 đ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 thiết lập 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 quá trình tạo báo cáo phân bổ thành công. Chúng có liên quan trực tiếp đến báo cáo phân bổ. Kể từ Chrome 101 (tháng 4 năm 2022), chúng tôi đã cung cấp báo cáo gỡ lỗi thành công.
- Báo cáo gỡ lỗi chi tiết có thể theo dõi báo cáo bị thiếu và giúp bạn xác định lý do
báo cáo bị thiếu. Chúng cho biết các trường hợp mà 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 trường
typemô tả lý do không tạo được sự kiện nguồn, sự kiệ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 đã có trên Chrome 109 (Chính thức 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 xuyên suốt tài liệu của chúng tôi, hãy tham khảo Bảng thuật ngữ về 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 kho lưu trữ hỗ trợ dành cho 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 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 mã của bạn có bị kiểm soát khi phát hiện tính năng hay không. Để đảm bảo API không bị Chính sách về quyền 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 (đúng), thì API sẽ được phép trong ngữ cảnh (trang) mà quy trình kiểm tra đang chạy.
(Không bắt buộc trong giai đoạn kiểm thử: Kiểm tra để chắc chắn rằng bạn đã đặt Permissions-Policy)
Khắc phục các vấn đề về tích hợp cơ bản
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ình trạng mất dữ liệu trên quy mô lớn, nhưng một số vấn đề tích hợp có thể được phát hiện cục bộ. Các vấn đề về cấu hình sai của tiêu đề nguồn và điều kiện kích hoạt, vấn đề về 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 đề DevTools.
Vấn đề về Công cụ cho nhà phát triển có thể thuộc nhiều loại. Nếu bạn gặp vấn đề invalid header, hãy sao chép tiêu đề vào công cụ trình xác thực tiêu đề. Việc 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 đây 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ả hoạt động đăng ký nguồn và đ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 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 sẽ bị tắt để hỗ trợ 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 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 nhằm cung cấp 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à số nguyên 64 bit chưa ký có định dạng là 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 bổ sung tại thời điểm nguồn mà bạn cho là phù hợp để 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 cho 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à thu thập cùng dấu thời gian đó trong hệ thống dựa trên cookie của bạn)
- 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 dấu thời gian đó trong hệ thống dựa trên cookie)
Nhờ vậy, bạn có thể sử dụng thông tin về lượt chuyển đổi dựa trên cookie để tra cứu các 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.
Hãy 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ạ: 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ã ví dụ trong phần này tạo ra các 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. Các 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 một đ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ự với điểm cuối phân bổ chính, có thêm một chuỗi debug trong đường dẫn:
- Điểm cuối của 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 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 tổng hợp:
Khi một mô hình 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 thông qua yêu cầu POST đến điểm cuối này. Mã máy chủ để 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 trên đ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 của 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 Show Debug Reports (Hiển thị báo cáo gỡ lỗi), trong cả thẻ Báo cáo cấp sự kiện và thẻ Aggregatable Reports (Báo cáo tổng hợp).
- Mở các trang web mà bạn đã triển khai Báo cáo phân bổ. Hoàn thành các bước bạn thực hiện để tạo báo cáo phân bổ; các bước tương tự sẽ tạo báo cáo gỡ lỗi thành công.
- Trong
chrome://attribution-internals:- Kiểm tra để đảm bảo rằng 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 báo cáo gỡ lỗi thành công cũng được tạo. Nhận diện các trình xử lý 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 ngay lập tức nhận được 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 hệt 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 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 một điểm cuối để thu thập các 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ự với điểm cuối phân bổ chính, có thêm một chuỗi debug/verbose 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 chưa đượ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ủ để xử lý các báo cáo gỡ lỗi chi tiết đến có thể có dạng như sau (ở đây trên đ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 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. 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ì đ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 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ột lượt 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 khi xảy ra lượt chuyển đổi này, nên hệ thống sẽ tạo báo cáo gỡ lỗi chi tiết thuộc loại
trigger-no-matching-source. - Trong
chrome://attribution-internals, hãy mở thẻ Báo cáo gỡ lỗi chi tiết và kiểm tra xem báo cáo gỡ lỗi chi tiết thuộc loạitrigger-no-matching-sourceđã được tạo hay chưa. - Trên máy chủ, hãy xác minh rằng điểm cuối của bạn đã nhận được ngay 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à khoá gỡ lỗi phía điều kiện kích hoạt (nếu có nguồn trùng khớp cho điều kiện kích hoạt). Các báo cáo gỡ lỗi chi tiết được tạo tại thời gian nguồn sẽ 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- Nguyên nhân tạo ra báo cá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ỳ thuộc vào 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: Gỡ lỗi sách dạy nấu ăn.
Body- Nội dung của báo cáo. Dữ liệu này sẽ phụ thuộc vào loại. Xem lại 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.
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; do đó, có thể tạo một báo cáo chi tiết cho mỗi lỗi và cho 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 lệ: nếu lý do lỗi là giống nhau đối với các 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)