Chuyển sang API Báo cáo phiên bản 1

Đã có phiên bản mới của API Báo cáo. Cookie này riêng tư hơn và có nhiều khả năng được hỗ trợ trên các trình duyệt.

Maud Nalpas

API Báo cáo thông báo cho bạn về những lỗi xảy ra trên trang web của bạn khi khách truy cập sử dụng trang web đó. Công cụ này giúp bạn nắm được thông tin về các biện pháp can thiệp của trình duyệt, sự cố trình duyệt, các trường hợp vi phạm Chính sách bảo mật nội dung, các trường hợp vi phạm COOP/COEP, cảnh báo ngừng sử dụng và nhiều thông tin khác.

Đã có phiên bản mới của API Báo cáo. API mới gọn nhẹ hơn và có nhiều khả năng được hỗ trợ trên các trình duyệt.

Tóm tắt

Nhà phát triển trang web

Nếu bạn đã có chức năng báo cáo cho trang web của mình: hãy di chuyển sang phiên bản 1 bằng cách sử dụng tiêu đề mới (Reporting-Endpoints), nhưng vẫn giữ tiêu đề cũ trong một thời gian (Report-To). Hãy xem phần Di chuyển: mã ví dụ.

Nếu bạn chỉ mới thêm chức năng báo cáo vào trang web của mình: chỉ sử dụng tiêu đề mới (Reporting-Endpoints).

⚠️ Trong cả hai trường hợp, hãy nhớ đặt tiêu đề Reporting-Endpoints cho tất cả các phản hồi có thể tạo báo cáo.

Nhà phát triển dịch vụ báo cáo

Nếu bạn đang duy trì một dịch vụ điểm cuối hoặc đang vận hành dịch vụ của riêng mình, hãy dự kiến lưu lượng truy cập sẽ tăng lên khi bạn hoặc các nhà phát triển bên ngoài di chuyển sang API Báo cáo phiên bản 1 (tiêu đề Reporting-Endpoints).

Hãy đọc tiếp để biết thông tin chi tiết và mã ví dụ!

Ghi nhật ký lỗi mạng

Một cơ chế mới để Ghi nhật ký lỗi mạng sẽ được phát triển. Khi cơ chế đó có sẵn, hãy chuyển từ API Báo cáo phiên bản 0 sang cơ chế mới đó.

Bản minh hoạ và mã

• Trang web minh hoạ: API báo cáo mới (phiên bản 1)
• Mã cho trang web minh hoạ

Sự khác biệt giữa phiên bản 0 và phiên bản 1

Điều gì sẽ thay đổi

• Nền tảng API khác nhau.

 Report-To: { group: "main-endpoint", "max_age": 86400, "endpoints": [ { "url": ... }, { "url": ... }] }, { group: "default-endpoint", "max_age": 86400, "endpoints": [ { "url": ... }, { "url": ... }] }
 Document-Policy: ...; report-to main-endpoint

 Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
 Document-Policy: ...; report-to main-endpoint

• Phạm vi của báo cáo khác nhau.

• Cả hai API đều hỗ trợ các loại báo cáo giống nhau, ngoại trừ một trường hợp: phiên bản 1 không hỗ trợ báo cáo Lỗi mạng. Đọc thêm trong các bước di chuyển.
• v0 hiện không được hỗ trợ và sẽ không được hỗ trợ trên các trình duyệt. v1 có nhiều khả năng sẽ được hỗ trợ trên nhiều trình duyệt trong tương lai.

Những điểm không thay đổi

• Định dạng và cấu trúc của báo cáo không thay đổi.
• Yêu cầu mà trình duyệt gửi đến điểm cuối vẫn là yêu cầu POST của Content-type application/reports+json.
• Việc liên kết một số điểm cuối nhất định với một số loại báo cáo nhất định được hỗ trợ ở cả phiên bản 0 và phiên bản 1.
• Vai trò của điểm cuối default không thay đổi.

• API Báo cáo phiên bản 1 không ảnh hưởng đến ReportingObserver. ReportingObserver vẫn có quyền truy cập vào tất cả các báo cáo có thể quan sát và định dạng của các báo cáo này là giống nhau.

Tất cả điểm khác biệt giữa phiên bản 0 và phiên bản 1

Nhà phát triển điểm cuối: Dự kiến lưu lượng truy cập sẽ tăng

Nếu bạn đã thiết lập máy chủ của riêng mình làm điểm cuối báo cáo hoặc nếu bạn đang phát triển hoặc duy trì một trình thu thập báo cáo dưới dạng dịch vụ, hãy dự kiến sẽ có nhiều lưu lượng truy cập hơn đến điểm cuối đó.

Điều này là do các báo cáo không được xử lý theo lô bằng API Báo cáo phiên bản 1 như API Báo cáo phiên bản 0. Do đó, khi các nhà phát triển ứng dụng bắt đầu di chuyển sang API Báo cáo phiên bản 1, số lượng báo cáo sẽ vẫn tương tự, nhưng số lượng yêu cầu đến máy chủ điểm cuối sẽ tăng lên.

