Reporting API 已推出新版本。这种方式更加注重隐私保护,并且更有可能在各浏览器中得到支持。
Reporting API 会告知您访问者在使用它时您的网站上发生的错误。借助此工具,您可以了解浏览器干预、浏览器崩溃、违反内容安全政策、COOP/COEP 违规行为、弃用警告等。
Reporting API 已发布新版本。新 API 更加精简,更有可能获得跨浏览器支持。
摘要
网站开发者
如果您的网站已有报告功能:请使用新标头 (Reporting-Endpoints
) 迁移到 v1,但将旧版标头保留一段时间 (Report-To
)。请参阅迁移:示例代码。
如果您正在向网站添加报告功能:请仅使用新标头 (Reporting-Endpoints
)。
⚠️ 在这两种情况下,请务必为可能生成报告的所有响应设置 Reporting-Endpoints
标头。
报告服务开发者
如果您正在维护端点服务或自行运营,那么随着您或外部开发者迁移到 Reporting API v1(Reporting-Endpoints
标头),预计流量会更多。
请继续阅读以了解详情和示例代码!
网络错误日志记录
我们将开发一种新的网络错误日志记录机制。在该机制可用后,请从 Reporting API v0 切换到该新机制。
演示和代码
v0 与 v1 之间的区别
具体变化
- API Surface 有所不同。
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
- 报告范围不同。
对于 v0,您只能为某些响应设置报告端点。该来源上的其他文档(页面)会自动使用这些环境端点。
对于 v1,您需要在可能生成报告的所有响应中设置 Reporting-Endpoints
标头。
- 这两种 API 支持相同的报告类型,但有一个例外:v1 不支持网络错误报告。如需了解详情,请参阅迁移步骤。
- 目前没有跨浏览器支持 v0,以后也不会支持 v0。将来,我们更有可能在多个浏览器中支持 v1。
保持不变的内容
- 报告的格式和结构保持不变。
- 浏览器向端点发送的请求仍然是
Content-type
application/reports+json
的POST
请求。 - v0 和 v1 均支持将某些端点映射到特定报告类型。
default
端点的角色保持不变。Reporting API v1 对
ReportingObserver
没有任何影响。ReportingObserver
可继续访问所有可观察报告,其格式相同。
v0 和 v1 之间的所有差异
旧版 Reporting API (v0)Report-To 标头 |
新增 Reporting API (v1)Reporting-Endpoints 标头 |
|
---|---|---|
浏览器支持 | Chrome 69 及更高版本和 Edge 69 及更高版本。 | Chrome 96 及更高版本和 Edge 96 及更高版本。Firefox 支持。Safari 没有异议。请参阅浏览器信号。 |
端点 | 将报告发送至多个报告收集器中的任意一个(每个端点组定义多个网址)。 | 将报告发送到特定报告收集器(每个端点仅定义一个网址)。 |
API Surface | 使用 `Report-To` 标头配置已命名的端点组。 |
使用 `Reporting-Endpoints` 标头配置已命名的 endpoints。 |
可通过该 API 生成的报告类型 |
|
保持不变(网络错误日志记录 (NEL) 除外):新的 Reporting API (v1) 不支持此功能。 |
报告范围 | 源网域的技术。 文档的 Report-To 标头会影响来自该来源的其他文档(页面)。报告的 url 字段仍然因文档而异。 |
Document. 文档的 Reporting-Endpoints 标头只会影响该文档。报告的 url 字段仍然因文档而异。 |
报告隔离(批处理) | 如果不同文档(页面)或网站/来源大致同时生成报告且报告端点也相同,系统会一起进行批量处理:它们将以同一条消息的形式发送到报告端点。 |
|
支持负载均衡 / 优先级 | 是 | 否 |
终端开发者:预计流量会更多
如果您已将自己的服务器设置为报告端点,或者正在将报告收集器作为一项服务进行开发或维护,则预计该端点会获得更多流量。
这是因为使用 Reporting API v1 不会像使用 Reporting API v0 那样进行批量处理。因此,当应用开发者开始迁移到 Reporting API v1 时,报告数量将保持不变,但向端点服务器的请求数量会增加。
应用开发者:迁移到 Reporting-Endpoints
(v1)
您该怎么做?
使用新的 Reporting API (v1) 可带来诸多好处 ✅:
- 浏览器信号为正,这意味着 v1 预计可以实现跨浏览器支持(这与仅在 Chrome 和 Edge 中支持的 v0 不同)。
- API 更加精简。
- 我们正在围绕新的 Reporting API (v1) 开发相应工具。
了解了这一点:
- 如果您的网站已使用带有
Report-To
标头的 Reporting API v0,请迁移到 Reporting API v1(请参阅迁移步骤)。如果您的网站已使用内容安全政策违规行为报告功能,请查看有关 CSP 报告的特定迁移步骤。 - 如果您的网站尚未使用 Reporting API,而现在要添加报告功能,请使用新的 Reporting API (v1)(
Reporting-Endpoints
标头)。但有一个例外情况:如果您需要使用网络错误日志记录,请使用Report-To
(v0)。Reporting API v1 目前不支持网络错误日志记录。我们将开发一种新的网络错误日志记录机制 ⏤在推出之前,请使用 Reporting API v0。如果您需要将网络错误日志记录与其他报告类型搭配使用,请同时使用Report-To
(v0) 和Reporting-Endpoints
(v1)。v0 为您提供网络错误日志记录,v1 则为您提供所有其他类型的报告。
迁移步骤
此次迁移的目的是让您不会丢失过去从 v0 中获得的报告。
第 1 步(立即行动):使用
Report-To
(v0) 和Reporting-Endpoints
(v1) 这两个头文件。这样,您可以:
- 得益于
Reporting-Endpoints
(v1) 功能,来自较新版本的 Chrome 和 Edge 客户端的报告。 - 得益于
Report-To
(v0) 功能,来自旧版 Chrome 和 Edge 客户端的报告。
支持
Reporting-Endpoints
的浏览器实例将使用Reporting-Endpoints
,不支持的实例回退到Report-To
。v0 和 v1 的请求和报告格式相同。- 得益于
第 2 步(立即行动):确保已针对可能生成报告的所有响应设置
Reporting-Endpoints
标头。使用 v0 时,您可以选择仅针对某些响应设置报告端点,该来源上的其他文档(页面)将使用此“环境”端点。使用 v1 时,由于范围不同,您需要在可能生成报告的所有响应中设置
Reporting-Endpoints
标头。第 3 步(稍后开始):当所有用户或大多数用户更新到 Chrome 或 Edge 安装(96 及更高版本)后,移除
Report-To
(v0) 并仅保留Reporting-Endpoints
。一种例外情况:如果您确实需要网络错误日志记录报告,请保留
Report-To
,直到为网络错误日志记录采用新机制为止。
请参阅迁移实战宝典中的代码示例。
CSP 报告的迁移步骤
您可以通过以下两种方式配置内容安全政策违规行为报告:
- 通过
report-uri
指令单独使用 CSP 标头。Chrome、Firefox、Safari 和 Edge报告使用内容类型application/csp-report
发送,并且采用 CSP 特有的格式。这些报告称为“CSP 2 级报告”,不依赖于 Reporting API。 - 对于 Reporting API,您需要使用
Report-To
标头(旧版)或更新版本的Reporting-Endpoints
(v1)。只有 Chrome 和 Edge 支持此功能。报告请求的格式与其他 Reporting API 请求相同,内容类型application/reports+json
也相同。
不再推荐使用第一种方法(仅 report-uri
),但使用第二种方法有一些好处。特别值得一提的是,借助该 API,您可以通过单一方式为所有报告类型设置报告和设置通用端点(因为通过 Reporting API⏤CSP 和其他其他报告请求产生的所有报告请求⏤的格式相同application/reports+json
)。
但是,只有少数浏览器支持 report-to
。因此,建议您保留 report-uri
以及 Reporting API 方法(Report-To
或更高版本,使用 Reporting-Endpoints
),以便从多个浏览器获取 CSP 违规报告。在可识别 report-uri
和 report-to
的浏览器中,如果存在 report-to
,则 report-uri
会被忽略。在只能识别 report-uri
的浏览器中,系统仅会考虑 report-uri
。
第 1 步(立即行动):如果您尚未添加,请在
report-uri
旁边添加report-to
。仅支持report-uri
的浏览器 (Firefox) 将使用report-uri
,同样支持report-to
的浏览器(Chrome、Edge)将使用report-to
。如需指定将在report-to
中使用的命名端点,请同时使用标头Report-To
和Reporting-Endpoints
。这样可以确保您从旧版和新版 Chrome 和 Edge 客户端都能获取报告。第 3 步(稍后开始):当所有用户或大多数用户更新到 Chrome 或 Edge 安装(96 及更高版本)后,移除
Report-To
(v0) 并仅保留Reporting-Endpoints
。保留report-uri
,以便仍然针对仅支持它的浏览器获取报告。
请参阅内容安全政策迁移中有关这些步骤的代码示例。
迁移:示例代码
概览
如果您使用旧版 Reporting API (v0) 获取 COOP(Cross-Origin-Opener-Policy
标头)、COEP (Cross-Origin-Embedder-Policy
) 或文档政策(Document-Policy
标头)的违规行为报告:则在迁移到 Reporting API v1 时,无需更改这些政策标头本身。您需要从旧版 Report-To
标头迁移到新的 Reporting-Endpoints
标头。
如果您使用旧版 Reporting API (v0) 获取 CSP(Content-Security-Policy
标头)的违规行为报告,则可能需要在迁移到新版 Reporting API (v1) 的过程中调整 Content-Security-Policy
。
基本迁移
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"
请注意,使用 v1 版本,您仍然可以将特定报告类型发送到特定端点。但每个端点只能有一个网址。
观察所有页面
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(...) });
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: ...
深入阅读
- 使用 Reporting API 监控 Web 应用(关于 Reporting API 的主要博文)
- 规范:旧版 Reporting API (v0)
- 规范:新的 Reporting API (v1)
主打图片,创作者:Nine Koepfer / @enka80 在 Unsplash 用户,已编辑。非常感谢 Ian Clelland、Eiji Kitamura 和 Milica Mihajlija 对本文的评价和建议。