Reporting API

Es gibt mehrere verschiedene Merkmale und Probleme in der Webplattform, die Informationen erzeugen, die für Webentwickler nützlich sind, wenn sie versuchen, Fehler zu beheben oder ihre Websites anderweitig zu verbessern. Solche Informationen können Folgendes umfassen:

• Verstöße gegen die Content Security Policy.
• Verstöße gegen die Permissions-Policy.
• Verwendung eingestellter Funktionen (wenn Sie etwas verwenden, das bald in Browsern nicht mehr funktionieren wird).
• Auftreten von Abstürzen.
• Auftreten von Benutzeragenten-Interventionen (wenn der Browser etwas blockiert, das Ihr Code auszuführen versucht, weil es beispielsweise als Sicherheitsrisiko angesehen wird oder einfach nur störend ist, wie das automatische Abspielen von Audio).

Der Zweck der Reporting API ist es, einen konsistenten Reporting-Mechanismus bereitzustellen, der verwendet werden kann, um Entwicklern solche Informationen in Form von Berichten zugänglich zu machen, die durch JavaScript-Objekte repräsentiert werden. Es gibt einige Möglichkeiten, sie zu verwenden, die in den folgenden Abschnitten detailliert beschrieben werden.

Jeder eindeutige Ursprung, für den Sie Berichte erhalten möchten, kann eine Reihe von "Endpunkten" erhalten, bei denen es sich um benannte URLs (oder Gruppen von URLs) handelt, die Berichte von einem Benutzeragenten empfangen können. Ein Reporting-Server an diesen Endpunkten kann die Berichte sammeln, verarbeiten und entsprechend den Anforderungen Ihrer Anwendung präsentieren.

Der Reporting-Endpoints HTTP-Header wird verwendet, um Details über die verschiedenen Endpunkte anzugeben, die einem Benutzeragenten für die Bereitstellung von Berichten zur Verfügung stehen. Die report-to-Direktive kann dann in bestimmten HTTP-Antwortheadern verwendet werden, um den spezifischen Endpunkt anzugeben, der für den zugehörigen Bericht verwendet wird. Zum Beispiel kann die report-to-Direktive in den HTTP-Headern Content-Security-Policy oder Content-Security-Policy-Report-Only verwendet werden, um den Endpunkt anzugeben, an den CSP-Verletzungsberichte gesendet werden sollen.

Die Berichte selbst werden durch den Benutzeragenten in einer POST-Operation mit einem Content-Type von application/reports+json an den Zielendpunkt gesendet. Sie sind Serialisierungen von Report-Objekten, wobei type den Berichtsart angibt, url den Ursprung des Berichts angibt und body eine Serialisierung der API-Schnittstelle enthält, die dem Berichtstyp entspricht. Zum Beispiel haben CSP-Verletzungsberichte einen type von csp-violation und einen body, der eine Serialisierung eines CSPViolationReportBody-Objekts ist.

Berichte, die an Endpunkte gesendet werden, können unabhängig vom Betrieb der Websites abgerufen werden, auf die sie sich beziehen, was nützlich ist — ein Absturz könnte beispielsweise eine Website zum Erliegen bringen und alles zum Stillstand bringen, aber ein Bericht könnte trotzdem abgerufen werden, um dem Entwickler einige Hinweise zu geben, warum es passiert ist.

Berichte können auch über ReportingObserver-Objekte abgerufen werden, die über JavaScript innerhalb der Website erstellt werden, auf der Sie Berichte erhalten möchten. Diese Methode ist nicht so ausfallsicher wie das Senden von Berichten an den Server, da jede Seitenerstörung Sie daran hindern könnte, die Berichte abzurufen — aber sie ist einfacher einzurichten und flexibler.

Ein ReportingObserver-Objekt wird mithilfe des ReportingObserver() Konstruktors erstellt, dem zwei Parameter übergeben werden:

• Eine Callback-Funktion mit zwei Parametern — ein Array der in der Beobachter-Warteschlange verfügbaren Berichte und eine Kopie desselben ReportingObserver-Objekts, die die Beobachtung direkt innerhalb des Callbacks steuern ermöglicht. Der Callback wird ausgeführt, wenn die Beobachtung beginnt.
• Ein Optionswörterbuch, das es Ihnen ermöglicht, den Typ der zu sammelnden Berichte anzugeben und ob Berichte, die vor der Erstellung des Beobachters generiert wurden, sichtbar sein sollen (buffered: true).