Nhà phát triển ứng dụng: Di chuyển sang Reporting-Endpoints (phiên bản 1)

Bạn nên làm gì?

Việc sử dụng API Báo cáo (phiên bản 1) mới mang lại một số lợi ích ✅:

• Tín hiệu trình duyệt là tích cực, tức là bạn có thể mong đợi sự hỗ trợ trên nhiều trình duyệt cho phiên bản 1 (không giống như phiên bản 0 chỉ được hỗ trợ trong Chrome và Edge).
• API này gọn nhẹ hơn.
• Chúng tôi đang phát triển công cụ dựa trên API Báo cáo (v1) mới.

Lưu ý:

• Nếu trang web của bạn đã sử dụng API Báo cáo phiên bản 0 với tiêu đề Report-To, hãy di chuyển sang API Báo cáo phiên bản 1 (xem các bước di chuyển). Nếu trang web của bạn đã sử dụng chức năng báo cáo cho các lỗi vi phạm Chính sách bảo mật nội dung, hãy kiểm tra các bước di chuyển cụ thể để báo cáo CSP.
• Nếu trang web của bạn chưa sử dụng API Báo cáo và bạn hiện đang thêm chức năng báo cáo: hãy sử dụng API Báo cáo (v1) mới (tiêu đề Reporting-Endpoints). Có một trường hợp ngoại lệ đối với điều này: nếu bạn cần sử dụng tính năng Ghi nhật ký lỗi mạng, hãy dùng Report-To (phiên bản 0). Tính năng Ghi nhật ký lỗi mạng hiện không được hỗ trợ trong API Báo cáo phiên bản 1. Một cơ chế mới để Ghi nhật ký lỗi mạng sẽ được phát triển. Cho đến khi cơ chế đó có sẵn, hãy sử dụng API Báo cáo phiên bản 0. Nếu bạn cần tính năng Ghi nhật ký lỗi mạng cùng với các loại báo cáo khác, hãy sử dụng cả Report-To (phiên bản 0) và Reporting-Endpoints (phiên bản 1). Phiên bản 0 cung cấp cho bạn tính năng Ghi nhật ký lỗi mạng và phiên bản 1 cung cấp cho bạn báo cáo của tất cả các loại khác.

Các bước di chuyển

Mục tiêu của bạn trong quá trình di chuyển này là không mất các báo cáo mà bạn thường nhận được bằng phiên bản 0.

1. Bước 1 (thực hiện ngay): Sử dụng cả hai tiêu đề: Report-To (v0) và Reporting-Endpoints (v1).

   Nhờ đó, bạn sẽ nhận được:

   • Báo cáo từ các ứng dụng Chrome và Edge mới hơn nhờ Reporting-Endpoints (phiên bản 1).
   • Báo cáo từ các ứng dụng Chrome và Edge cũ nhờ Report-To (phiên bản 0).

   Các phiên bản trình duyệt hỗ trợ Reporting-Endpoints sẽ sử dụng Reporting-Endpoints và các phiên bản không hỗ trợ sẽ chuyển về Report-To. Định dạng yêu cầu và báo cáo giống nhau đối với v0 và v1.

2. Bước 2 (thực hiện ngay): Đảm bảo rằng tiêu đề Reporting-Endpoints được đặt trên tất cả các phản hồi có thể tạo báo cáo.

   Với v0, bạn có thể chọn chỉ đặt điểm cuối báo cáo trên một số phản hồi và các tài liệu (trang) khác trên nguồn gốc đó sẽ sử dụng điểm cuối "xung quanh" này. Với phiên bản 1, do sự khác biệt về phạm vi, bạn cần đặt tiêu đề Reporting-Endpoints trên tất cả các phản hồi có thể tạo báo cáo.

3. Bước 3 (bắt đầu sau): Sau khi tất cả hoặc hầu hết người dùng của bạn đã cập nhật lên các bản cài đặt Chrome hoặc Edge mới hơn (96 trở lên), hãy xoá Report-To (v0) và chỉ giữ lại Reporting-Endpoints.

   Một trường hợp ngoại lệ: nếu bạn cần báo cáo Network Error Logging, hãy giữ lại Report-To cho đến khi có cơ chế mới cho Network Error Logging.

Xem các ví dụ về mã trong sổ tay di chuyển.

Các bước di chuyển đối với báo cáo CSP

Có hai cách để định cấu hình báo cáo vi phạm Content-Security-Policy:

• Chỉ với tiêu đề CSP thông qua lệnh report-uri. Tính năng này được hỗ trợ trên nhiều trình duyệt, bao gồm Chrome, Firefox, Safari và Edge. Báo cáo được gửi bằng content-type application/csp-report và có định dạng dành riêng cho CSP. Các báo cáo này được gọi là "Báo cáo CSP cấp 2" và không dựa vào API Báo cáo.
• Với API Báo cáo, đó là thông qua tiêu đề Report-To (cũ) hoặc Reporting-Endpoints (v1) mới hơn. Tính năng này chỉ được hỗ trợ trong Chrome và Edge. Yêu cầu báo cáo có cùng định dạng với các yêu cầu khác của API Báo cáo và cùng loại nội dung application/reports+json.

