Reporting API 已推出新版本。它具有更高的私密性,更有可能在各个浏览器上受支持。
当访问者使用您的网站时,Reporting API 会通知您。它提供 了解浏览器干预、浏览器崩溃、内容安全政策 COOP/COEP 违规、弃用警告等。
Reporting API 已推出新版本。新 API 更精简, 对各种浏览器的支持。
摘要
网站开发者
如果您的网站已有报告功能:请使用新标头迁移到 v1
(Reporting-Endpoints
),但将旧版标头保留一段时间 (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
{0 使用 Report-To
标头配置已命名的端点组,并使用其他标头中的 report-to
指令引用这些端点组。
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default" Document-Policy: ...; report-to main-endpoint
v1 使用 Reporting-Endpoints
标头来配置命名的
endpoints。与 v0 一样,它在其他标头中使用 report-to
指令来引用这些端点组。
- 此报告的范围有所不同。
使用 v0 时,您只能为某些响应设置报告端点。有关该组织的其他文档(页面) 来源会自动使用这些 Ambient 端点。
对于 v1,您需要在可能会生成的所有响应上设置 Reporting-Endpoints
标头
报告。
- 两个 API 支持相同的报告类型,但有一个例外:v1 不支持网络错误报告。如需了解详情,请参阅迁移步骤。
- v0 目前不受所有浏览器支持,以后也不会受到支持。版本 1 更有可能在 支持多种浏览器
保持不变的方面
- 报告的格式和结构保持不变。
- 浏览器向端点发送的请求仍为
Content-type
的POST
请求application/reports+json
。 - 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 v0 那样使用 Reporting API v1 批量处理报告。因此, 随着应用开发者开始迁移到 Reporting API v1,报告数量将 但向端点服务器发送的请求数量会增加。
应用开发者:迁移至 Reporting-Endpoints
(v1)
您该怎么做?
使用新的 Reporting API (v1) 有诸多好处 ✅:
- 浏览器信号为正值,这意味着 v1 预计会实现跨浏览器支持(这与仅 Chrome 浏览器和 Edge)。
- API 更加精简。
- 我们正在围绕新的 Reporting API (v1) 开发工具。
了解了这一点:
- 如果您的网站已在使用带有
Report-To
标头的 Reporting API v0,请迁移到 Reporting API v1(请参阅迁移步骤)。如果您的网站已使用 有关内容安全政策违规行为的报告功能,请参阅具体的 CSP 报告迁移步骤。 - 如果您的网站尚未使用 Reporting API,而您现在要添加报告功能,请执行以下操作:
使用新的 Reporting API (v1)(
Reporting-Endpoints
标头)。有一个例外情况 this:如果您需要使用网络错误日志记录,请使用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 客户端能够提供报告。 - 旧版 Chrome 和 Edge 客户端可通过
Report-To
(v0) 提供的报告获取服务。
支持
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 报告的迁移步骤
Content-Security-Policy有两种方法 违规报告:
- 通过
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
。
因此,建议您在 Reporting API 方法 (Report-To
) 的同时还使用 report-uri
或 Reporting-Endpoints
),才能从多个浏览器获取 CSP 违规报告。在
可识别 report-uri
和 report-to
的浏览器,如果 report-to
,则系统将忽略 report-uri
。在仅识别 report-uri
的浏览器中,将仅考虑 report-uri
。
第 1 步(立即执行):如果您尚未添加,请添加
report-to
以及report-uri
。 仅支持report-uri
的浏览器 (Firefox) 将使用report-uri
,同时 支持report-to
(Chrome、Edge)将使用report-to
。要指定已命名的端点 在report-to
中,同时使用头文件Report-To
和Reporting-Endpoints
。这可确保您获得 报告。第 3 步(稍后开始):当所有或大多数用户更新到更高版本的 Chrome 或 Edge 后 安装(96 及更高版本),移除了
Report-To
(v0),仅保留Reporting-Endpoints
。保留report-uri
,因此您仍会收到关于只支持它的浏览器的报告。
如需了解这些步骤的代码示例,请参阅 CSP 报告迁移。
迁移:示例代码
概览
如果您使用的是旧版 Reporting API (v0) 来获取 COOP 的违规报告
(Cross-Origin-Opener-Policy
标头)、COEP (Cross-Origin-Embedder-Policy
) 或文档政策
(Document-Policy
header):迁移时,您无需自行更改这些政策标头
升级到 Reporting API v1。您只需从旧版 Report-To
标头迁移到新版
Reporting-Endpoints
标头。
如果您使用的是旧版 Reporting API (v0) 来获取 CSP 的违规报告
(Content-Security-Policy
标头),您可能需要调整 Content-Security-Policy
作为
向新的 Reporting API (v1) 迁移。
基本迁移
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" }] }
如果您的网站中已有报告功能,请仅暂时保留 Report-To
(直到大多数 Chrome 和 Edge 客户端完成更新),以免丢失报告。
如果您需要网络错误日志记录,请保留Report-To
直到更换网络错误日志记录
可用。
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
在大多数 Chrome 和 Edge 客户端都已更新并支持 API v1 后,您的代码将如下所示。
请注意,使用 v1 时,您仍然可以向特定端点发送特定报告类型。但你 每个端点只能有一个网址。
观察所有网页
app.get("/", (request, response) => { response.set("Report-To", …) response.render(...) }); app.get("/page1", (request, response) => { response.render(...) });
使用 v0 时,您只能为某些响应设置报告端点。其他
该来源上的文档(网页)会自动使用这些 Ambient 端点。在这里,设置的端点
for "/"
用于所有响应,例如 page1
。
// 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(...) });
对于 v1,您需要在所有网页上设置 Reporting-Endpoints
标头
可能生成报告的响应。
CSP 报告迁移
Content-Security-Policy: ...; report-uri https://reports.example/main
不再支持仅使用 report-uri
(推荐)。
如果您的代码如上所示,请进行迁移。请参阅下面的新代码示例(以绿色显示)。
Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint Report-To: main-endpoint="https://reports.example/main"
代码使用效果较好:此代码使用报告对象,是较新的
report-uri。它仍会保留 report-uri,以确保向后兼容;若干
浏览器不支持
report-to
但支持
report-uri
。
尽管如此,还是会有改进空间:此代码使用 Reporting API v0(Report-To
标头)。迁移到 v1:请参阅
“新验证码”示例如下(以绿色显示)。
Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint Reporting-Endpoints: main-endpoint="https://reports.example/main" Report-To: ...
请保留 report-uri
指令和 report-to
指令,直到 report-to
指令为止
。有关详情,请参阅浏览器兼容性
表格。
暂时将Report-To
与Reporting-Endpoints
放在一起。在 Chrome 和 Edge 中,
位访问者已将浏览器版本升级到 96 以上,请移除 Report-To
。
深入阅读
- 使用 Reporting API 监控 Web 应用(Reporting API 上的主帖子)
- 规范:旧版 Reporting API (v0)
- 规范:新版 Reporting API (v1)
主打图片作者:Nine Koepfer / @enka80 Unlaunch,已修改。非常感谢 Ian Clelland、Eiji Kitamura 和 Milica Mihajlija 一文。