Reporting API

Konzepte und Verwendung

Verschiedene Funktionen und Probleme der Webplattform erzeugen Informationen, die Webentwicklern helfen können, Fehler zu beheben oder ihre Websites anderweitig zu verbessern. Dazu gehören:

• Verstöße gegen die Content Security Policy.
• Verstöße gegen die Permissions-Policy.
• Verstöße gegen die Integrity-Policy.
• Verstöße gegen die Cross-Origin-Embedder-Policy.
• Die Verwendung veralteter Funktionen, die demnächst in Browsern nicht mehr funktionieren werden.
• Das Auftreten von Abstürzen.
• Eingriffe des User-Agents, etwa wenn der Browser eine Aktion Ihres Codes blockiert, weil sie als Sicherheitsrisiko oder als störend gilt, beispielsweise die automatische Audiowiedergabe.

Die Reporting API soll einen einheitlichen Mechanismus bereitstellen, mit dem Entwickler solche Informationen als Berichte in Form von JavaScript-Objekten erhalten können.

Berichte können über JavaScript-Reporting-Observer abgerufen oder an einen entfernten Server-Endpunkt gesendet werden. Die Berichtstypen und beide Verfahren werden im Folgenden beschrieben.

Berichtstypen

Berichte, die an Reporting-Observer übermittelt werden, sind Instanzen von Dictionary-Objekten. Sie verfügen jeweils über die Eigenschaften type, url und body. Dabei gibt type den Berichtstyp an, während der Inhalt von body vom Berichtstyp abhängt.

An Reporting-Endpunkte gesendete Berichte sind im Wesentlichen gleich aufgebaut. Der einzige Unterschied besteht darin, dass Serverberichte JSON-Serialisierungen dieser Objekte mit zusätzlichen Feldern user_agent und age sind.

Die folgende Tabelle führt die dokumentierten Berichtstypen, die zugehörigen Bericht-Dictionaries und Hinweise zu den gemeldeten Ereignissen auf. Mit Ausnahme von crash-Berichten, die nicht in JavaScript beobachtet werden können, weil die beobachtete Seite abgestürzt ist, sind alle aufgeführten Berichte für Observer sichtbar und können an Server-Endpunkte gesendet werden.

Eine Liste der Typen kann auch über den Parameter options.types an den Konstruktor ReportingObserver() übergeben werden.

Reporting-Observer

Berichte können über ReportingObserver-Objekte abgerufen werden, die per JavaScript innerhalb der Website erstellt werden, für die Sie Berichte erhalten möchten. Dieses Verfahren ist weniger ausfallsicher als das Senden von Berichten an einen Server, da ein Seitenabsturz den Abruf verhindern kann. Es lässt sich jedoch einfacher einrichten und ist flexibler.

Ein ReportingObserver-Objekt wird mit dem Konstruktor ReportingObserver() erstellt, der zwei Parameter erhält:

• Eine Callback-Funktion mit zwei Parametern: einem Array der Berichte in der Berichtswarteschlange des Observers und einer Kopie desselben ReportingObserver-Objekts. Dadurch lässt sich die Beobachtung direkt aus dem Callback steuern. Der Callback wird ausgeführt, wenn die Beobachtung beginnt.
• Ein Options-Dictionary, mit dem Sie die zu erfassenden Berichtstypen festlegen und bestimmen können, ob Berichte beobachtbar sein sollen, die vor der Erstellung des Observers erzeugt wurden (buffered: true).

Anschließend stehen Methoden bereit, um die Erfassung von Berichten zu starten (ReportingObserver.observe()), die derzeit in der Berichtswarteschlange enthaltenen Berichte abzurufen (ReportingObserver.takeRecords()) und den Observer zu trennen, sodass er keine weiteren Berichte erfassen kann (ReportingObserver.disconnect()).

Server-Endpunkte für Berichte

Der User-Agent kann Berichte auch per POST mit einem Content-Type von application/reports+json an entfernte Server-Endpunkte senden. Die Berichte sind Serialisierungen des jeweiligen Dictionary für den entsprechenden Berichtstyp. Berichte über CSP-Verstöße sind beispielsweise Serialisierungen eines CSPViolationReport-Objekts.

An Endpunkte gesendete Berichte lassen sich unabhängig davon abrufen, ob die zugehörigen Websites noch ausgeführt werden. Das ist beispielsweise bei einem Absturz hilfreich: Auch wenn die Website nicht mehr funktioniert, kann ein Bericht Entwicklern Hinweise auf die Ursache liefern.

Der HTTP-Header Reporting-Endpoints legt Namen und URLs der Endpunkte fest, die einem User-Agent für die Zustellung von Berichten zur Verfügung stehen. Anschließend können diese Endpunkte in bestimmten HTTP-Antwort-Headern angegeben werden, um festzulegen, an welchen Endpunkt – oder in manchen Fällen an welche Endpunkte – die zugehörigen Berichte gesendet werden. Berichtstypen ohne zugehörigen HTTP-Header, etwa crash, deprecation und intervention, senden Berichte üblicherweise an den Reporting-Endpunkt "default". Dabei handelt es sich um einen Endpunkt mit dem Namen „default“, der über den Header Reporting-Endpoints festgelegt wird.

Die Verfahren zur Festlegung von Server-Endpunkten für die einzelnen Berichtstypen sind nachstehend aufgeführt:

coep

• Parameter report-to in Cross-Origin-Embedder-Policy oder Cross-Origin-Embedder-Policy-Report-Only

