Sử dụng API Báo cáo để giám sát các lỗi vi phạm bảo mật, các lệnh gọi API không dùng nữa, v.v.
Một số lỗi chỉ xảy ra trong phiên bản chính thức. Bạn sẽ không thấy các quảng cáo này tại địa phương hoặc trong khoảng thời gian vì người dùng thực, mạng thực và thiết bị thực thay đổi trò chơi. API Báo cáo giúp phát hiện một số lỗi trong số này, chẳng hạn như do lỗi vi phạm bảo mật hoặc API không được dùng nữa và sắp bị ngừng sử dụng trên trang web của bạn và truyền chúng đến điểm cuối mà bạn đã chỉ định.
Thẻ này cho phép bạn khai báo thông tin bạn muốn giám sát qua tiêu đề HTTP và được trình duyệt vận hành.
Việc thiết lập API Báo cáo giúp bạn yên tâm rằng khi người dùng trải nghiệm các loại lỗi này, bạn sẽ biết để có thể khắc phục.
Bài đăng này đề cập đến những việc API này có thể làm và cách sử dụng. Chúng ta hãy cùng tìm hiểu kỹ hơn nhé!
Bản minh hoạ và mã
Xem cách hoạt động của API Báo cáo kể từ Chrome 96 trở lên (Chrome Beta hoặc Canary, kể từ tháng 10 năm 2021).
Tổng quan
![Sơ đồ tóm tắt các bước dưới đây, từ khi tạo báo cáo đến khi nhà phát triển truy cập vào báo cáo](https://developer.chrome.com/static/docs/capabilities/web-apis/reporting-api/image/diagram-summarizing-step-7115c265c2e02.png?authuser=19&hl=vi)
Giả sử trang web của bạn, site.example
, có Chính sách bảo mật nội dung và Chính sách tài liệu. Bạn không biết những tính năng này có tác dụng gì? Không sao, bạn vẫn sẽ
đều hiểu được ví dụ này.
Bạn quyết định giám sát trang web của mình để biết khi nào các chính sách này bị vi phạm, mà còn vì bạn muốn chú ý đến các API không dùng nữa hoặc sắp bị ngừng sử dụng mà cơ sở mã của bạn có thể đang sử dụng.
Để thực hiện việc này, hãy định cấu hình tiêu đề Reporting-Endpoints
và ánh xạ các điểm cuối này
tên thông qua lệnh report-to
trong chính sách của bạn nếu cần.
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
# Content-Security-Policy violations and Document-Policy violations
# will be sent to main-endpoint
Content-Security-Policy: script-src 'self'; object-src 'none'; report-to main-endpoint;
Document-Policy: document-write=?0; report-to=main-endpoint;
# Deprecation reports don't need an explicit endpoint because
# these reports are always sent to the `default` endpoint
Điều gì đó không mong muốn sẽ xảy ra và các chính sách này bị vi phạm đối với một số người dùng.
Ví dụ về trường hợp vi phạm
index.html
<script src="script.js"></script>
<!-- CSP VIOLATION: Try to load a script that's forbidden as per the Content-Security-Policy -->
<script src="https://example.com/script.js"></script>
script.js
, do index.html
tải
// DOCUMENT-POLICY VIOLATION: Attempt to use document.write despite the document policy
try {
document.write('<h1>hi</h1>');
} catch (e) {
console.log(e);
}
// DEPRECATION: Call a deprecated API
const webkitStorageInfo = window.webkitStorageInfo;
Trình duyệt tạo báo cáo vi phạm CSP, báo cáo vi phạm Chính sách tài liệu và Ngừng sử dụng báo cáo ghi lại các vấn đề này.
Với độ trễ ngắn (tối đa một phút), trình duyệt sẽ gửi báo cáo đến điểm cuối được định cấu hình cho loại lỗi vi phạm này. Báo cáo được gửi ngoài băng tần của trình duyệt (không phải do máy chủ hay trang web của bạn).
(Các) thiết bị đầu cuối sẽ nhận được(các) báo cáo này.
Giờ đây, bạn có thể truy cập báo cáo về các điểm cuối này và theo dõi lỗi. Bạn có thể bắt đầu khắc phục sự cố đang ảnh hưởng đến người dùng.
Báo cáo mẫu
{
"age": 2,
"body": {
"blockedURL": "https://site2.example/script.js",
"disposition": "enforce",
"documentURL": "https://site.example",
"effectiveDirective": "script-src-elem",
"originalPolicy": "script-src 'self'; object-src 'none'; report-to main-endpoint;",
"referrer": "https://site.example",
"sample": "",
"statusCode": 200
},
"type": "csp-violation",
"url": "https://site.example",
"user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
}
Trường hợp sử dụng và loại báo cáo
API Báo cáo có thể được định cấu hình để giúp bạn theo dõi nhiều loại cảnh báo hoặc vấn đề thú vị xảy ra xuyên suốt trang web của bạn:
Loại báo cáo | Ví dụ về một tình huống trong đó báo cáo sẽ được tạo |
---|---|
Vi phạm CSP (Chỉ cấp 3) | Bạn đã thiết lập Content-Security-Policy (CSP) trên một trong các trang của mình, nhưng trang đó đang cố tải một tập lệnh mà CSP của bạn không cho phép. |
Lỗi vi phạm COOP | Bạn đã đặt Cross-Origin-Opener-Policy trên một trang, nhưng một cửa sổ nhiều nguồn gốc đang cố tương tác trực tiếp với tài liệu. |
Vi phạm COEP | Bạn đã đặt Cross-Origin-Embedder-Policy trên một trang, nhưng tài liệu chứa iframe trên nhiều nguồn gốc nhưng chưa chọn tải bằng các tài liệu nhiều nguồn gốc. |
Vi phạm chính sách của tài liệu | Trang có chính sách tài liệu ngăn việc sử dụng document.write , nhưng một tập lệnh cố gắng gọi document.write . |
Lỗi vi phạm Chính sách về quyền | Trang này có chính sách quyền ngăn chặn việc sử dụng micrô và một tập lệnh yêu cầu đầu vào âm thanh. |
Cảnh báo về việc ngừng sử dụng | Trang đang sử dụng một API không được dùng nữa hoặc sẽ không được dùng nữa; nó gọi trực tiếp hoặc thông qua tập lệnh cấp cao nhất của bên thứ ba. |
Can thiệp | Trang đang cố gắng thực hiện một thao tác nào đó mà trình duyệt quyết định không tuân thủ, vì lý do bảo mật, hiệu suất hoặc trải nghiệm người dùng. Ví dụ trong Chrome: trang sử dụng document.write trên mạng chậm hoặc gọi navigator.vibrate trong một khung trên nhiều nguồn gốc mà người dùng chưa tương tác. |
Sự cố | Trình duyệt gặp sự cố khi trang web của bạn đang mở. |
Báo cáo
Báo cáo trông như thế nào?
Trình duyệt sẽ gửi báo cáo đến điểm cuối mà bạn đã định cấu hình. Thao tác này sẽ gửi các yêu cầu có dạng như sau:
POST
Content-Type: application/reports+json
Tải trọng của các yêu cầu này là một danh sách các báo cáo.
Danh sách ví dụ về báo cáo
[
{
"age": 420,
"body": {
"columnNumber": 12,
"disposition": "enforce",
"lineNumber": 11,
"message": "Document policy violation: document-write is not allowed in this document.",
"policyId": "document-write",
"sourceFile": "https://site.example/script.js"
},
"type": "document-policy-violation",
"url": "https://site.example/",
"user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
},
{
"age": 510,
"body": {
"blockedURL": "https://site.example/img.jpg",
"destination": "image",
"disposition": "enforce",
"type": "corp"
},
"type": "coep",
"url": "https://dummy.example/",
"user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
}
]
Dưới đây là dữ liệu bạn có thể tìm thấy trong mỗi báo cáo này:
Trường | Mô tả |
---|---|
age |
Số mili giây giữa dấu thời gian của báo cáo và thời gian hiện tại. |
body |
Dữ liệu báo cáo thực tế được chuyển đổi tuần tự thành một chuỗi JSON. Các trường có trong body của một báo cáo là do type của báo cáo xác định. ⚠️ Báo cáo thuộc nhiều loại có nội dung khác nhau.
Để xem nội dung chính xác của từng loại báo cáo, hãy tham khảo điểm cuối báo cáo minh hoạ và làm theo hướng dẫn để tạo báo cáo mẫu. |
type |
Một loại báo cáo, ví dụ: csp-violation hoặc coep . |
url |
Địa chỉ của tài liệu hoặc trình thực thi mà báo cáo được tạo. Dữ liệu nhạy cảm như tên người dùng, mật khẩu và mảnh sẽ bị xoá khỏi URL này. |
user_agent |
Tiêu đề User-Agent của yêu cầu mà báo cáo được tạo. |
Báo cáo đã xác thực
Các điểm cuối báo cáo có cùng nguồn gốc với trang tạo báo cáo sẽ nhận được thông tin xác thực (cookie) trong các yêu cầu chứa báo cáo.
Thông tin đăng nhập có thể cung cấp bối cảnh bổ sung hữu ích về báo cáo; với ví dụ: liệu tài khoản của một người dùng nhất định có kích hoạt lỗi một cách liên tục hay không hoặc một trình tự nhất định hành động được thực hiện trên các trang khác đang kích hoạt báo cáo trên trang này.
Trình duyệt gửi báo cáo khi nào và bằng cách nào?
Báo cáo được gửi ngoài băng tần từ trang web của bạn: trình duyệt kiểm soát thời điểm chúng sẽ được gửi đến(các) điểm cuối đã định cấu hình. Cũng không có cách nào để kiểm soát thời điểm trình duyệt gửi báo cáo; thiết bị này sẽ chụp, xếp hàng và gửi tự động tại thời gian phù hợp.
Điều này có nghĩa là hầu như không phải lo lắng về hiệu suất khi sử dụng API Báo cáo.
Việc gửi báo cáo có độ trễ (tối đa một phút) nhằm tăng khả năng gửi báo cáo hàng loạt. Điều này giúp tiết kiệm băng thông để tôn trọng kết nối mạng của người dùng, đặc biệt rất quan trọng trên thiết bị di động. Trình duyệt cũng có thể trì hoãn việc phân phối nếu đang bận xử lý mức độ ưu tiên cao hơn hoặc người dùng có đang sử dụng mạng chậm và/hoặc bị nghẽn tại thời điểm đó hay không.
Vấn đề của bên thứ ba và bên thứ nhất
Hệ thống sẽ gửi các báo cáo được tạo do lỗi vi phạm hoặc do việc ngừng sử dụng diễn ra trên trang của bạn với(các) điểm cuối mà bạn đã định cấu hình. Điều này bao gồm các vi phạm do tập lệnh bên thứ ba gây ra đang chạy trên trang của bạn.
Lỗi vi phạm hoặc ngừng sử dụng xảy ra trong một iframe trên nhiều nguồn gốc được nhúng trong trang của bạn sẽ không được báo cáo cho(các) điểm cuối của bạn (ít nhất là theo mặc định). iframe có thể thiết lập các iframe riêng báo cáo và thậm chí báo cáo cho trang web của bạn (tức là dịch vụ báo cáo của bên thứ nhất); nhưng đã rồi vào trang web được đóng khung. Ngoài ra, xin lưu ý rằng hầu hết các báo cáo chỉ được tạo nếu chính sách của trang bị vi phạm, và chính sách của trang khác với chính sách của iframe.
Ví dụ về việc ngừng sử dụng
![Nếu bạn thiết lập tiêu đề Reporting-Endpoints trên trang: API không dùng nữa do các tập lệnh bên thứ ba đang chạy trên trang gọi, thì API này sẽ được báo cáo đến điểm cuối. API không dùng nữa do iframe được nhúng trong trang của bạn gọi sẽ không được báo cáo cho điểm cuối. Báo cáo về việc ngừng sử dụng sẽ chỉ được tạo nếu máy chủ iframe đã thiết lập Điểm cuối báo cáo, đồng thời báo cáo này sẽ được gửi đến bất kỳ điểm cuối nào mà máy chủ của iframe đã thiết lập.](https://developer.chrome.com/static/docs/capabilities/web-apis/reporting-api/image/if-reporting-endpoints-h-c4facaee3ba26.png?authuser=19&hl=vi)
Hỗ trợ trình duyệt
Bảng dưới đây tóm tắt tính năng hỗ trợ trình duyệt dành cho API Báo cáo phiên bản 1, cùng với
Tiêu đề Reporting-Endpoints
. Trình duyệt hỗ trợ API Báo cáo phiên bản 0 (tiêu đề Report-To
)
giống nhau, ngoại trừ một loại báo cáo: Tính năng Ghi nhật ký lỗi mạng không được hỗ trợ trong API Báo cáo mới.
Đọc hướng dẫn di chuyển để biết thông tin chi tiết.
Loại báo cáo | Chrome | Chrome dành cho iOS | Safari | Firefox | Edge |
---|---|---|---|---|---|
Vi phạm Chính sách quyền riêng tư (CSP) (Chỉ ở Cấp 3)* | ✔ Có | ✔ Có | ✔ Có | ✘ Không | ✔ Có |
Ghi nhật ký lỗi mạng | ✘ Không | ✘ Không | ✘ Không | ✘ Không | ✘ Không |
Vi phạm COOP/COEP | ✔ Có | ✘ Không | ✔ Có | ✘ Không | ✔ Có |
Tất cả các loại khác: Vi phạm chính sách tài liệu, Không dùng nữa, Can thiệp, Sự cố | ✔ Có | ✘ Không | ✘ Không | ✘ Không | ✔ Có |
Bảng này chỉ tóm tắt khả năng hỗ trợ report-to
với tiêu đề Reporting-Endpoints
mới. Hãy đọc mẹo di chuyển báo cáo CSP nếu bạn đang muốn di chuyển sang Reporting-Endpoints
.
Sử dụng API Báo cáo
Quyết định nơi gửi báo cáo
Bạn có hai lựa chọn:
- Gửi báo cáo đến dịch vụ thu thập báo cáo hiện có.
- Gửi báo cáo cho một trình thu thập báo cáo mà bạn tự xây dựng và vận hành.
Cách 1: Sử dụng một dịch vụ thu thập báo cáo hiện có
Một số ví dụ về dịch vụ thu thập báo cáo là:
Nếu bạn biết các giải pháp khác, hãy mở vấn đề để cho chúng tôi biết, chúng tôi sẽ cập nhật bài đăng này!
Ngoài giá, hãy cân nhắc những điểm sau khi chọn công cụ thu thập báo cáo: 🧐
- Công cụ thu thập này có hỗ trợ tất cả các loại báo cáo không? Ví dụ: không phải tất cả các giải pháp điểm cuối báo cáo hỗ trợ báo cáo COOP/COEP.
- Bạn có cảm thấy thoải mái khi chia sẻ bất kỳ URL nào của ứng dụng với trình thu thập báo cáo của bên thứ ba không? Ngay cả khi trình duyệt xoá thông tin nhạy cảm khỏi những URL này, thì thông tin nhạy cảm có thể bị rò rỉ theo cách này. Nếu chiến dịch này có vẻ quá rủi ro cho cho ứng dụng của bạn, vận hành điểm cuối báo cáo của riêng bạn.
Lựa chọn 2: Tạo và vận hành trình thu thập báo cáo của riêng bạn
Việc xây dựng máy chủ của riêng bạn để nhận báo cáo không phải là một việc đơn giản. Để bắt đầu, bạn có thể phát triển nhánh mã nguyên mẫu gọn nhẹ. Báo cáo được xây dựng bằng Express và có thể nhận cũng như hiển thị báo cáo.
Chuyển đến trình thu thập báo cáo tạo sẵn.
Nhấp vào Phối lại để chỉnh sửa để có thể chỉnh sửa dự án.
Giờ bạn đã có bản sao của mình! Bạn có thể tuỳ chỉnh thư viện này cho mục đích của riêng mình.
Nếu bạn không sử dụng bản mẫu và đang xây dựng máy chủ của riêng mình từ đầu:
- Kiểm tra các yêu cầu
POST
cóContent-Type
làapplication/reports+json
để nhận dạng báo cáo các yêu cầu mà trình duyệt gửi đến điểm cuối của bạn. - Nếu điểm cuối nằm trên một nguồn gốc khác với trang web của bạn, hãy đảm bảo rằng điểm cuối đó hỗ trợ các yêu cầu kiểm tra CORS.
Lựa chọn 3: Kết hợp Lựa chọn 1 và 2
Bạn nên để một nhà cung cấp cụ thể xử lý một số loại báo cáo, nhưng bạn chỉ cần có một nhà cung cấp nội bộ cho những người khác.
Trong trường hợp này, hãy đặt nhiều điểm cuối như sau:
Reporting-Endpoints: endpoint-1="https://reports-collector.example", endpoint-2="https://my-custom-endpoint.example"
Định cấu hình tiêu đề Reporting-Endpoints
Đặt tiêu đề phản hồi Reporting-Endpoints
. Giá trị của giá trị này phải là một hoặc một chuỗi các ký tự được phân tách bằng dấu phẩy
cặp khoá-giá trị:
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
Nếu bạn đang di chuyển từ API Báo cáo cũ sang API Báo cáo mới, thì bạn nên
đặt cả Reporting-Endpoints
và Report-To
. Xem thông tin chi tiết trong hướng dẫn di chuyển. Cụ thể, nếu bạn đang sử dụng tính năng báo cáo cho
Content-Security-Policy
chỉ vi phạm thông qua lệnh report-uri
. Hãy kiểm tra các bước di chuyển để báo cáo CSP.
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
Report-To: ...
Khoá (tên điểm cuối)
Mỗi khoá có thể là một tên mà bạn chọn, chẳng hạn như main-endpoint
hoặc endpoint-1
.
Bạn có thể quyết định đặt các điểm cuối khác nhau được đặt tên cho các báo cáo khác nhau
– ví dụ: my-coop-endpoint
, my-csp-endpoint
. Với cách này, bạn
có thể gửi báo cáo đến các điểm cuối khác nhau tuỳ theo loại điểm cuối.
Nếu bạn muốn nhận sự can thiệp, ngừng sử dụng và/hoặc sự cố
báo cáo nội dung, hãy đặt một điểm cuối có tên default
.
Nếu tiêu đề Reporting-Endpoints
xác định không có điểm cuối default
, thì các báo cáo thuộc loại này sẽ không được gửi (mặc dù báo cáo sẽ được tạo).
Giá trị (URL)
Mỗi giá trị là một URL mà bạn chọn, nơi báo cáo sẽ được gửi đến. URL để đặt ở đây tuỳ thuộc vào quyết định của bạn ở Bước 1.
URL điểm cuối:
- Phải bắt đầu bằng dấu gạch chéo (
/
). Đường dẫn tương đối không được hỗ trợ. - Có thể có nhiều nguồn gốc; nhưng trong trường hợp đó, thông tin xác thực không được gửi cùng với báo cáo.
Ví dụ
Reporting-Endpoints: my-coop-endpoint="https://reports.example/coop", my-csp-endpoint="https://reports.example/csp", default="https://reports.example/default"
Sau đó, bạn có thể dùng từng điểm cuối được đặt tên trong chính sách thích hợp hoặc dùng một điểm cuối trên một điểm cuối duy nhất trên tất cả các chính sách.
Đặt tiêu đề ở đâu?
Trong API Báo cáo mới – là API được đề cập trong
bài đăng— báo cáo thuộc phạm vi tài liệu. Điều này có nghĩa là đối với một trường hợp
nguồn gốc, các chứng từ khác, chẳng hạn như site.example/page1
và
site.example/page2
có thể gửi báo cáo đến nhiều điểm cuối.
Để nhận được báo cáo về các lỗi vi phạm hoặc việc ngừng sử dụng diễn ra trên bất kỳ trang nào của trang web, hãy đặt tiêu đề làm phần mềm trung gian trên tất cả các phản hồi.
Dưới đây là một ví dụ trong Express:
const REPORTING_ENDPOINT_BASE = 'https://report.example';
const REPORTING_ENDPOINT_MAIN = `${REPORTING_ENDPOINT_BASE}/main`;
const REPORTING_ENDPOINT_DEFAULT = `${REPORTING_ENDPOINT_BASE}/default`;
app.use(function (request, response, next) {
// Set up the Reporting API
response.set(
'Reporting-Endpoints',
`main-endpoint="${REPORTING_ENDPOINT_MAIN}", default="${REPORTING_ENDPOINT_DEFAULT}"`,
);
next();
});
Chỉnh sửa chính sách của bạn
Tiêu đề Reporting-Endpoints
hiện đã được định cấu hình, hãy thêm report-to
vào từng tiêu đề chính sách mà bạn muốn vi phạm
. Giá trị của report-to
phải là một trong các điểm cuối được đặt tên mà bạn đã đặt
đã định cấu hình.
Bạn có thể sử dụng nhiều điểm cuối cho nhiều chính sách hoặc sử dụng nhiều điểm cuối điểm cuối giữa các chính sách.
report-to
không cần thiết trong trường hợp ngừng sử dụng, can thiệp và sự cố
. Những báo cáo này không bị ràng buộc bởi bất kỳ chính sách nào. Bạn có thể tạo các thành phần này miễn là
một điểm cuối default
được thiết lập và được gửi đến điểm cuối default
này.
Ví dụ:
# Content-Security-Policy violations and Document-Policy violations
# will be sent to main-endpoint
Content-Security-Policy: script-src 'self'; object-src 'none'; report-to main-endpoint;
Document-Policy: document-write=?0;report-to=main-endpoint;
# Deprecation reports don't need an explicit endpoint because
# these reports are always sent to the default endpoint
Mã mẫu
Để xem tất cả những điều này trong ngữ cảnh, dưới đây là một ví dụ về máy chủ Nút sử dụng Express và tập hợp tất cả nội dung được thảo luận trong bài viết này. Hướng dẫn định cấu hình báo cáo cho một số loại báo cáo khác nhau và hiển thị kết quả.
Gỡ lỗi thiết lập báo cáo
Có chủ ý tạo báo cáo
Khi thiết lập API Báo cáo, có thể bạn sẽ phải cố tình vi phạm chính sách của mình để kiểm tra xem báo cáo có được tạo và gửi như dự kiến không. Để xem ví dụ về mã vi phạm chính sách và thực hiện những hành vi xấu khác tạo báo cáo thuộc mọi loại, hãy xem bản minh hoạ.
Tiết kiệm thời gian
Báo cáo có thể được gửi trễ, tức là khoảng một phút, tức là dài
khi gỡ lỗi. 🔒 Thật may là khi gỡ lỗi trong Chrome, bạn có thể sử dụng cờ
--short-reporting-delay
để nhận báo cáo ngay khi được tạo.
Chạy lệnh này trong thiết bị đầu cuối của bạn để bật cờ này:
YOUR_PATH/TO/EXECUTABLE/Chrome --short-reporting-delay
Sử dụng Công cụ cho nhà phát triển
Trong Chrome, hãy sử dụng Công cụ cho nhà phát triển để xem các báo cáo đã hoặc sẽ gửi đi.
Kể từ tháng 10 năm 2021, tính năng này đang ở giai đoạn thử nghiệm. Để sử dụng, hãy làm theo các bước sau:
- Sử dụng Chrome phiên bản 96 trở lên (kiểm tra bằng cách nhập
chrome://version
vào trình duyệt) - Nhập hoặc dán
chrome://flags/#enable-experimental-web-platform-features
vào thanh URL của Chrome. - Nhấp vào Đã bật.
- Khởi động lại trình duyệt.
- Mở Công cụ của Chrome cho nhà phát triển.
- Trong Công cụ của Chrome cho nhà phát triển, hãy mở phần Cài đặt. Trong mục Thử nghiệm, hãy nhấp vào Bật bảng điều khiển API báo cáo trong bảng điều khiển Application (Ứng dụng).
- Tải lại Công cụ cho nhà phát triển.
- Tải lại trang. Các báo cáo do trang Công cụ cho nhà phát triển tạo ra đang mở sẽ được được liệt kê trong Công cụ của Chrome cho nhà phát triển Bảng điều khiển Application (Ứng dụng), bên dưới Báo cáo API.
![Ảnh chụp màn hình của Công cụ cho nhà phát triển liệt kê các báo cáo](https://developer.chrome.com/static/docs/capabilities/web-apis/reporting-api/image/screenshot-devtools-list-adb1aaa437b6b.png?authuser=19&hl=vi)
Trạng thái báo cáo
Cột Trạng thái cho bạn biết liệu báo cáo đã được gửi thành công hay chưa.
Trạng thái | Mô tả |
---|---|
Success |
Trình duyệt đã gửi báo cáo và điểm cuối đã trả lời bằng một mã thành công (200 hoặc một mã phản hồi thành công khác 2xx ). |
Pending |
Trình duyệt hiện đang cố gửi báo cáo. |
Queued |
Báo cáo đã được tạo và trình duyệt hiện không cố gửi báo cáo. Báo cáo sẽ xuất hiện dưới dạng Queued trong một trong hai trường hợp sau:
|
MarkedForRemoval |
Sau khi thử lại một lúc (Queued ), trình duyệt đã ngừng gửi báo cáo và sẽ sớm xoá báo cáo đó khỏi danh sách báo cáo cần gửi. |
Sau một thời gian, các báo cáo sẽ bị xoá, cho dù chúng có được gửi thành công hay không.
Khắc phục sự cố
Báo cáo không được tạo hoặc không được gửi như dự kiến đến điểm cuối của bạn? Dưới đây là một vài mẹo để khắc phục sự cố này.
Báo cáo sẽ không được tạo
Các báo cáo hiển thị trong Công cụ cho nhà phát triển đã được tạo chính xác. Nếu báo cáo mà bạn dự kiến không xuất hiện trong danh sách này:
- Hãy kiểm tra
report-to
trong các chính sách của bạn. Nếu cấu hình này bị định cấu hình sai, báo cáo sẽ không được tạo. Hãy chuyển đến phần Chỉnh sửa chính sách để khắc phục vấn đề này. Một cách khác để khắc phục sự cố này là kiểm tra bảng điều khiển Công cụ cho nhà phát triển trong Chrome: nếu lỗi bật lên trong bảng điều khiển cho lỗi vi phạm mà bạn dự kiến, điều này có nghĩa là chính sách của bạn có thể được định cấu hình đúng cách. - Xin lưu ý rằng chỉ các báo cáo đã được tạo cho tài liệu trong Công cụ cho nhà phát triển mới được mở
hiện trong danh sách này. Một ví dụ: nếu trang web của bạn
site1.example
nhúng iframesite2.example
vi phạm chính sách và do đó tạo ra một báo cáo, báo cáo này sẽ chỉ hiển thị trong Công cụ cho nhà phát triển nếu bạn mở iframe trong cửa sổ riêng và mở Công cụ cho nhà phát triển cho cửa sổ đó.
Báo cáo được tạo nhưng không được gửi hoặc chưa nhận được
Điều gì xảy ra nếu bạn có thể thấy một báo cáo trong Công cụ cho nhà phát triển nhưng điểm cuối của bạn không nhận được báo cáo đó?
- Hãy sử dụng độ trễ ngắn. Có thể lý do khiến bạn không thể xem báo cáo là vì vẫn chưa được gửi!
Kiểm tra cấu hình tiêu đề
Reporting-Endpoints
của bạn. Nếu có vấn đề, hãy báo cáo đã được tạo đúng cách thì sẽ không được gửi. Trong Công cụ cho nhà phát triển, trạng thái của báo cáo sẽ vẫn giữ nguyênQueued
(có thể nhảy nhanh vềPending
, sau đó nhanh chóng quay lạiQueued
khi cố gắng giao hàng thực hiện) trong trường hợp này. Một số lỗi thường gặp có thể gây ra lỗi này:Điểm cuối được sử dụng nhưng chưa được định cấu hình. Ví dụ:
Document-Policy: document-write=?0;report-to=endpoint-1; Reporting-Endpoints: default="https://reports.example/default"
Báo cáo vi phạm chính sách tài liệu phải được gửi đến endpoint-1
, nhưng tên điểm cuối này chưa được định cấu hình trong
Reporting-Endpoints
Thiếu điểm cuối
default
. Một số loại báo cáo, chẳng hạn như báo cáo không dùng nữa và biện pháp can thiệp sẽ chỉ được gửi đến điểm cuối có têndefault
. Đọc thêm trong bài viết Định cấu hình tiêu đề Điểm cuối báo cáo.Tìm vấn đề trong cú pháp tiêu đề chính sách, chẳng hạn như thiếu dấu ngoặc kép. Xem chi tiết.
Kiểm tra để đảm bảo rằng điểm cuối của bạn có thể xử lý các yêu cầu được gửi đến.
Đảm bảo rằng điểm cuối của bạn hỗ trợ các yêu cầu kiểm tra CORS. Nếu không, thì tài khoản đó không thể nhận báo cáo.
Kiểm thử hành vi của điểm cuối. Để làm được điều đó, thay vì tạo theo cách thủ công, bạn có thể mô phỏng trình duyệt bằng cách gửi đến các yêu cầu điểm cuối giống như nội dung mà trình duyệt sẽ gửi. Chạy lệnh sau:
curl --header "Content-Type: application/reports+json" \ --request POST \ --data '[{"age":420,"body":{"columnNumber":12,"disposition":"enforce","lineNumber":11,"message":"Document policy violation: document-write is not allowed in this document.","policyId":"document-write","sourceFile":"https://dummy.example/script.js"},"type":"document-policy-violation","url":"https://dummy.example/","user_agent":"xxx"},{"age":510,"body":{"blockedURL":"https://dummy.example/img.jpg","destination":"image","disposition":"enforce","type":"corp"},"type":"coep","url":"https://dummy.example/","user_agent":"xxx"}]' \ YOUR_ENDPOINT
Điểm cuối của bạn phải phản hồi bằng một mã thành công (
200
hoặc một mã phản hồi thành công khác2xx
). Nếu không, đã xảy ra vấn đề về cấu hình.
Các cơ chế báo cáo có liên quan
Chỉ báo cáo
Tiêu đề chính sách -Report-Only
và Reporting-Endpoints
hoạt động cùng nhau.
Điểm cuối được định cấu hình trong Reporting-Endpoints
và được chỉ định trong trường report-to
của
Content-Security-Policy
!
Cross-Origin-Embedder-Policy
và
Cross-Origin-Opener-Policy
sẽ nhận được báo cáo khi những chính sách này bị vi phạm.
Bạn cũng có thể chỉ định điểm cuối được định cấu hình trong Reporting-Endpoints
trong
Trường report-to
/
Content-Security-Policy-Report-Only
!
Cross-Origin-Embedder-Policy-Report-Only
và
Cross-Origin-Opener-Policy-Report-Only
Họ cũng sẽ nhận được báo cáo khi những chính sách này bị vi phạm.
Mặc dù báo cáo được gửi trong cả hai trường hợp, nhưng tiêu đề -Report-Only
không thực thi
chính sách: không có gì vi phạm hoặc thực sự bị chặn, nhưng bạn sẽ nhận được
báo cáo về những gì sẽ bị hỏng hoặc bị chặn.
ReportingObserver
API JavaScript ReportingObserver
có thể giúp bạn
quan sát các cảnh báo phía máy khách.
ReportingObserver
và tiêu đề Reporting-Endpoints
tạo ra các báo cáo
trông giống nhau, nhưng chúng cho phép các trường hợp sử dụng hơi khác nhau.
Sử dụng ReportingObserver
trong trường hợp:
- Bạn chỉ muốn theo dõi việc ngừng sử dụng và/hoặc can thiệp của trình duyệt.
ReportingObserver
cho thấy cảnh báo phía máy khách, chẳng hạn như về việc ngừng sử dụng và trình duyệt, nhưng không giống nhưReporting-Endpoints
, công cụ này không thu thập bất kỳ loại báo cáo nào khác, chẳng hạn như báo cáo vi phạm CSP hoặc COOP/COEP. - Bạn cần phải phản ứng với những lỗi vi phạm này theo thời gian thực.
ReportingObserver
tạo bạn có thể đính kèm lệnh gọi lại vào sự kiện vi phạm. - Bạn muốn đính kèm thông tin bổ sung vào báo cáo để hỗ trợ gỡ lỗi, thông qua lệnh gọi lại tuỳ chỉnh.
Một điểm khác biệt nữa là ReportingObserver
chỉ được định cấu hình ở phía máy khách:
bạn có thể sử dụng API này ngay cả khi không kiểm soát được tiêu đề phía máy chủ và không thể
đặt Reporting-Endpoints
.
Tài liệu đọc thêm
- Hướng dẫn di chuyển từ API Báo cáo phiên bản 0 sang phiên bản 1
- ReportingObserver
- 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. Rất cảm ơn Ian Clelland, Eiji Kitamura và Milica Mihajlija vì những bài đánh giá và đề xuất trong bài viết này.