Hiện đã có phiên bản mới của API Báo cáo. Tính năng này riêng tư hơn và có nhiều khả năng được hỗ trợ trên nhiều trình duyệt hơn.
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 cung cấp cho bạn thông tin về 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 thông tin khác.
Hiện đã 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 sẽ đượ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 hãy giữ lại tiêu đề cũ trong một thời gian (Report-To
). Xem nội dung Di chuyển: mã mẫu.
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: hãy 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ả 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ụ thiết bị đầu cuối hoặc đang tự vận hành, hãy chờ đợi nhiều lưu lượng truy cập 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 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 cho tính năng Ghi nhật ký lỗi mạng. Khi 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
Nội dung thay đổi
- Nền tảng API thì 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 này sẽ khác nhau.
Với phiên bản 0, bạn chỉ có thể thiết lập điểm cuối báo cáo trên 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 xung quanh này.
Với v1, bạn cần đặt tiêu đề Reporting-Endpoints
trên mọi phản hồi có thể tạo báo cáo.
- Cả hai API đều hỗ trợ cùng một loại báo cáo, nhưng có một ngoại lệ là phiên bản 1 không hỗ trợ Báo cáo lỗi mạng. Hãy đọc thêm trong các bước di chuyển.
- v0 chưa 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 nội dung 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 do trình duyệt gửi đến điểm cuối vẫn là yêu cầu
POST
củaContent-type
application/reports+json
. - Việc liên kết một số điểm cuối đến 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ả các báo cáo có thể ghi nhận được và có định dạng giống nhau.
Tất cả sự khác biệt giữa v0 và v1
API Báo cáo cũ (v0) tiêu đề Report-To |
API Báo cáo mới (v1) tiêu đề Reporting-Endpoints |
|
---|---|---|
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ó hỗ trợ. Safari không phản đối. Xem tín hiệu của trình duyệt. |
Thiết bị đầu cuối | Gửi báo cáo đến bất kỳ người thu thập báo cáo nào trong số 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 người thu thập báo cáo cụ thể (chỉ một URL được xác định cho mỗi điểm cuối). |
Nền tảng API | Sử dụng tiêu đề `Report-To` để định cấu hình các 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 |
|
Không thay đổi, ngoại trừ tính năng 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 mới (v1). |
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 ảnh hưởng đến các tài liệu (trang) khác trong nguồn gốc đó.
Trường url của báo cáo vẫn thay đổi theo từng tài liệu.
|
Tài liệu. Tiêu đề Reporting-Endpoints của tài liệu chỉ ảnh hưởng đến tài liệu đó.
Trường url của báo cáo vẫn thay đổi theo từng tài liệu.
|
Tách biệt báo cáo (phân lô) | Nhiều tài liệu (trang) hoặc trang web/nguồn gốc tạo báo cáo cùng một lúc và có cùng điểm cuối báo cáo sẽ được nhóm 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. |
|
Hỗ trợ cân bằng tải / mức độ ưu tiên | Có | Không |
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 kỳ vọng 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 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 các 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ố lượng báo cáo sẽ vẫn giữ nguyên, nhưng 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 (v1) mới có một số lợi ích ✅:
- Tín hiệu của trình duyệt tích cực, có nghĩa là phiên bản 1 có thể được hỗ trợ trên nhiều trình duyệt (không giống như phiên bản 0 chỉ được hỗ trợ trong Chrome và Edge).
- API tinh gọn hơn.
- Công cụ đang được phát triển xoay quanh API Báo cáo mới (v1).
Lưu ý như sau:
- 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 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 đối với các lỗi vi phạm Chính sách bảo mật nội dung, hãy xem các bước di chuyển cụ thể để có 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 mới (v1) (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 dùngReport-To
(v0). API Báo cáo phiên bản 1 hiện không hỗ trợ tính năng 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⏤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
(v0) vàReporting-Endpoints
(v1). v0 cung cấp cho bạn tính năng Ghi nhật ký lỗi mạng, còn v1 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 bị mất các báo cáo mà bạn từng nhận được với phiên bản 0.
Bước 1 (làm ngay bây giờ): Sử dụng cả hai tiêu đề:
Report-To
(v0) vàReporting-Endpoints
(v1).Với gói này, bạn sẽ có:
- Báo cáo từ các ứng dụng Chrome và Edge mới hơn nhờ có
Reporting-Endpoints
(v1). - Báo cáo từ các ứng dụng Chrome và Edge cũ hơn nhờ có
Report-To
(v0).
Các phiên bản trình duyệt hỗ trợ
Reporting-Endpoints
sẽ sử dụngReporting-Endpoints
và các phiên bản không hỗ trợReport-To
. Định dạng yêu cầu và báo cáo là giống nhau đối với phiên bản 0 và phiên bản 1.- Báo cáo từ các ứng dụng Chrome và Edge mới hơn nhờ có
Bước 2 (làm ngay): Đảm bảo rằng bạn đã đặt tiêu đề
Reporting-Endpoints
trên tất cả phản hồi có thể tạo báo cáo.Với v0, bạn có thể chọn chỉ thiết lập điểm cuối báo cáo trên một số phản hồi và các tài liệu khác (các trang) trên nguồn gốc đó sẽ sử dụng điểm cuối "môi trường" này. Với v1, do sự khác biệt về phạm vi, bạn cần đặt tiêu đề
Reporting-Endpoints
trên tất 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ập nhật lên phiên bản Chrome hoặc Edge mới hơn (phiên bản 96 trở lên), hãy xoá
Report-To
(v0) và chỉ giữ lạiReporting-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ữ lại
Report-To
cho đến khi triển khai cơ chế mới cho tính năng Ghi nhật ký lỗi mạng.
Xem các ví dụ về mã trong sổ tay nấu ăn di chuyển.
Các bước di chuyển cho tính năng báo cáo CSP
Có 2 cách để định cấu hình báo cáo vi phạm Chính sách bảo mật nội dung:
- Chỉ riêng tiêu đề CSP thông qua lệnh
report-uri
. Trình duyệt này được hỗ trợ trên nhiều trình duyệt, trên Chrome, Firefox, Safari và Edge. Báo cáo được gửi với loại nội dungapplication/csp-report
và có định dạng dành riêng cho CSP. Những 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, hoạt động đó được thực hiện qua tiêu đề
Report-To
(cũ) hoặcReporting-Endpoints
mới hơn (v1). 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 API Báo cáo khác và có cùng loại nội dungapplication/reports+json
.
Phương pháp đầu tiên (chỉ report-uri
) không còn được khuyên dùng và việc sử dụng phương pháp thứ hai có một số lợi ích. Cụ thể, tính năng 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 điểm cuối chung (vì tất cả cá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⏤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 được 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 có report-to
. Trong một trình duyệt chỉ nhận dạng report-uri
, thì chỉ report-uri
sẽ được xem xét.
Bước 1 (làm ngay): Nếu bạn chưa thêm, hãy thêm
report-to
cùng vớireport-uri
. Các trình duyệt chỉ hỗ trợreport-uri
(Firefox) sẽ sử dụngreport-uri
, và các trình duyệt cũng hỗ trợreport-to
(Chrome, Edge) sẽ sử dụngreport-to
. Để chỉ định các điểm cuối được đặt tên mà bạn sẽ sử dụng trongreport-to
, hãy sử dụng cả hai 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 mới hơn và cũ.Bước 3 (bắt đầu sau): Sau khi tất cả hoặc hầu hết người dùng cập nhật lên phiên bản Chrome hoặc Edge mới hơn (phiên bản 96 trở lên), hãy xoá
Report-To
(v0) và chỉ giữ lạiReporting-Endpoints
. Giữ lạireport-uri
để bạn vẫn nhận được báo cáo cho các trình duyệt chỉ hỗ trợ tiện ích đó.
Xem mã ví dụ cho các bước này trong bài viết di chuyển báo cáo CSP.
Di chuyển: mã ví dụ
Tổng quan
Nếu bạn đang sử dụng API Báo cáo cũ (v0) để nhận báo cáo vi phạm đối với 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 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ũ (v0) để nhận báo cáo vi phạm cho CSP
(tiêu đề Content-Security-Policy
), thì bạn có thể phải điều chỉnh Content-Security-Policy
trong quá trình
di chuyển sang API Báo cáo mới (v1).
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 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 của bạn 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ũ (v0)
- Quy cách: API Báo cáo mới (v1)
Hình ảnh chính của Nine Koepfer / @enka80 trên Unsplash, đã chỉnh sửa. Cảm ơn Ian Cllelland, Eiji Kitamura và Milica Mihajlija đã viết rất nhiều bài đánh giá và đề xuất về bài viết này.