csp-violation

• Direktive report-to in Content-Security-Policy oder Content-Security-Policy-Report-Only.

integrity-violation

• Feld endpoints in Integrity-Policy oder Integrity-Policy-Report-Only

permissions-policy-violation

• Parameter report-to in Permissions-Policy oder Permissions-Policy-Report-Only
• Endpunkt "default"

crash

• Endpunkt crash-reporting
• Endpunkt default.

deprecation

• Endpunkt default.

intervention

• Endpunkt default.

Berichte über WebDriver erzeugen

Die Spezifikation der Reporting API definiert außerdem eine WebDriver-Erweiterung namens „Generate Test Report“, mit der Sie die Erzeugung von Berichten während einer Automatisierung simulieren können. Über WebDriver erzeugte Berichte werden von allen registrierten ReportingObserver-Objekten auf der geladenen Website beobachtet. Dies ist noch nicht dokumentiert.

Schnittstellen

CrashReportContext

Stellt Methoden bereit, mit denen beliebige Daten für den aktuellen Top-Level-Browsing-Kontext aufgezeichnet werden können. Bei einem Browserabsturz werden diese Daten einem CrashReport hinzugefügt und an einen Reporting-Endpunkt gesendet.

ReportingObserver

Ein Objekt, mit dem Berichte bei ihrer Erzeugung erfasst und abgerufen werden können.

Verwandte Schnittstellen

SecurityPolicyViolationEvent

Repräsentiert das Event-Objekt eines securitypolicyviolation-Events, das bei einem CSP-Verstoß an einem Element, Dokument oder Worker ausgelöst wird. Dies ist in den HTTP-Spezifikationen zur Content Security Policy (CSP) definiert.

Dictionaries

COEPViolationReport

Enthält Details zu einem Verstoß gegen Cross-Origin-Embedder-Policy (COEP).

CrashReport

Enthält Details zu einem Browserabsturz.

CSPViolationReport

Enthält Details zu einem CSP-Verstoß. Dies ist in den HTTP-Spezifikationen zur Content Security Policy (CSP) definiert.

DeprecationReport

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

InterventionReport

Enthält Details zu einem Eingriff, der gemeldet wird, wenn der Browser eine von der Website gestellte Anfrage ablehnt, beispielsweise aus Sicherheitsgründen.

IntegrityViolationReport

Enthält Informationen über eine Ressource, die blockiert wurde, weil sie die durch Integrity-Policy vorgeschriebenen Subresource-Integrity-Garantien nicht erfüllt, oder die bei einer über Integrity-Policy-Report-Only festgelegten Richtlinie im reinen Berichtsmodus blockiert würde. Dies ist in der Spezifikation zu Subresource Integrity definiert.

PermissionsPolicyViolationReport

Enthält Details zu einem Verstoß gegen Permissions-Policy.

Verwandte HTTP-Header

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

Reporting-Endpoints

Legt Namen und URLs von Reporting-Endpunkten fest. Diese Endpunkte können in der Direktive report-to verwendet werden, die mit verschiedenen HTTP-Headern eingesetzt werden kann, darunter Content-Security-Policy und Content-Security-Policy-Report-Only.

Report-To

Ist nicht mehr Teil der Reporting API, wird aber weiterhin von einigen Browsern unterstützt. Dieser Header legt Namen und URLs von Gruppen von Reporting-Endpunkten fest. Sie können mit verschiedenen HTTP-Headern verwendet werden, insbesondere für Network Error Logging, das noch nicht für die Unterstützung von Reporting-Endpoints aktualisiert wurde. Andere Berichte der Reporting API sollten stattdessen Reporting-Endpoints verwenden, um künftig besser unterstützt zu werden.

Beispiele

Berichte über veraltete Funktionen

Dieses Beispiel zeigt, wie Sie mit einem ReportingObserver "deprecation"-Berichte innerhalb einer Seite beobachten, die diese Berichte auslöst.

Wir zeigen einen "deprecation"-Bericht, weil dafür keine bestimmten HTTP-Header gesetzt werden müssen und sich das Beispiel daher als interaktives MDN-Beispiel ausführen lässt.

<pre id="log"></pre>

#log {
  height: 200px;
  margin: 10px;
  overflow: scroll;
  padding: 0.5rem;
  border: 1px solid black;
}

const logElement = document.querySelector("#log");
function log(text) {
  logElement.innerText = `${logElement.innerText}${text}\n`;
  logElement.scrollTop = logElement.scrollHeight;
}

JavaScript

Zunächst erstellen wir ein neues ReportingObserver-Objekt, das auf Berichte vom Typ "deprecation" wartet. Dabei übergeben wir einen Callback, der die Berichte empfängt und protokolliert.

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

const observer = new ReportingObserver((reports, observer) => {
  reports.forEach((report) => {
    log(JSON.stringify(report, null, 2));
  });
}, options);

// Start the observer
observer.observe();

Anschließend führen wir den folgenden Code aus, der synchrones XHR verwendet (eine veraltete API). Beachten Sie, dass dieser Code nach dem Observer definiert ist, den er auslöst, sobald der Observer aktiv ist.

const xhr = new XMLHttpRequest();
xhr.open("GET", "/", false); // false = synchronous (deprecated)
xhr.send();

Ergebnisse

In Browsern, die Berichte über veraltete Funktionen unterstützen, sollte unten ein Bericht angezeigt werden. Beachten Sie, dass type den Wert "deprecation" hat.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Content Security Policy
• Permissions-Policy