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. Phương thức này mang lại sự riêng tư hơn và có nhiều khả năng được hỗ trợ trên các trình duyệt hơn.

Maud Nalpas

API Báo cáo thông báo cho bạn về các 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 cho bạn biết về các biện pháp can thiệp của trình duyệt, sự cố trình duyệt, lỗi vi phạm Chính sách bảo mật nội dung, lỗi vi phạm COOP/COEP, cảnh báo về việc 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 hơn.

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ữ lại tiêu đề cũ trong một khoảng thời gian (Report-To). Hãy xem phần Di chuyển: mã ví dụ.

Nếu bạn đang 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 trên 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 nhiều hơn khi bạn hoặc các nhà phát triển bên ngoài 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

Chúng tôi sẽ phát triển một cơ chế mới để Ghi nhật ký lỗi mạng. Khi cơ chế mới đó ra mắt, 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.

 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ùng một loại báo cáo, ngoại trừ một ngoại lệ: phiên bản 1 không hỗ trợ báo cáo Lỗi mạng. Hãy đọc thêm trong phần các bước di chuyển.
• Phiên bản 0 không được và sẽ không được hỗ trợ trên các trình duyệt. Phiên bản 1 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ợ trong cả phiên bản 0 và 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 tiếp tục có quyền truy cập vào tất cả báo cáo có thể quan sát và định dạng của các báo cáo này giống hệt nhau.

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

Nhà phát triển thiết bị đầu 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ì trình thu thập báo cáo dưới dạng dịch vụ, thì hãy dự kiến lưu lượng truy cập nhiều hơn đến điểm cuối đó.

Nguyên nhân là do các báo cáo không được phân lô bằng API Báo cáo phiên bản 1 như với API Báo cáo phiên bản 0. Do đó, khi 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 khối 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 mới (phiên bản 1) mang lại một số lợi ích ✅:

• Tín hiệu trình duyệt là dương, nghĩa là bạn có thể mong đợi tính năng 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 gọn nhẹ hơn.
• Chúng tôi đang phát triển các công cụ dựa trên API Báo cáo mới (phiên bản 1).

Do đó, hãy lưu ý:

• Nếu trang web của bạn đã sử dụng Reporting API phiên bản 0 với tiêu đề Report-To, hãy di chuyển sang Reporting API 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 đang thêm chức năng báo cáo: hãy sử dụng API Báo cáo mới (phiên bản 1) (tiêu đề Reporting-Endpoints). Có một ngoại lệ cho đ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 sử 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. Chúng tôi sẽ phát triển một cơ chế mới để Ghi nhật ký lỗi mạng⏤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 về 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 từ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 (phiên bản 0) và Reporting-Endpoints (phiên bản 1).

   Khi sử dụng tính năng này, 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 thực thể trình duyệt hỗ trợ Reporting-Endpoints sẽ sử dụng Reporting-Endpoints và các thực thể không hỗ trợ sẽ chuyển sang Report-To. Định dạng yêu cầu và báo cáo giống nhau đối với phiên bản 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 phiên bản 0, 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 "toàn cảnh" 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 này): Sau khi tất cả hoặc hầu hết người dùng đã 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 (phiên bản 0) và chỉ giữ lại Reporting-Endpoints.

   Một ngoại lệ: nếu bạn cần báo cáo Ghi lỗi mạng, hãy giữ Report-To cho đến khi có cơ chế mới cho tính năng Ghi lỗi mạng.

Xem các ví dụ về mã trong cuốn sách nấu ăn về di chuyển.

Các bước di chuyển để 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ỉ có tiêu đề CSP thông qua lệnh report-uri. API này có hỗ trợ nhiều trình duyệt, bao gồm Chrome, Firefox, Safari và Edge. Báo cáo được gửi bằng loại nội dung 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 cấp 2 của CSP" 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 (phiên bản 1) 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.

Bạn không nên sử dụng phương pháp đầu tiên (chỉ report-uri) và có một số lợi ích khi sử dụng phương pháp thứ hai. 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 là Reporting-Endpoints) để nhận báo cáo vi phạm CSP từ nhiều trình duyệt. Trong trình duyệt nhận dạng report-uri và report-to, report-uri sẽ bị bỏ qua nếu có report-to. 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. Các trình duyệt chỉ hỗ trợ report-uri (Firefox) sẽ sử dụng report-uri và các trình duyệt cũng hỗ trợ report-to(Chrome, Edge) sẽ sử dụng report-to. Để chỉ định các điểm cuối được đặt 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ả ứng dụng Chrome và Edge cũ lẫn mới.

2. Bước 3 (bắt đầu sau này): Sau khi tất cả hoặc hầu hết người dùng đã 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 (phiên bản 0) 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ợ report-uri.

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 cũ (phiên bản 0) để nhận báo cáo vi phạm về một chính sách về sự hợp tác (tiêu đề Cross-Origin-Opener-Policy), chính sách về quyền riêng tư (tiêu đề Cross-Origin-Embedder-Policy) hoặc chính sách về tài liệu (tiêu đề Document-Policy), thì bạn không cần tự thay đổi 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 một 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ể. Tuy nhiên, bạn chỉ có thể có một URL cho mỗi điểm cuối.

Quan sát 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

• Theo dõi ứng dụng web bằng API Báo cáo (bài đăng chính về API Báo cáo)
• Thông số kỹ thuật: API Báo cáo cũ (phiên bản 0)
• Thông số kỹ thuật: API Báo cáo mới (phiên bản 1)

Xin cảm ơn Ian Clelland, Eiji Kitamura và Milica Mihajlija đã xem xét và đề xuất về bài viết này.