Reporting API

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

• 内容安全策略 违规。
• 权限策略 违规。
• 已弃用功能的使用（当您使用浏览器中很快将停止工作的内容时）。
• 崩溃事件的发生。
• 用户代理干预事件的发生（例如，当浏览器阻止您的代码尝试执行的操作，因为它被认为是安全风险，或者仅仅是令人讨厌的操作，如自动播放音频）。

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

您要获取报告的每个唯一来源都可以有一系列“端点”，这些端点是命名的 URL（或 URL 组），用户代理可以向其发送报告。这些端点上的报告服务器可以收集报告，并根据您的应用程序需要对其进行处理和呈现。

使用 Reporting-Endpoints HTTP 头来指定用户代理可用于传递报告的不同端点的详细信息。然后，可以在特定的 HTTP 响应头中使用 report-to 指令来指示将用于关联报告的特定端点。例如，可以在 Content-Security-Policy 或 Content-Security-Policy-Report-Only HTTP 头中使用 CSP report-to 指令来指定应将 CSP 违规报告发送到的端点。

报告本身由用户代理通过 POST 操作发送到目标端点，Content-Type 为 application/reports+json。它们是 Report 对象的序列化，其中 type 指示报告的类型，url 指示报告的来源，body 包含与报告类型相对应的 API 接口的序列化。例如，CSP 违规报告的 type 为 csp-violation，body 是 CSPViolationReportBody 对象的序列化。

发送到端点的报告可以独立于与其相关的网站的运行进行检索，这很有用——例如，崩溃可能会使网站崩溃并停止任何运行，但仍然可以获取报告，以便为开发人员提供一些关于其发生原因的线索。

报告也可以通过 ReportingObserver 对象获得，这些对象是通过您要获取报告的网站内部的 JavaScript 创建的。此方法不如将报告发送到服务器可靠，因为任何页面崩溃都可能阻止您检索报告——但它更容易设置，并且更灵活。

使用 ReportingObserver() 构造函数创建一个 ReportingObserver 对象，该构造函数传递两个参数

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

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

发送到报告端点和报告观察器的报告本质上是相同的：它们都有一个来源 url、一个 type 和一个 body，该 body 是与该类型相对应的接口的实例。唯一的区别是服务器报告是对象的 JSON 序列化。

报告 type 到 body 的映射如下所示。

Reporting API 规范还定义了一个生成测试报告 WebDriver 扩展，允许您在自动化过程中模拟报告生成。通过 WebDriver 生成的报告由加载的网站中存在的任何已注册的 ReportObserver 对象观察。这还没有记录。

DeprecationReportBody

包含网站正在使用的已弃用 Web 平台功能的详细信息。

InterventionReportBody

包含干预报告的详细信息，该报告是在网站发出的请求被浏览器拒绝时生成的；例如，出于安全原因。

Report

表示单个报告的对象。

ReportingObserver

一个可以用于收集和访问生成报告的对象。

这些接口在 HTTP 内容安全策略 (CSP) 规范中定义

CSPViolationReportBody

包含 CSP 违规的详细信息。

SecurityPolicyViolationEvent

表示在元素、文档或工作程序的 CSP 被违反时在其上触发的 securitypolicyviolation 事件的事件对象。

这些 HTTP 响应头定义了发送报告的端点。

Reporting-Endpoints

设置报告端点的名称和 URL。这些可以在 report-to 指令中使用，该指令可与许多 HTTP 头一起使用，包括 Content-Security-Header。

Report-To 已弃用

设置报告端点组的名称和 URL，这些端点组可与许多 HTTP 头一起使用，包括 Content-Security-Header。

可以使用相应头上的 report-to 指令为以下报告设置报告端点

CSP 违规

report-to 在 Content-Security-Policy 或 Content-Security-Policy-Report-Only 上。

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

const options = {
  types: ["deprecation"],
  buffered: true,
};

const observer = new ReportingObserver((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() 构造函数内部设置的事件处理程序，我们现在可以单击按钮来显示报告详细信息。

目前支持处于早期阶段。Firefox 支持 JavaScript API 和 Report-To 头，但需要通过首选项启用

• JavaScript API：dom.reporting.enabled（仅在 nightly 版本中启用）
• HTTP 头：dom.reporting.header.enabled

Chrome 也正在开发实现：有关 Chrome 实现的信息。

• 内容安全策略
• 权限策略