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

Các 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 đề 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 đề Attribution Reporting

Bạn có thể sử dụng trình xác thực tiêu đề để xác thực các tiêu đề liên quan đến Attribution Reporting API. Bạn có thể theo dõi các lỗi xác thực bắt nguồn từ trình duyệt để hỗ trợ 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 từ điểnAttribution-Reporting-Info, vì vậy, việc cung cấp khoá boolean report-header-errors ngụ ý một giá trị true.

Báo cáo gỡ lỗi được gửi ngay đế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 gồm các đối tượng có dạng sau:

[{
  "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

Bước 1: Đặt cookie gỡ lỗi

Đặt cookie sau 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 sự hiện diện của cookie này trên cả nguồn và quá trình đă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.

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 để 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 đến 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 thành 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.

• Ánh xạ khoá gỡ lỗi phía nguồn với thông tin bổ sung về thời gian nguồn mà bạn cho là có liên quan để gỡ lỗi.
• Ánh xạ 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à có liên quan để gỡ lỗi.

Ví dụ: bạn có thể đặt các khoá gỡ lỗi sau:

• Mã nhận dạng cookie + Dấu thời gian nguồn làm khoá gỡ lỗi nguồn (và ghi lại cùng 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 đ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 của bạn)

Nhờ đó, bạn có thể sử dụng thông tin 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.

Đặ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ã nhận dạng 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 điều kiện 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. 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 các 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, có thêm chuỗi debug 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 hoạt động phân bổ được kích hoạt, trình duyệt sẽ gửi ngay một báo cáo gỡ lỗi bằng cách sử dụng 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à trên một đ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 báo cáo gỡ lỗi có thể 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 rằng hộp đánh dấu Hiện báo cáo gỡ lỗi được đánh dấu 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 Attribution Reporting. 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 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 có thể 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 diện các tệp này trong danh sách bằng đường dẫn debug mà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 nhận được ngay các báo cáo gỡ lỗi thành công nà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 gỡ lỗi thành công có thể 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à tiêu đề 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ạ: trigger header

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 các 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, có thêm 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 không được đăng ký, trình duyệt sẽ gửi ngay một báo cáo gỡ lỗi chi tiết bằng 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à trên một đ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, chỉ có một điểm cuối cho báo cáo chi tiết. Tất cả các báo cáo chi tiết liên quan đến báo cáo cấp sự kiện và báo cáo tổng hợp sẽ được gửi đến cùng một điểm cuối.

Mã minh hoạ: điểm cuối 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ế độ 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ả 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ột lượt phân bổ (chuyển đổi) trên trang web của bạn được thiết lập bằng Attribution Reporting. Vì 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ẽ nhận được một báo cáo gỡ lỗi chi tiết thuộc loại trigger-no-matching-source.
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áo cáo gỡ lỗi chi tiết thuộc loại trigger-no-matching-source đã được tạo.
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 đã 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à 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ề một yêu cầu chứa các 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ỳ 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: Sổ tay 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 tài sản. Xem tài liệu tham khảo về báo cáo chi tiết trong Phần 3: Sổ tay 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 báo cáo cấp sự kiện (hoặc nếu lỗi chỉ ảnh hưởng đến báo cáo có thể tổng hợp). Một nguồn hoặc lỗi đăng ký đ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 có thể 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 có thể 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 có thể 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ổ tay gỡ lỗi