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

Thận trọng: Nếu bạn sử dụng Ghi nhật ký lỗi mạng, hãy tiếp tục sử dụng Report-To (v0) vì tính năng Ghi nhật ký lỗi mạng không được hỗ trợ trong API Báo cáo v1.

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.

v0 (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

{0 sử dụng tiêu đề Report-To để định cấu hình các nhóm điểm cuối được đặt tên và chỉ thị report-to trong các tiêu đề khác để tham chiếu đến các nhóm điểm cuối này.

v1 (mới)

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

v1 sử dụng tiêu đề Reporting-Endpoints để định cấu hình các điểm cuối được đặt tên. Giống như v0, phiên bản này sử dụng chỉ thị report-to trong các tiêu đề khác để tham chiếu đến các nhóm điểm cuối này.

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

v0 (cũ)

Với phiên bản 0, bạn chỉ có thể đặt điểm cuối báo cáo cho một số phản hồi. Các tài liệu (trang) khác trên nguồn gốc đó sẽ tự động sử dụng các điểm cuối môi trường này.

v1 (mới)

Với phiên bản 1, 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.

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

	Legacy Reporting API (v0) `Report-To` tiêu đề	API Báo cáo (v1) mới `Reporting-Endpoints` tiêu đề
Hỗ trợ trình duyệt	Chrome 69 trở lên và Edge 69 trở lên.	Chrome 96 trở lên và Edge 96 trở lên. Firefox cũng được hỗ trợ. Safari không phản đối. Xem tín hiệu trình duyệt.
Điểm cuối	Gửi báo cáo đến nhiều trình thu thập báo cáo (nhiều URL được xác định cho mỗi nhóm điểm cuối).	Gửi báo cáo đến các trình thu thập báo cáo cụ thể (chỉ xác định một URL cho mỗi điểm cuối).
Nền tảng API	Sử dụng tiêu đề `Report-To` để định cấu hình nhóm điểm cuối được đặt tên.	Sử dụng tiêu đề `Reporting-Endpoints` để định cấu hình điểm cuối được đặt tên.
Các loại báo cáo có thể được tạo thông qua API này	Ngừng sử dụng Can thiệp Sự cố COOP/COEP Chính sách bảo mật nội dung cấp 3 (CSP cấp 3) Ghi nhật ký lỗi mạng (NEL) _{Tìm hiểu thêm về các loại báo cáo trong bài đăng về API Báo cáo.}	Không thay đổi, ngoại trừ Ghi nhật ký lỗi mạng (NEL): tính năng này không được hỗ trợ trong API Báo cáo (v1) mới.
Phạm vi báo cáo	Nguồn gốc từ bạn. Tiêu đề `Report-To` của một tài liệu sẽ ảnh hưởng đến các tài liệu (trang) khác từ nguồn đó. Trường `url` của báo cáo vẫn khác nhau theo từng tài liệu.	Tài liệu. Tiêu đề `Reporting-Endpoints` của một tài liệu chỉ ảnh hưởng đến tài liệu đó. Trường `url` của báo cáo vẫn khác nhau theo từng tài liệu.
Phân tách báo cáo (theo lô)	Các tài liệu (trang) hoặc trang web/nguồn gốc khác nhau tạo báo cáo trong cùng một thời điểm và có cùng điểm cuối báo cáo sẽ được gộp lại với nhau: chúng sẽ được gửi trong cùng một thông báo đến điểm cuối báo cáo.	Báo cáo từ các tài liệu (trang) khác nhau sẽ không bao giờ được gửi cùng nhau. Ngay cả khi hai tài liệu (trang) từ cùng một nguồn gốc tạo báo cáo cùng lúc, cho cùng một điểm cuối, thì các báo cáo này sẽ không được xử lý theo lô. Đây là một cơ chế giúp giảm thiểu các cuộc tấn công xâm phạm quyền riêng tư. Bạn có thể gửi cùng lúc các báo cáo từ cùng một tài liệu (trang).
Hỗ trợ cân bằng tải / mức độ ưu tiên	Có	Không

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.

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

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

Mã cũ (có v0)

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

Mã mới (mã chuyển đổi có v0 cùng với v1)

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" }] }

Nếu trang web của bạn đã có chức năng báo cáo, hãy chỉ tạm thời giữ lại Report-To (cho đến khi hầu hết các ứng dụng Chrome và Edge đã được cập nhật) để tránh mất báo cáo.

Nếu bạn cần tính năng Ghi nhật ký lỗi mạng, hãy giữ Report-To cho đến khi có tính năng thay thế Ghi nhật ký lỗi mạng.

Mã mới (chỉ có ở phiên bản 1)

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

Đây là giao diện mã của bạn trong tương lai, sau khi hầu hết các ứng dụng Chrome và Edge đã được cập nhật và hỗ trợ API phiên bản 1.

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

Mã cũ (có v0), ví dụ: với Express

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

Với phiên bản 0, bạn chỉ có thể đặt điểm cuối báo cáo cho một số phản hồi. Các tài liệu (trang) khác trên nguồn gốc đó sẽ tự động sử dụng các điểm cuối môi trường này. Ở đây, các điểm cuối được đặt cho "/" được dùng cho tất cả các phản hồi, chẳng hạn như cho page1.

Mã mới (có phiên bản 1), ví dụ: với Express

// 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(...)
});

Với phiên bản 1, 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.

Di chuyển báo cáo CSP

Mã cũ, chỉ có report-uri

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

Không còn được khuyến khích chỉ sử dụng report-uri. Nếu mã của bạn có dạng như trên, hãy di chuyển. Hãy xem Các ví dụ về mã mới bên dưới (màu xanh lục).

Cải thiện mã cũ bằng report-uri và chỉ thị report-to với tiêu đề Report-To (v0)

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

Đây là lựa chọn tốt hơn: mã này sử dụng report-to, một lựa chọn thay thế mới hơn cho report-uri. Nó vẫn giữ report-uri để đảm bảo khả năng tương thích ngược; một số trình duyệt không hỗ trợ report-to nhưng có hỗ trợ report-uri.

Tuy nhiên, điều này có thể tốt hơn: mã này sử dụng API Báo cáo v0 (tiêu đề Report-To). Di chuyển sang phiên bản 1: xem các ví dụ về "Mã mới" bên dưới (màu xanh lục).

Mã mới, có report-uri và chỉ thị report-to với tiêu đề Reporting-Endpoints (v1)

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

Giữ chỉ thị report-uri cùng với chỉ thị report-to cho đến khi chỉ thị report-to được hỗ trợ trên các trình duyệt. Xem bảng khả năng tương thích của trình duyệt.

Tạm thời giữ Report-To bên cạnh Reporting-Endpoints. Sau khi hầu hết khách truy cập Chrome và Edge nâng cấp lên phiên bản trình duyệt 96 trở lên, hãy xoá 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.