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. Tính năng này giúp bảo mật thông tin riêng tư hơn và có nhiều khả năng được hỗ trợ trên nhiều trình duyệt.

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 đó. Điều này mang lại cho bạn biết các biện pháp can thiệp vào 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 nội dung khác.

Đã có phiên bản mới của API Báo cáo. API mới tinh gọn hơn và có nhiều khả năng được hỗ trợ trên nhiều 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 hãy giữ 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 vừa 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 câu trả lờ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ụ thiết bị đầu cuối hoặc đang vận hành dịch vụ của riêng mình, thì bạn sẽ nhận được nhiều lưu lượng truy cập hơn khi sử dụng hoặ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 chi tiết và mã ví dụ nhé!

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

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

• Có 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ông giống nhau.

• Cả hai API đều hỗ trợ cùng một loại báo cáo, với một ngoại lệ: 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 không được và sẽ không được hỗ trợ trên các trình duyệt. v1 có nhiều khả năng được hỗ trợ trên nhiều trình duyệt trong tương lai.

Những nội dung không thay đổi

• Định dạng và cấu trúc của các 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à 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 tiếp tục có quyền truy cập vào tất cả báo cáo có thể ghi nhận được và các báo cáo này có định dạng là .

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 có nhiều lưu lượng truy cập hơn

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ụ, hãy dự kiến sẽ có thêm lưu lượng truy cập đến điểm cuối đó.

Điều này là do các báo cáo không được phân theo lô với 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 chuyển sang API Báo cáo phiên bản 1, số báo cáo sẽ vẫn giữ nguyên, nhưng số lượng yêu cầu gửi đế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 (v1)

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 của trình duyệt tích cực, tức là hỗ trợ trên nhiều trình duyệt có thể được mong đợi đối với phiên bản 1 (không giống như v0 chỉ được hỗ trợ trong Chrome và Cạnh).
• API tinh gọn hơn.
• Chúng tôi đang phát triển công cụ này xoay quanh API Báo cáo mới (phiên bản 1).

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 về các trường hợp 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 làm như sau: hãy sử dụng API Báo cáo mới (phiên bản 1) (tiêu đề Reporting-Endpoints). Có một trường hợp ngoại lệ đối với this: 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 (v0). 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. Cơ chế mới để Ghi nhật ký lỗi mạng sẽ được phát triển⏤cho đến khi có sẵn, hãy sử dụng API Báo cáo phiên bản 0. Nếu bạn cần 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). v0 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 thuộc 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 bị mất báo cáo mà bạn từng tải với phiên bản 0.

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

   Với tính năng này, bạn sẽ 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ũ hơn nhờ Report-To (v0).

   Các phiên bản trình duyệt hỗ trợ Reporting-Endpoints sẽ sử dụng Reporting-Endpoints, và các thực thể không được tạo dự phòng cho Report-To. Yêu cầu và định dạng báo cáo cho v0 và v1.

2. Bước 2 (làm 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ố câu trả lời và các tài liệu khác (các trang) trên nguồn gốc đó sẽ sử dụng "môi trường xung quanh" này điểm cuối. 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 cho tất cả các phản hồi có thể tạo ra .

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 Chrome hoặc Edge sau này cài đặt (96 trở lên), xoá Report-To (v0) và chỉ giữ lại Reporting-Endpoints.

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

Xem ví dụ về mã trong sổ tay hướng dẫn di chuyển.

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

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

• Chỉ riêng tiêu đề CSP thông qua lệnh report-uri. này có hỗ trợ trình duyệt rộng, trên Chrome, Firefox, Safari và Edge. Báo cáo được gửi với 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 CSP cấp 2" và làm không dựa vào API Báo cáo.
• Với API Báo cáo, bạn cần sử dụng tiêu đề Report-To (cũ) hoặc tiêu đề mới hơn Reporting-Endpoints (phiên bản 1). Tính năng này chỉ được hỗ trợ trên 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.

Việc sử dụng phương pháp đầu tiên (chỉ report-uri) không còn được đề xuất và việc sử dụng phương pháp thứ hai sẽ mang lại 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ư đặt một điểm cuối chung (vì tất cả yêu cầu báo cáo được tạo qua API Báo cáo⏤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 duy trì report-uri cùng với phương pháp API Báo cáo (Report-To 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 ra report-uri và report-to, report-uri sẽ bị bỏ qua nếu report-to đang tồn tại. Trong trình duyệt chỉ nhận ra report-uri, thì chỉ report-uri sẽ được xem xét.

1. Bước 1 (làm 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 đã đặt tên, bạn 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 sẽ có được báo cáo từ cả các ứng dụng Chrome và Edge mới hơn lẫn cũ hơn.

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 Chrome hoặc Edge sau này cài đặt (96 trở lên), 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 các trình duyệt chỉ hỗ trợ API này.

Xem ví dụ về mã cho các bước này trong quá trình di chuyển báo cáo CSP.

Di chuyển: mã ví dụ

Tổng quan

Trường hợp bạn đ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 COOP (Cross-Origin-Opener-Policy tiêu đề), 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 phải tự thay đổi các tiêu đề chính sách này khi di chuyển vào API Báo cáo phiên bản 1. Những gì bạn cần là di chuyển từ tiêu đề Report-To cũ sang tiêu đề mới Tiêu đề Reporting-Endpoints.

Trường hợp bạn đ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 phải tinh chỉnh Content-Security-Policy như một phần của 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"

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.

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

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

Hình ảnh chính của Nine Koepfer / @enka80 đang bật Đã chỉnh sửa Unsplash. Cảm ơn Ian Clelland, Eiji Kitamura và Milica Mihajlija đã chia sẻ những bài đánh giá và đề xuất của họ về chủ đề này bài viết.