迁移到 Reporting API v1

Reporting API 已推出新版本。这种方式更加注重隐私保护，并且更有可能在各浏览器中得到支持。

Maud Nalpas

Reporting API 会告知您访问者在使用它时您的网站上发生的错误。借助此工具，您可以了解浏览器干预、浏览器崩溃、违反内容安全政策、COOP/COEP 违规行为、弃用警告等。

Reporting API 已发布新版本。新 API 更加精简，更有可能获得跨浏览器支持。

摘要

网站开发者

如果您的网站已有报告功能：请使用新标头 (Reporting-Endpoints) 迁移到 v1，但将旧版标头保留一段时间 (Report-To)。请参阅迁移：示例代码。

如果您正在向网站添加报告功能：请仅使用新标头 (Reporting-Endpoints)。

⚠️ 在这两种情况下，请务必为可能生成报告的所有响应设置 Reporting-Endpoints 标头。

报告服务开发者

如果您正在维护端点服务或自行运营，那么随着您或外部开发者迁移到 Reporting API v1（Reporting-Endpoints 标头），预计流量会更多。

请继续阅读以了解详情和示例代码！

网络错误日志记录

我们将开发一种新的网络错误日志记录机制。在该机制可用后，请从 Reporting API v0 切换到该新机制。

演示和代码

• 演示网站：新的 Reporting API (v1)
• 演示网站的代码

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

• 报告范围不同。

• 这两种 API 支持相同的报告类型，但有一个例外：v1 不支持网络错误报告。如需了解详情，请参阅迁移步骤。
• 目前没有跨浏览器支持 v0，以后也不会支持 v0。将来，我们更有可能在多个浏览器中支持 v1。

保持不变的内容

• 报告的格式和结构保持不变。
• 浏览器向端点发送的请求仍然是 Content-type application/reports+json 的 POST 请求。
• v0 和 v1 均支持将某些端点映射到特定报告类型。
• default 端点的角色保持不变。

• Reporting API v1 对 ReportingObserver 没有任何影响。ReportingObserver 可继续访问所有可观察报告，其格式相同。

v0 和 v1 之间的所有差异

终端开发者：预计流量会更多

如果您已将自己的服务器设置为报告端点，或者正在将报告收集器作为一项服务进行开发或维护，则预计该端点会获得更多流量。

这是因为使用 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. 第 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. 第 2 步（立即行动）：确保已针对可能生成报告的所有响应设置 Reporting-Endpoints 标头。

   使用 v0 时，您可以选择仅针对某些响应设置报告端点，该来源上的其他文档（页面）将使用此“环境”端点。使用 v1 时，由于范围不同，您需要在可能生成报告的所有响应中设置 Reporting-Endpoints 标头。

3. 第 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. 第 1 步（立即行动）：如果您尚未添加，请在 report-uri 旁边添加 report-to。仅支持 report-uri 的浏览器 (Firefox) 将使用 report-uri，同样支持 report-to 的浏览器（Chrome、Edge）将使用 report-to。如需指定将在 report-to 中使用的命名端点，请同时使用标头 Report-To 和 Reporting-Endpoints。这样可以确保您从旧版和新版 Chrome 和 Edge 客户端都能获取报告。

2. 第 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 对本文的评价和建议。