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 umfassen:

• Verstöße gegen die Content Security Policy.
• Verstöße gegen die Permissions-Policy.
• Verstöße gegen die Integrity-Policy.
• Nutzung veralteter Funktionen (wenn Sie etwas verwenden, das in Browsern bald nicht mehr funktionieren wird).
• Auftreten von Abstürzen.
• Auftreten von User-Agent-Interventionen (wenn der Browser etwas blockiert, das Ihr Code zu tun versucht, weil es beispielsweise als Sicherheitsrisiko angesehen wird oder einfach nur nervig ist, wie das automatische Abspielen von Audio).

Der Zweck der Reporting-API ist es, einen konsistenten Berichtsmechanismus bereitzustellen, mit dem solche Informationen Entwicklern in Form von Berichten verfügbar gemacht werden können, die durch JavaScript-Objekte repräsentiert werden. Es gibt einige Möglichkeiten, sie zu nutzen, 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, das sind benannte URLs (oder Gruppen von URLs), an die Berichte von einem User-Agent gesendet werden können. Ein Reporting-Server an diesen Endpunkten kann die Berichte sammeln, verarbeiten und nach Bedarf für Ihre Anwendung präsentieren.

Der Reporting-Endpoints HTTP-Header wird verwendet, um Details über die verschiedenen Endpunkte anzugeben, die einem User-Agent für die Zustellung von Berichten zur Verfügung stehen. Die report-to Direktive kann dann in bestimmten HTTP-Antwort-Headern 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-Verstoßberichte gesendet werden sollen.

Die Berichte selbst werden vom User-Agent in einem POST-Vorgang 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 und der body eine Serialisierung der API-Schnittstelle, die dem Berichtstyp entspricht, enthält. Zum Beispiel haben CSP-Verstoßberichte 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, auf die sie sich beziehen, abgerufen werden, was nützlich ist — ein Absturz könnte beispielsweise eine Website lahmlegen und alles stoppen, könnte jedoch trotzdem einen Bericht bringen, um dem Entwickler Hinweise darauf zu geben, warum es passiert ist.

Berichte können auch über ReportingObserver-Objekte erlangt werden, die über JavaScript innerhalb der Website erstellt werden, bei der Sie Berichte erhalten möchten. Diese Methode ist nicht so ausfallsicher wie das Senden von Berichten an den Server, da ein Seitenabsturz Sie möglicherweise daran hindern könnte, die Berichte abzurufen — sie ist jedoch 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 in der Beobachterberichtswarteschlange verfügbaren Berichte und eine Kopie desselben ReportingObserver-Objekts, mit dem die Überwachung direkt aus dem Inneren des Callbacks gesteuert werden kann. Der Callback wird ausgeführt, wenn die Beobachtung beginnt.
• Ein Optionswörterbuch, mit dem Sie den Berichtstypen angeben können, den Sie sammeln möchten, und ob Berichte, die vor der Erstellung des Observers generiert wurden, beobachtbar sein sollen (buffered: true).

Anschließend stehen dem Observer Methoden zur Verfügung, um Berichte zu sammeln (ReportingObserver.observe()), die Berichte in der Berichts-Warteschlange abzurufen (ReportingObserver.takeRecords()) und den Observer zu trennen, sodass er keine Berichte mehr sammeln kann (ReportingObserver.disconnect()).

Berichte, die an Reporting-Endpunkte und Reporting-Observer gesendet werden, sind im Wesentlichen gleich: Sie haben eine Origin-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 Berichtstypen zu body wird unten gezeigt.

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

DeprecationReportBody

Enthält Details zu veralteten Webplattform-Funktionen, die eine Website verwendet.

InterventionReportBody

Enthält Details zu einem Interventionsbericht, der generiert wird, wenn eine von der Website gestellte Anfrage vom 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 generiert werden.

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

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 dessen CSP verletzt wird.

Diese Schnittstelle ist Teil der Subresource Integrity-Spezifikation:

IntegrityViolationReportBody

Enthält Informationen über eine Ressource, die blockiert wurde, weil sie die Integritätsgarantien der Subressource nicht erfüllt hat, die von ihrer Integrity-Policy gefordert werden, oder die für Berichte in "Nur-Bericht"-Richtlinien blockiert werden würde, die mit Integrity-Policy-Report-Only festgelegt wurden.

Diese HTTP-Antwort-Header 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, einschließlich Content-Security-Policy und Content-Security-Policy-Report-Only, verwendet werden kann.

Report-To Veraltet

Nicht mehr Teil der Reporting-API, aber immer noch von einigen Browsern unterstützt. Dies legt den Namen und die URL von Reporting-Endpunktgruppen fest, die mit einer Reihe von HTTP-Headern, insbesondere für Network Error Logging, verwendet werden können, das noch nicht aktualisiert wurde, um Reporting-Endpoints zu unterstützen. Andere Reporting-API-Berichte sollten stattdessen Reporting-Endpoints verwenden, um eine bessere zukünftige Unterstützung zu gewährleisten.

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

CSP-Verstöße

Content-Security-Policy oder Content-Security-Policy-Report-Only.

Berichts-Endpunkte können für die folgenden Berichte mit dem endpoints-Feld in einem strukturierten Wörterbuch auf den entsprechenden Headern festgelegt werden:

Integrity-Policy-Verstöße

Integrity-Policy oder Integrity-Policy-Report-Only.

In unserem deprecation_report.html-Beispiel erstellen wir einen einfachen Reporting-Observer, um die Nutzung 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 fordern ihn dann auf, Berichte mit ReportingObserver.observe() zu beobachten; dies weist den Observer an, Berichte in seiner Berichts-Warteschlange zu sammeln und die im Konstruktor angegebene Callback-Funktion auszuführen:

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 erstellt wird; aufgrund des Ereignis-Handlers, den wir im Inneren des ReportingObserver()-Konstruktors eingerichtet haben, können wir nun auf die Schaltfläche klicken, um die Berichtdetails anzuzeigen.

• Content Security Policy
• Permissions-Policy