Reporting API - 为 Web 应用程序提供通用报告机制

Reporting API（报告 API）为 Web 应用程序提供通用报告机制，用于以一致的方式基于各种平台功能（例如 Content Security Policy、Feature-Policy或功能弃用报告）提供报告。

概念和用法

Web 平台上有许多不同的功能和问题，它们会在 Web 开发人员尝试修复错误或以其他方式改进其网站时生成有用的信息。此类信息可包括：

• 违反 Content Security Policy。
• 违反 Feature-Policy。
• 不推荐使用的功能（当您使用将很快在浏览器中停止工作的东西时）。
• 发生崩溃。
• 发生用户代理干预（当浏览器阻止您的代码尝试执行的操作，因为它被认为是安全风险，或者只是令人讨厌，例如自动播放音频）。

报告 API 的目的是提供一致的报告机制，可用于以 JavaScript 对象表示的报告的形式向开发人员提供此类信息。有几种使用它的方法，在下面的部分中进行了详细介绍。

源和端点

您要为其检索报告的每个唯一来源都可以提供一系列端点，这些端点是可以从用户代理接收给定报告的 URL。

Report-To HTTP 标头用于指定有关用户代理可用于向其提供报告的不同端点的详细信息。然后，您可以通过向这些 URL 发出请求来检索报告。

端点被分组；端点组可以协同工作，以提供负载平衡（每个端点将接收指定比例的报告流量）和防止故障（可以指定在主要端点故障时使用后备端点）。

注意： 没有绝对保证报告送达 —— 如果发生严重错误，仍然可能无法收集报告。

可以独立于与它们相关的网站的运行来检索发送到端点的报告。这很有用 —— 例如，崩溃可能会导致网站下线并停止任何运行，但仍可以通过其他网址向开发人员发送报告。

报告观察者

报告也可以通过您要获取报告的网站内通过 JavaScript 创建的 ReportingObserver 对象获取。这种方法不像上面描述的 Report-To 方法那样安全 —— 任何页面崩溃都可能阻止你检索报告 —— 但它更容易设置，也更灵活。

ReportingObserver 对象是使用 ReportingObserver() 构造函数创建的，它传递了两个参数：

• 一个回调函数，它具有观察者报告队列中可用报告的参数，以及相同的 ReportingObserver 对象的副本，因此可以直接从回调内部控制观察。观察开始时就运行回调
• 一个选项字典，允许您指定要收集的报告类型，以及在观察者能够被创建之前生成的报告是否应该是可观察的（ buffered: true ）。

然后观察者可以使用方法开始收集报告（ReportingObserver.observe()），检索当前在报告队列中的报告（ReportingObserver.takeRecords()），并断开观察者的连接，使其不再收集记录（ReportingObserver.disconnect()）。

通过 WebDriver 生成报告

报告 API 规范还定义了生成测试报告 WebDriver 扩展，它允许您在自动化期间模拟报告生成。通过 WebDriver 生成的报告被任何在加载的网站中注册的 ReportObserver 对象观察。

Reporting API 接口

ReportingObserver

使用其构造函数创建 ReportingObserver 实例，然后可用于收集和访问报告。

Report

表示单个报告的对象。

Reporting API 字典

ReportingObserverOptions

允许在创建报告观察者时在构造函数中设置的选项。

可用的报告类型

该规范定义了以下报告类型：

弃用报告

表示网站中使用的 WebAPI 或其他浏览器功能预计将在未来版本中停止工作。Report.body 属性的值为 DeprecationReportBody。

干预报告

表示网站发出的请求已被浏览器拒绝，例如出于安全或用户烦恼的原因。Report.body 属性的值为 InterventionReportBody。

崩溃报告

表示网站因浏览器崩溃而停止运行。Report.body 属性的值为 CrashReportBody。

实例

在我们的 deprecation_report.html 实例中，我们创建了一个简单的报告观察器来观察我们网页上已弃用功能的使用情况：

let options = {
  types: ['deprecation'],
  buffered: true
}

let observer = new ReportingObserver(function(reports, observer) {
  reportBtn.onclick = () => displayReports(reports);
}, options);

然后我们告诉它使用 ReportingObserver.observe()；开始观察报告。这告诉观察者开始在其报告队列中收集报告，并运行构造函数中指定的回调函数：

observer.observe();

稍后在实例中，我们故意使用已弃用的 MediaDevices.getUserMedia() 版本：

if(navigator.mozGetUserMedia) {
  navigator.mozGetUserMedia(
    constraints,
    success,
    failure);
} else {
  navigator.getUserMedia(
    constraints,
    success,
    failure);
}

这会导致生成弃用报告；由于我们在 ReportingObserver() 构造函数中设置了事件处理程序，我们现在可以单击按钮来显示报告详细信息。

注意： 如果您查看完整源代码，您会注意到我们实际上两次调用已弃用的 getUserMedia() 方法。第一次之后我们调用 ReportingObserver.takeRecords()，它返回第一个生成的报告并清空队列。因此，当按下按钮时，只会列出第二个报告。

规范

规范	状态	备注
Reporting API spec	-	-

浏览器兼容性

支持目前处于早期阶段。Firefox 支持 JavaScript API 和 prefs 后面的 Report-To 标头：

• JavaScript API: dom.reporting.enabled（仅在夜间构建中启用）
• HTTP 标头: dom.reporting.header.enabled

Chrome 也在实现中：有关 Chrome 实现的信息。

相关链接

• Content Security Policy
• Feature-Policy