Thiết lập báo cáo gỡ lỗi cho Báo cáo phân bổ

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ữ

  • 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.

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
  }
}]
Ảnh chụp màn hình: công cụ xác thực tiêu đề

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.

Mã minh hoạ: gỡ lỗi cookie

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

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-internals trong 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 debug màu xanh dương.
Ảnh chụp màn hình: Nội dung phân bổ
  • 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.
Ảnh chụp màn hình: báo cáo nhật ký máy chủ nguồn

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 đề nguồn

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.

  1. Mở chrome://attribution-internals trong trình duyệt.
  2. 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.
  3. 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ại trigger-no-matching-source.
  4. 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)

Tiếp theo

Phần 3: Sách dạy nấu ăn về gỡ lỗi