Không nên sử dụng phương pháp đầu tiên (chỉ report-uri) và phương pháp thứ hai có một số lợi ích. Cụ thể, API này cho phép bạn sử dụng một cách duy nhất để thiết lập báo cáo cho tất cả các loại báo cáo cũng như thiết lập một điểm cuối chung (vì tất cả các yêu cầu báo cáo được tạo thông qua Reporting API⏤CSP và các yêu cầu khác⏤đều có cùng định dạng application/reports+json.

Tuy nhiên, chỉ một số trình duyệt hỗ trợ report-to. Do đó, bạn nên giữ report-uri cùng với phương pháp API Báo cáo (Report-To hoặc tốt hơn, Reporting-Endpoints) để nhận báo cáo vi phạm CSP từ nhiều trình duyệt. Trong một trình duyệt nhận dạng report-uri và report-to, report-uri sẽ bị bỏ qua nếu report-to xuất hiện. Trong trình duyệt chỉ nhận dạng report-uri, chỉ report-uri mới được xem xét.

1. Bước 1 (thực hiện ngay): Nếu bạn chưa thêm, hãy thêm report-to cùng với report-uri. Những trình duyệt chỉ hỗ trợ report-uri (Firefox) sẽ dùng report-uri, còn những trình duyệt cũng hỗ trợ report-to(Chrome, Edge) sẽ dùng report-to. Để chỉ định các điểm cuối có tên mà bạn sẽ sử dụng trong report-to, hãy sử dụng cả tiêu đề Report-To và Reporting-Endpoints. Điều này đảm bảo rằng bạn nhận được báo cáo từ cả các ứng dụng Chrome và Edge cũ cũng như mới.

2. Bước 3 (bắt đầu sau): Sau khi tất cả hoặc hầu hết người dùng của bạn đã cập nhật lên các bản cài đặt Chrome hoặc Edge mới hơn (96 trở lên), hãy xoá Report-To (v0) và chỉ giữ lại Reporting-Endpoints. Giữ lại report-uri để bạn vẫn nhận được báo cáo cho những trình duyệt chỉ hỗ trợ thuộc tính này.

Xem ví dụ về mã cho các bước này trong phần Di chuyển báo cáo CSP.

Di chuyển: mã ví dụ

Tổng quan

Nếu đang sử dụng API Báo cáo (v0) cũ để nhận báo cáo vi phạm cho COOP (tiêu đề Cross-Origin-Opener-Policy), COEP (Cross-Origin-Embedder-Policy) hoặc chính sách tài liệu (tiêu đề Document-Policy): bạn không cần thay đổi chính các tiêu đề chính sách này khi di chuyển sang API Báo cáo phiên bản 1. Bạn cần di chuyển từ tiêu đề Report-To cũ sang tiêu đề Reporting-Endpoints mới.

Nếu đang sử dụng API Báo cáo cũ (phiên bản 0) để nhận báo cáo vi phạm cho CSP (tiêu đề Content-Security-Policy), bạn có thể cần điều chỉnh Content-Security-Policy trong quá trình di chuyển sang API Báo cáo mới (phiên bản 1).

Di chuyển cơ bản

Report-To: { group: "main-endpoint", "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "endpoints": [ { "url": "https://reports.example/default" }] }

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
Report-To: { group: "main-endpoint", "max_age": 86400, "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "max_age": 86400, "endpoints": [ { "url": "https://reports.example/default" }] }

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"

Xin lưu ý rằng với phiên bản 1, bạn vẫn có thể gửi các loại báo cáo cụ thể đến các điểm cuối cụ thể. Nhưng bạn chỉ có thể có một URL cho mỗi điểm cuối.

Theo dõi tất cả các trang

app.get("/", (request, response) => {
  response.set("Report-To", …)
  response.render(...)
});
app.get("/page1", (request, response) => {
  response.render(...)
});

// Use a middleware to set the reporting endpoint(s) for *all* requests.
app.use(function(request, response, next) {
  response.set("Reporting-Endpoints", …);
  next();
});

app.get("/", (request, response) => {
  response.render(...)
});

app.get("/page1", (request, response) => {
  response.render(...)
});

Di chuyển báo cáo CSP

Content-Security-Policy: ...; report-uri https://reports.example/main

Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Report-To: main-endpoint="https://reports.example/main"

Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Reporting-Endpoints: main-endpoint="https://reports.example/main"
Report-To: ...

Tài liệu đọc thêm

• Giám sát ứng dụng web bằng API Báo cáo (bài đăng chính về API Báo cáo)
• Quy cách: API Báo cáo cũ (phiên bản 0)
• Quy cách: API Báo cáo mới (phiên bản 1)

Xin chân thành cảm ơn Ian Clelland, Eiji Kitamura và Milica Mihajlija vì đã xem xét và đưa ra đề xuất cho bài viết này.