Sử dụng API Báo cáo để giám sát các lỗi vi phạm về 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 khi phát hành công khai. Bạn sẽ không thấy chúng trên thiết bị hoặc trong quá trình phát triển 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ư lỗi vi phạm bảo mật hoặc các lệnh gọi API không dùng nữa và sắp bị ngừng hoạt động trên trang web của bạn, đồng thời truyền các lỗi đó đến điểm cuối mà bạn đã chỉ định.
API này cho phép bạn khai báo những thông tin bạn muốn theo dõi thông qua tiêu đề HTTP và hoạt động do 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 gặp các loại lỗi này, bạn sẽ biết để có thể khắc phục.
Bài đăng này trình bày những việc mà 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 API Báo cáo trong thực tế 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 bên dưới, từ khi tạo báo cáo đến quyền truy cập của nhà phát triển vào báo cáo](https://developer.chrome.com/static/docs/capabilities/web-apis/reporting-api/image/diagram-summarizing-step-7115c265c2e02.png?authuser=5&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. Không biết các số này có tác dụng gì? Không sao cả, bạn vẫn có thể hiểu ví dụ này.
Bạn quyết định theo dõi trang web của mình để biết thời điểm các chính sách này bị vi phạm, nhưng cũng vì bạn muốn theo dõi các API không dùng nữa hoặc sắp bị ngừng hoạt động mà cơ sở mã của bạn có thể đang sử dụng.
Để thực hiện việc này, bạn định cấu hình tiêu đề Reporting-Endpoints
và liên kết các tên điểm cuối này thông qua lệnh report-to
trong các chính sách 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
Đã xảy ra điều không mong muốn và một số người dùng của bạn đã vi phạm những chính sách này.
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 sẽ tạo một báo cáo về lỗi vi phạm CSP, một báo cáo về lỗi vi phạm Chính sách tài liệu và một báo cáo về việc Ngừng sử dụng ghi lại những vấn đề này.
Với độ trễ ngắn (tối đa một phút), trình duyệt sẽ gửi các báo cáo đến điểm cuối đã được định cấu hình cho loại vi phạm này. Báo cáo do chính trình duyệt gửi ngoài băng tần (không phải do máy chủ hoặc trang web của bạn gửi).
(Các) thiết bị đầu cuối nhận được(các) báo cáo này.
Giờ đây, bạn có thể truy cập vào báo cáo về các điểm cuối này và theo dõi xem đã xảy ra lỗi gì. Bạn đã sẵn sàng để bắt đầu khắc phục sự cố đang ảnh hưởng đến người dùng của mình.
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"
}
Các trường hợp sử dụng và loại báo cáo
Bạn có thể định cấu hình API Báo cáo để theo dõi nhiều loại cảnh báo hoặc vấn đề đáng chú ý xảy ra trên trang web của mình:
Loại báo cáo | Ví dụ về tình huống sẽ tạo báo cáo |
---|---|
Vi phạm về CSP (Chỉ áp dụng cho Cấp 3) | Bạn đã đặt Content-Security-Policy (CSP) trên một trong các trang của mình, nhưng trang này đang cố gắng tải một tập lệnh mà CSP của bạn không cho phép. |
Vi phạm về 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 bao gồm một iframe trên nhiều nguồn gốc chưa chọn tải bằng tài liệu nhiều nguồn gốc. |
Vi phạm chính sách về 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 có một tập lệnh sẽ cố gắng gọi document.write . |
Vi phạm chính sách về quyền | Trang có chính sách về quyền ngăn việc sử dụng micrô và có một tập lệnh yêu cầu nhập âm thanh. |
Cảnh báo về việc không dùng nữa | Trang đang sử dụng một API không còn được dùng nữa; trang này sẽ gọi API này trực tiếp hoặc thông qua một tập lệnh cấp cao nhất của bên thứ ba. |
Can thiệp | Trang đang cố thực hiện một hành động nào đó mà trình duyệt quyết định không thực hiện 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 các 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. |
Vụ đụng xe | 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 gửi báo cáo đến điểm cuối mà bạn đã thiết lập. Trình này sẽ gửi các yêu cầu như sau:
POST
Content-Type: application/reports+json
Tải trọng của những yêu cầu này là một danh sách các báo cáo.
Danh sách ví dụ về các 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 mà bạn có thể tìm thấy trong mỗi báo cáo này:
Trường | Nội dung 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 báo cáo được xác định theo type của báo cáo. ⚠️ Mỗi loại báo cáo sẽ có nội dung riêng.
Để xem nội dung chính xác của từng loại báo cáo, hãy xem đ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 |
Loại báo cáo, ví dụ: csp-violation hoặc coep . |
url |
Địa chỉ của tài liệu hoặc nhân viên 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à phân đoạn sẽ bị xoá khỏi URL này. |
user_agent |
Tiêu đề User-Agent của yêu cầu đã tạo báo cáo. |
Báo cáo có thông tin 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 xác thực có thể cung cấp ngữ cảnh bổ sung hữu ích về báo cáo; ví dụ: liệu tài khoản của một người dùng cụ thể có liên tục kích hoạt lỗi hay không, hoặc liệu một chuỗi thao tác nhất định được thực hiện trên các trang khác có đang kích hoạt một báo cáo trên trang này hay không.
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 phân phố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 gửi báo cáo đế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; trình duyệt sẽ ghi lại, xếp hàng và tự động gửi báo cáo vào thời điểm thích hợp.
Điều này có nghĩa là hiệu suất không hề thay đổi khi bạn sử dụng API Báo cáo.
Báo cáo được gửi với độ trễ (tối đa một phút) để 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 để phù hợp với kết nối mạng của người dùng, điều này đặc biệ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ý công việc có mức độ ưu tiên cao hơn hoặc nếu người dùng đang sử dụng mạng chậm và/hoặc bị tắc nghẽn tại thời điểm đó.
Các vấn đề về bên thứ ba và bên thứ nhất
Những báo cáo được tạo do các lỗi vi phạm hoặc việc ngừng sử dụng diễn ra trên trang của bạn sẽ được gửi đến(các) điểm cuối mà bạn đã định cấu hình. Số liệu này bao gồm cả các lỗi vi phạm do tập lệnh bên thứ ba chạy trên trang của bạn mắc phải.
Các lỗi vi phạm hoặc việc ngừng sử dụng xảy ra trong một iframe 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 hoạt động báo cáo của riêng nó và thậm chí là 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 điều đó tuỳ thuộc 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 một trang bị vi phạm chính sách 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 tiêu đề Báo cáo-Điểm cuối được thiết lập trên trang của bạn: API không dùng nữa do các tập lệnh bên thứ ba chạy trên trang của bạn gọi sẽ được báo cáo cho điểm cuối của bạn. API không dùng nữa được một iframe nhúng trong trang gọi sẽ không được báo cáo cho điểm cuối của bạn. 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, và 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=5&hl=vi)
Hỗ trợ trình duyệt
Bảng dưới đây tóm tắt tính năng hỗ trợ của trình duyệt cho API Báo cáo phiên bản 1, với tiêu đề Reporting-Endpoints
. Khả năng hỗ trợ trình duyệt cho API Báo cáo phiên bản 0 (tiêu đề Report-To
) cũng tương tự như vậy, 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 cho iOS | Safari | Firefox | Edge |
---|---|---|---|---|---|
Lỗi vi phạm Chính sách bảo mật nội dung (CSP) (Chỉ dành cho 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, Ngừng sử dụng, 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
có tiêu đề Reporting-Endpoints
mới. Hãy đọc cá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 một dịch vụ thu thập báo cáo hiện có.
- Gửi báo cáo đến trình thu thập báo cáo mà bạn tự tạo và vận hành.
Cách 1: Sử dụng dịch vụ thu thập báo cáo hiện có
Sau đây là một số ví dụ về dịch vụ thu thập báo cáo:
Nếu bạn biết các giải pháp khác, hãy mở một 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 mức giá, hãy cân nhắc các điểm sau đây khi chọn trình thu thập báo cáo: 🧐
- Trình 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 giải pháp báo cáo điểm cuối nào cũng hỗ trợ báo cáo COOP/COEP.
- Bạn có thoải mái 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 vẫn có thể bị rò rỉ theo cách này. Nếu việc này nghe có vẻ quá rủi ro cho ứng dụng của bạn, hãy vận hành điểm cuối báo cáo của riêng mình.
Cách 2: Xây dựng 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ủ nhận báo cáo của riêng bạn không phải là một việc đơn giản. Để bắt đầu, bạn có thể tạo phiên bản nguyên mẫu nhẹ của chúng tôi. Trang này được xây dựng bằng ứng dụng Sao lưu nhanh, có thể nhận và hiển thị báo cáo.
Hãy chuyển đến trình thu thập báo cáo mẫu.
Nhấp vào Remix để chỉnh sửa (Remix) để chỉnh sửa dự án.
Giờ đây, bạn đã có bản sao của mình! Bạn có thể tuỳ chỉnh dữ liệu này cho mục đích riêng của 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 các yêu cầu báo cáo do trình duyệt gửi đến điểm cuối của bạn. - Nếu điểm cuối của bạn nằm trên một nguồn gốc khác với trang web, hãy đảm bảo điểm cuối đó hỗ trợ các yêu cầu kiểm tra tài khoản cơ sở dữ liệu (CORS).
Phương án 3: Kết hợp phương án 1 và 2
Bạn có thể muốn để một nhà cung cấp cụ thể xử lý một số loại báo cáo, nhưng bạn có giải pháp nội bộ cho những loại báo cáo 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 thuộc tính này phải là một hoặc một chuỗi các cặp khoá-giá trị được phân tách bằng dấu phẩy:
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
Nếu đ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 chỉ đang sử dụng tính năng báo cáo cho các lỗi vi phạm Content-Security-Policy
thông qua lệnh report-uri
, hãy xem các bước di chuyển để có 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 nhiều điểm cuối được đặt tên cho các loại báo cáo khác nhau – ví dụ: my-coop-endpoint
, my-csp-endpoint
. Nhờ vậy, bạn có thể định tuyến báo cáo đến nhiều điểm cuối tuỳ thuộc vào loại điểm cuối.
Nếu bạn muốn nhận được các báo cáo can thiệp, ngừng sử dụng và/hoặc sự cố, hãy đặt một điểm cuối có tên là default
.
Nếu tiêu đề Reporting-Endpoints
không xác định điểm cuối default
nào, thì các báo cáo thuộc loại này sẽ không được gửi (mặc dù chúng sẽ được tạo).
Giá trị (URL)
Mỗi giá trị là một URL do bạn chọn, nơi các báo cáo sẽ được gửi đến. URL cần đặt ở đây phụ thuộc vào những gì bạn đã quyết định ở 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ó trên 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ể sử dụng từng điểm cuối được đặt tên trong chính sách thích hợp hoặc sử dụng 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 (API được đề cập trong bài đăng này), các báo cáo có phạm vi là tài liệu. Điều này có nghĩa là đối với một điểm gốc nhất định, các tài liệu khác nhau, 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 báo cáo về các lỗi vi phạm hoặc tình trạng 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 trong 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
Hiện tại, tiêu đề Reporting-Endpoints
đã được định cấu hình, hãy thêm một lệnh report-to
vào từng tiêu đề chính sách mà bạn muốn nhận báo cáo vi phạm. Giá trị của report-to
phải là một trong những điểm cuối có tên mà bạn đã đị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 các điểm cuối khác nhau trên các chính sách.
Bạn không cần report-to
cho các báo cáo ngừng sử dụng, can thiệp và sự cố. Các báo cáo này không bị ràng buộc với bất kỳ chính sách nào. Các mẫu này được tạo miễn là đ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
Ví dụ về mã
Để xem tất cả những điều này trong ngữ cảnh, dưới đây là ví dụ về máy chủ Nút sử dụng Express và tập hợp tất cả các phần được thảo luận trong bài viết này. Hướng dẫn này cho biết cách định cấu hình báo cáo cho một số loại báo cáo và hiển thị kết quả.
Gỡ lỗi chế độ 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ẽ cần cố ý 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 hay không. Để xem đoạn mã ví dụ vi phạm chính sách và thực hiện những hành vi xấu khác sẽ tạo ra mọi loại báo cáo, hãy xem bản minh hoạ.
Tiết kiệm thời gian
Các báo cáo có thể được gửi với độ trễ (khoảng một phút) tức là khoảng thời gian dài khi gỡ lỗi. Jibe 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 sau khi báo cáo được tạo.
Chạy lệnh này trong dòng lệnh 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 đã gửi hoặc sẽ được gửi.
Kể từ tháng 10 năm 2021, tính năng này đang trong 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 phần 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 Ứ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 đang mở sẽ được liệt kê trong bảng điều khiển Ứng dụng của Công cụ của Chrome cho nhà phát triển, trong phần API báo cáo.
![Ảnh chụp màn hình 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=5&hl=vi)
Trạng thái báo cáo
Cột Trạng thái cho bạn biết báo cáo đã được gửi thành công hay chưa.
Trạng thái | Nội dung 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ắng 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 ở một trong hai trường hợp sau:
|
MarkedForRemoval |
Sau khi thử lại một thời gian (Queued ), trình duyệt đã ngừng tìm cách 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. |
Báo cáo sẽ bị xoá sau một khoảng thời gian, 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? Sau đây là một vài mẹo giúp bạn khắc phục vấn đề này.
Báo cáo chưa đượ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 muốn không xuất hiện trong danh sách này:
- Hãy kiểm tra
report-to
trong chính sách của bạn. Nếu bạn định cấu hình sai cấu hình này, 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 đối với lỗi vi phạm mà bạn dự kiến, thì đ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. - Lưu ý rằng chỉ những báo cáo đã được tạo cho tài liệu Công cụ cho nhà phát triển đang mở mới xuất hiện trong danh sách này. Một ví dụ: nếu trang web của bạn
site1.example
nhúng một iframesite2.example
vi phạm chính sách và do đó tạo ra một báo cáo, thì 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 gửi được hoặc không được nhận
Điều gì xảy ra nếu bạn có thể xem 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 nhớ sử dụng độ trễ ngắn. Có thể bạn không thấy báo cáo vì báo cáo đó chưa được gửi!
Kiểm tra cấu hình tiêu đề
Reporting-Endpoints
của bạn. Nếu có sự cố với mã đó, báo cáo đã được tạo chính xác 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 làQueued
(có thể chuyển đếnPending
, sau đó nhanh chóng quay lạiQueued
khi cố gắng phân phối) trong trường hợp này. Một số lỗi phổ biến có thể gây ra điều 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"
Các báo cáo vi phạm chính sách về tài liệu sẽ được gửi tới endpoint-1
, nhưng tên điểm cuối này không đượ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 về việc ngừng sử dụng và can thiệp, sẽ chỉ được gửi đến điểm cuối có tên làdefault
. Đọc thêm trong Định cấu hình tiêu đề Báo cáo-Điểm cuối.Tìm vấn đề trong cú pháp của tiêu đề chính sách, chẳng hạn như thiếu dấu ngoặc kép. Xem thông tin 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.
Hãy đả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, Analytics không thể nhận báo cáo.
Kiểm thử hành vi của điểm cuối. Để thực hiện việc này, thay vì tạo báo cá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 có dạng 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ã thành công (
200
hoặc một mã phản hồi thành công khác2xx
). Nếu không, thì đã xảy ra sự cố với cấu hình của điểm cuối.
Các cơ chế báo cáo có liên quan
Chỉ báo cáo
Các tiêu đề chính sách -Report-Only
và Reporting-Endpoints
hoạt động cùng nhau.
Các đ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 vi phạm các chính sách này.
Bạn cũng có thể chỉ định các điểm cuối đã định cấu hình trong Reporting-Endpoints
trong trường report-to
của 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 vi phạm những chính sách này.
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
các chính sách: không có gì bị lỗi 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ị lỗi 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 các báo cáo trông giống nhau, như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 các biện pháp can thiệp của trình duyệt.
ReportingObserver
hiển thị cảnh báo phía máy khách như ngừng sử dụng và can thiệp vào trình duyệt, nhưng không giống nhưReporting-Endpoints
, API 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ư lỗi vi phạm CSP hoặc COOP/COEP. - Bạn cần phải xử lý những lỗi vi phạm này theo thời gian thực.
ReportingObserver
giúp bạn có thể đính kèm lệnh gọi lại vào trường hợp vi phạm. - Bạn muốn đính kèm thông tin bổ sung vào một 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 khác là ReportingObserver
chỉ được định cấu hình ở phía máy khách: bạn có thể sử dụng cấu hình này ngay cả khi không có quyền kiểm soát đối với cá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
- 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 Clelland, Eiji Kitamura và Milica Mihajlija vì những bài đánh giá và đề xuất về bài viết này.