Methoden stehen dann im Beobachter zur Verfügung, um Berichte zu sammeln (ReportingObserver.observe()), die Berichte in der aktuellen Warteschlange abzurufen (ReportingObserver.takeRecords()) und den Beobachter zu trennen, sodass er keine Berichte mehr sammeln kann (ReportingObserver.disconnect()).

Berichte, die an Reporting-Endpunkte und Reporting-Beobachter gesendet werden, sind im Wesentlichen dasselbe: Sie haben eine Ursprungs-url, einen type und einen body, der eine Instanz der Schnittstelle ist, die diesem Typ entspricht. Der einzige Unterschied besteht darin, dass Serverberichte JSON-Serialisierungen der Objekte sind.

Die Zuordnung von Berichtstyp type zu body ist unten gezeigt.

Die Reporting API-Spezifikation definiert auch eine Generate Test Report WebDriver-Erweiterung, die es Ihnen ermöglicht, die Berichtserstellung während der Automatisierung zu simulieren. Über WebDriver generierte Berichte werden von allen registrierten ReportObserver-Objekten beobachtet, die auf der geladenen Website vorhanden sind. Dies ist noch nicht dokumentiert.

DeprecationReportBody

Enthält Details zu abgekündigten Webplattformfunktionen, die eine Website verwendet.

InterventionReportBody

Enthält Details zu einem Interventionsbericht, der erstellt wird, wenn eine Anfrage der Website durch den Browser abgelehnt wurde, z.B. aus Sicherheitsgründen.

Report

Ein Objekt, das einen einzelnen Bericht darstellt.

ReportingObserver

Ein Objekt, das verwendet werden kann, um Berichte zu sammeln und darauf zuzugreifen, sobald sie erstellt werden.

Diese Schnittstellen sind Teil der HTTP Content Security Policy (CSP)-Spezifikationen definiert:

CSPViolationReportBody

Enthält Details zu einem CSP-Verstoß.

SecurityPolicyViolationEvent

Repräsentiert das Ereignisobjekt eines securitypolicyviolation-Ereignisses, das auf einem Element, Dokument oder Worker ausgelöst wird, wenn seine CSP verletzt wird.

Diese HTTP-Antwortheader definieren die Endpunkte, an die Berichte gesendet werden.

Reporting-Endpoints

Setzt den Namen und die URL von Reporting-Endpunkten. Diese Endpunkte können in der report-to-Direktive verwendet werden, die bei einer Reihe von HTTP-Headern inklusive Content-Security-Policy und oder Content-Security-Policy-Report-Only genutzt werden kann.

Report-To Veraltet

Setzt den Namen und die URL von Gruppen von Reporting-Endpunkten, die bei einer Reihe von HTTP-Headern inklusive Content-Security-Policy genutzt werden können.

Berichts-Endpunkte können für die folgenden Berichte mithilfe der report-to-Direktive auf den entsprechenden Headern festgelegt werden:

CSP-Verstöße

report-to auf Content-Security-Policy oder Content-Security-Policy-Report-Only.

In unserem Beispiel deprecation_report.html erstellen wir einen einfachen Reporting-Beobachter, um die Nutzung von eingestellten Funktionen auf unserer Webseite zu beobachten:

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

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

Wir sagen ihm dann, dass er anfangen soll, Berichte zu beobachten, indem wir ReportingObserver.observe() verwenden; dies teilt dem Beobachter mit, dass er anfängt, Berichte in seiner Berichtswarteschlange zu sammeln, und führt die im Konstruktor angegebene Callback-Funktion aus:

observer.observe();

Später im Beispiel verwenden wir absichtlich die veraltete Version von MediaDevices.getUserMedia():

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

Dies führt dazu, dass ein Abkündigungsbericht erstellt wird; aufgrund des Event-Handlers, den wir im ReportingObserver()-Konstruktor eingerichtet haben, können wir jetzt auf die Schaltfläche klicken, um die Berichtdetails anzuzeigen.

Die API wird von Chromium-Browsern unterstützt und in Firefox hinter einer Präferenz (dom.reporting.enabled).

Für detailliertere Support-Informationen siehe die spezifischen Schnittstellen.

• Content Security Policy
• Permissions-Policy