Reporting API

可用性有限

此特性不是基線特性，因為它在一些最廣泛使用的瀏覽器中不起作用。

注意：此功能在 Web Workers 中可用。

Reporting API 提供了一種通用的報告機制，供 Web 應用程式使用，以便以一致的方式提供基於各種平臺功能（例如 Content Security Policy、Permissions-Policy 或功能棄用報告）的報告。

概念與用法

Web 平臺上有許多不同的功能和問題會生成對 Web 開發者有用的資訊，當他們嘗試修復 bug 或以其他方式改進其網站時。此類資訊可包括：

Content Security Policy 違規。
Permissions-Policy 違規。
Integrity-Policy 違規。
棄用功能使用（當您使用將在瀏覽器中很快停止工作的某些功能時）。
崩潰事件。
使用者代理干預事件（當瀏覽器阻止您的程式碼嘗試執行的某些操作時，例如，因為它被認為存在安全風險，或者只是令人討厭，例如自動播放音訊）。

Reporting API 的目的是提供一個一致的報告機制，該機制可用於以 JavaScript 物件表示的報告形式向開發人員提供此類資訊。有幾種使用方法，將在下面的章節中詳細介紹。

報告伺服器端點

您想獲取報告的每個唯一源都可以被賦予一系列“端點”，這些端點是命名 URL（或 URL 組），可以從中傳送使用者代理報告。這些端點上的報告伺服器可以收集報告，並根據您的應用程式需要進行處理和呈現。

Reporting-Endpoints HTTP 標頭用於指定使用者代理可用的用於傳遞報告的不同端點的詳細資訊。然後，可以在特定的 HTTP 響應標頭上使用 report-to 指令來指示將用於關聯報告的特定端點。例如，CSP report-to 指令可以在 Content-Security-Policy 或 Content-Security-Policy-Report-Only HTTP 標頭上使用，以指定應將 CSP 違規報告發送到的端點。

注意：報告的傳遞沒有絕對保證——如果發生嚴重錯誤，報告仍可能無法收集。

報告本身透過使用者代理在 POST 操作中以 application/reports+json 的 Content-Type 傳送到目標端點。它們是 Report 物件的序列化，其中 type 指示報告型別，url 指示報告來源，body 包含與報告型別對應的 API 介面的序列化。例如，CSP 違規報告的 type 為 csp-violation，body 是 CSPViolationReportBody 物件的序列化。

傳送到端點的報告可以獨立於其相關的網站執行來檢索，這很有用——例如，崩潰可能會導致網站宕機並停止執行任何內容，但仍然可以獲得報告，為開發人員提供有關其原因的線索。

報告觀察者

報告還可以透過在您要獲取報告的網站內部透過 JavaScript 建立的 ReportingObserver 物件來獲取。此方法不如傳送到伺服器的報告安全，因為任何頁面崩潰都可能阻止您檢索報告——但它更容易設定，並且更靈活。

ReportingObserver 物件使用 ReportingObserver() 建構函式建立，該建構函式接收兩個引數：

一個帶有兩個引數的回撥函式——一個是由觀察者報告佇列中可用的報告組成的陣列，以及該 ReportingObserver 物件的一個副本，這允許直接從回撥函式內部控制觀察。觀察開始時執行回撥函式。
一個選項字典，允許您指定要收集的報告型別，以及是否應觀察在觀察者建立之前生成的報告（buffered: true）。

然後可以使用觀察者上的方法來開始收集報告（ReportingObserver.observe()），檢索報告佇列中當前的報告（ReportingObserver.takeRecords()），以及斷開觀察者連線，使其不再收集記錄（ReportingObserver.disconnect()）。

報告型別

傳送到報告端點和報告觀察者的報告基本相同：它們都有一個源 url，一個 type，以及一個 body，它是與該型別對應的介面的例項。唯一區別是伺服器報告是物件的 JSON 序列化。

報告 type 到 body 的對映如下所示。

`type`	`body`	報告專案
`棄用`	`DeprecationReportBody`	網站使用的已棄用功能。
`integrity-violation`	`IntegrityViolationReportBody`	頁面完整性策略的違規。
`intervention`	`InterventionReportBody`	使用者代理阻止的功能，例如，未授予許可權時。
`csp-violation`	`CSPViolationReportBody`	網站 CSP 策略的違規。

透過 WebDriver 生成報告

Reporting API 規範還定義了一個“生成測試報告” WebDriver 擴充套件，它允許您在自動化過程中模擬報告生成。透過 WebDriver 生成的報告會被載入網站中存在的任何已註冊 ReportObserver 物件觀察。這尚未記錄。

介面

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() 建構函式中設定了事件處理程式，我們現在可以單擊按鈕來顯示報告詳細資訊。

image of a jolly bearded man with various stats displayed below it about a deprecated feature