Reporting API
概念和用法
来源和端点
可以为希望检索报告的每个唯一来源提供一系列端点,这些端点是可以从用户代理接收给定报告的 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
对象观察。这还没有相关文档记录。
接口
CSPViolationReportBody
-
包含违反内容安全策略的详细信息。
DeprecationReportBody
-
包含网站正在使用的已弃用的 web 平台特性的详细信息。
InterventionReportBody
-
包含干预报告的详细信息,该报告是在网站发出的请求被浏览器拒绝时生成的(例如:出于安全考虑)。
Report
-
表示单个报告的对象。
ReportingObserver
-
一个对象,可用于在报告生成时收集和访问报告。
示例
在我们的 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()
构造函数中设置了事件处理器,现在可以单击按钮来显示报告的详细信息。
备注:如果你查看完整的源代码,你将注意到我们调用了两次 getUserMedia()
方法。在我们第一次调用 ReportingObserver.takeRecords()
之后,它返回第一个生成的报告并清空队列。因此,当按下该按钮时,只会列出第二个报告。
规范
Specification |
---|
Reporting API # intro |
Content Security Policy Level 3 # cspviolationreportbody |
Deprecation Reporting # deprecationreportbody |
Intervention Reporting # intervention-report |
浏览器兼容性
目前浏览器的支持还处于早期阶段。Firefox 通过首选项来提供对 JavaScript API 和 Report-To
标头的支持:
- JavaScript API:
dom.reporting.enabled
(仅在 Nightly 版本中可用) - HTTP 标头:
dom.reporting.header.enabled
Chrome 浏览器也在逐步实现该特性:有关 Chrome 实现的信息。