Reporting API

Es gibt mehrere unterschiedliche Funktionen und Probleme auf 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 beinhalten:

• Verstöße gegen die Content Security Policy.
• Verstöße gegen die Permissions-Policy.
• Verwendung veralteter Funktionen (wenn Sie etwas verwenden, das bald in Browsern nicht mehr funktionieren wird).
• Auftreten von Abstürzen.
• Auftreten von Eingriffen des Benutzeragenten (wenn der Browser etwas blockiert, das Ihr Code versucht, weil es zum Beispiel als Sicherheitsrisiko angesehen wird oder einfach nur störend ist, wie automatisch abspielendes Audio).

Der Zweck der Reporting API ist es, einen konsistenten Mechanismus bereitzustellen, der verwendet werden kann, um solche Informationen Entwicklern in Form von Berichten zur Verfügung zu stellen, die durch JavaScript-Objekte dargestellt werden. Es gibt einige Möglichkeiten, sie zu verwenden, die in den folgenden Abschnitten detailliert beschrieben sind.

Jeder eindeutige Ursprung, für den Sie Berichte erhalten möchten, kann eine Reihe von "Endpunkten" erhalten, die benannten URLs (oder Gruppen von URLs) entsprechen, an die ein Benutzeragent Berichte senden kann. Ein Reporting-Server an diesen Endpunkten kann die Berichte sammeln und sie gemäß den Anforderungen Ihrer Anwendung verarbeiten und präsentieren.

Der Reporting-Endpoints HTTP-Header wird verwendet, um Details über die verschiedenen Endpunkte zu spezifizieren, die einem Benutzeragenten zur Verfügung stehen, um Berichte zu liefern. 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 CSP report-to-Direktive in den Content-Security-Policy oder Content-Security-Policy-Report-Only HTTP-Headern verwendet werden, um den Endpunkt anzugeben, an den CSP-Verletzungsberichte gesendet werden sollen.

Die Berichte selbst werden vom Benutzeragenten in einer POST-Operation mit einem Content-Type von application/reports+json an den Zielendpunkt gesendet. Sie sind Serialisierungen von Report-Objekten, wobei der type den Berichtstyp angibt, die url den Ursprung des Berichts angibt und der 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 von der Ausführung der Websites, auf die sie sich beziehen, abgerufen werden, was nützlich ist – ein Absturz könnte zum Beispiel eine Website zum Absturz bringen und alles zum Stillstand bringen, aber ein Bericht könnte dennoch erhalten werden, um dem Entwickler Hinweise zu geben, warum er aufgetreten ist.

Berichte können auch über ReportingObserver-Objekte abgerufen werden, die über JavaScript innerhalb der Website erstellt werden, für die Sie Berichte erhalten möchten. Diese Methode ist nicht so ausfallsicher wie das Senden von Berichten an den Server, da jeder Seitenabsturz verhindern könnte, dass Sie die Berichte abrufen — aber es ist einfacher einzurichten und flexibler.

Ein ReportingObserver-Objekt wird mit dem ReportingObserver()-Konstruktor erstellt, dem zwei Parameter übergeben werden:

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

Methoden sind dann am Beobachter verfügbar, um Berichte zu sammeln (ReportingObserver.observe()), die derzeit in der Berichte-Warteschlange befindlichen Berichte abzurufen (ReportingObserver.takeRecords()) und den Beobachter zu trennen, damit er keine Aufzeichnungen mehr sammeln kann (ReportingObserver.disconnect()).

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

Die Zuordnung von Bericht type zu body ist unten dargestellt.

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

DeprecationReportBody

Enthält Details zu veralteten Webplattformfunktionen, die eine Website verwendet.

InterventionReportBody

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

Report

Ein Objekt, das einen einzelnen Bericht repräsentiert.

ReportingObserver

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

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

CSPViolationReportBody

Enthält Details zu einer CSP-Verletzung.

SecurityPolicyViolationEvent

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

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

Reporting-Endpoints

Legt den Namen und die URL von Reporting-Endpunkten fest. Diese Endpunkte können in der report-to-Direktive verwendet werden, die mit einer Reihe von HTTP-Headern verwendet werden kann, einschließlich Content-Security-Policy oder Content-Security-Policy-Report-Only.

Report-To Veraltet

Ist nicht mehr Teil der Reporting API, wird jedoch weiterhin von einigen Browsern unterstützt. Dies legt den Namen und die URL von Gruppen von Reporting-Endpunkten fest, die mit einer Reihe von HTTP-Headern verwendet werden können, insbesondere für Network Error Logging, das noch nicht aktualisiert wurde, um Reporting-Endpoints zu unterstützen. Andere Reporting API-Berichte sollten stattdessen Reporting-Endpoints verwenden, um zukünftige Unterstützung zu verbessern.

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

CSP-Verletzungen

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

In unserem deprecation_report.html Beispiel erstellen wir einen einfachen Reporting-Observer, um die Verwendung veralteter Funktionen auf unserer Webseite zu beobachten:

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

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

Wir weisen ihn dann an, mit Hilfe von ReportingObserver.observe() Berichte zu überwachen; dies sagt dem Beobachter, dass er Berichte in seiner Berichte-Warteschlange sammeln soll, 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 Veraltungsbericht generiert wird; aufgrund des Ereignishandlers, den wir im ReportingObserver()-Konstruktor eingerichtet haben, können wir jetzt auf die Schaltfläche klicken, um die Berichtdetails anzuzeigen.

• Content Security Policy
• Permissions-Policy