Zur Reporting API v1 migrieren

Eine neue Version der Reporting API ist verfügbar. Sie ist sicherer und wird eher in verschiedenen Browsern unterstützt.

Maud Nalpas

Die Reporting API informiert Sie über Fehler, die auf Ihrer Website auftreten, wenn Besucher sie verwenden. Sie erhalten unter anderem Einblick in Browsereingriffe, Browserabstürze, Verstöße gegen die Content Security Policy, COOP/COEP-Verstöße und Warnungen zur Einstellung.

Eine neue Version der Reporting API ist verfügbar. Die neue API ist schlanker und wird eher in verschiedenen Browsern unterstützt.

Zusammenfassung

Websiteentwickler

Wenn Sie bereits Berichtsfunktionen für Ihre Website haben: Migrieren Sie zu Version 1, indem Sie den neuen Header (Reporting-Endpoints) verwenden, aber den alten Header noch eine Zeit lang verwenden (Report-To). Weitere Informationen finden Sie unter Migration: Beispielcode.

Wenn Sie Ihrer Website gerade Berichtsfunktionen hinzufügen: Verwenden Sie nur den neuen Header (Reporting-Endpoints).

⚠️ In beiden Fällen musst du den Reporting-Endpoints-Header für alle Antworten festlegen, die Berichte generieren könnten.

Entwickler von Meldediensten

Wenn Sie einen Endpunktdienst betreiben oder Ihren eigenen betreiben, müssen Sie mit mehr Traffic rechnen, wenn Sie oder externe Entwickler zur Reporting API Version 1 migrieren (Reporting-Endpoints-Header).

Lesen Sie weiter, um mehr über Details und Beispielcode zu erfahren.

Logging von Netzwerkfehlern

Für die Protokollierung von Netzwerkfehlern wird ein neuer Mechanismus entwickelt. Sobald diese Funktion verfügbar ist, können Sie von Version 0 der Reporting API zu diesem neuen Mechanismus wechseln.

Demo und Code

• Demowebsite: Neue Reporting API (Version 1)
• Code für die Demowebsite

Unterschiede zwischen v0 und v1

Was ändert sich?

• Die API-Oberfläche ist anders.

 Report-To: { group: "main-endpoint", "max_age": 86400, "endpoints": [ { "url": ... }, { "url": ... }] }, { group: "default-endpoint", "max_age": 86400, "endpoints": [ { "url": ... }, { "url": ... }] }
 Document-Policy: ...; report-to main-endpoint

 Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
 Document-Policy: ...; report-to main-endpoint

• Der Umfang des Berichts ist unterschiedlich.

• Beide APIs unterstützen dieselben Berichtstypen, mit einer Ausnahme: v1 unterstützt keine Netzwerkfehlerberichte. Weitere Informationen finden Sie in den Migrationsschritten.
• v0 wird nicht in verschiedenen Browsern unterstützt und wird auch in Zukunft nicht unterstützt. In Zukunft wird v1 voraussichtlich in mehreren Browsern unterstützt.

Was unverändert bleibt

• Format und Struktur der Berichte bleiben unverändert.
• Die vom Browser an den Endpunkt gesendete Anfrage bleibt eine POST-Anfrage mit dem Wert Content-type application/reports+json.
• Die Zuordnung bestimmter Endpunkte zu bestimmten Berichtstypen wird sowohl in v0 als auch in v1 unterstützt.
• Die Rolle des default-Endpunkts bleibt unverändert.

• Die Reporting API Version 1 hat keine Auswirkungen auf die ReportingObserver. ReportingObserver erhält weiterhin Zugriff auf alle beobachtbaren Berichte und ihr Format ist identisch.

Alle Unterschiede zwischen v0 und v1

Endpunktentwickler: Mehr Traffic erwarten

Wenn Sie Ihren eigenen Server als Endpunkt für die Berichterstellung eingerichtet haben oder wenn Sie einen Report Collector als Dienst entwickeln oder verwalten, sollten Sie mehr Traffic an diesen Endpunkt erwarten.

Das liegt daran, dass Berichte nicht im Batch mit der Reporting API Version 1 zusammengefasst werden wie mit der Reporting API Version 0. Wenn Anwendungsentwickler zur Reporting API Version 1 migrieren, bleibt die Anzahl der Berichte ähnlich, das Volumen der Anfragen an den Endpunktserver wird jedoch zunehmen.

Anwendungsentwickler: Zu Reporting-Endpoints migrieren (v1)

Was solltet ihr tun?

Die neue Reporting API (v1) bietet mehrere Vorteile ✅:

• Browsersignale sind positiv, was bedeutet, dass für v1 eine browserübergreifende Unterstützung zu erwarten ist (im Gegensatz zu v0, die nur in Chrome und Edge unterstützt wird).
• Die API ist schlanker.
• Tools werden rund um das neue Reporting API (v1) entwickelt.

Beachten Sie Folgendes:

• Wenn Ihre Website bereits die Reporting API Version 0 mit dem Header Report-To verwendet, migrieren Sie zur Reporting API Version 1 (siehe Migrationsschritte). Wenn auf Ihrer Website bereits Berichtsfunktionen für Content-Security-Policy-Verstöße verwendet werden, lesen Sie die Migrationsschritte für CSP-Berichte.
• Wenn auf Ihrer Website die Reporting API noch nicht verwendet wird und Sie jetzt Berichtsfunktionen hinzufügen, verwenden Sie die neue Reporting API (Version 1) (Reporting-Endpoints-Header). Es gibt jedoch eine Ausnahme: Verwenden Sie Report-To (v0), wenn Sie Netzwerkfehler-Logging verwenden müssen. Netzwerkfehler-Logging wird derzeit in der Reporting API v1 nicht unterstützt. Ein neuer Mechanismus für Netzwerkfehler-Logging wird entwickelt. Verwenden Sie die Reporting API Version 0, bis dieser verfügbar ist. Wenn Sie Netzwerkfehler-Logging neben anderen Berichtstypen benötigen, verwenden Sie sowohl Report-To (V0) als auch Reporting-Endpoints (V1). Mit v0 erhalten Sie Netzwerkfehler-Logging und v1 liefert Berichte aller anderen Typen.

Migrationsanleitung

Ihr Ziel bei dieser Migration ist es, keine Berichte zu verlieren, die Sie früher mit Version 0 erhalten haben.

1. Schritt 1 (jetzt ausführen): Verwenden Sie beide Header: Report-To (V0) und Reporting-Endpoints (V1).

   Das bringt Ihnen folgende Vorteile:

   • Berichte von neueren Chrome- und Edge-Clients dank Reporting-Endpoints (v1).
   • Berichte von älteren Chrome- und Edge-Clients dank Report-To (v0).

   Browserinstanzen, die Reporting-Endpoints unterstützen, verwenden Reporting-Endpoints. Instanzen, die dies nicht tun, greifen auf Report-To zurück. Das Anfrage- und Berichtsformat ist für v0 und v1 gleich.

2. Schritt 2 (jetzt ausführen): Der Header Reporting-Endpoints muss für alle Antworten festgelegt sein, die Berichte generieren können.

   Mit v0 konnten Sie Endpunkte für die Berichterstellung nur für bestimmte Antworten festlegen. Andere Dokumente (Seiten) an diesem Ursprung würden diesen „Inaktiven“ Endpunkt verwenden. Aufgrund der unterschiedlichen Gültigkeitsbereich müssen Sie bei Version 1 für alle Antworten, die Berichte generieren könnten, den Header Reporting-Endpoints festlegen.

3. Schritt 3 (später starten): Sobald alle oder die meisten Ihrer Nutzer auf spätere Chrome- oder Edge-Installationen (Version 96 und höher) aktualisiert haben, entfernen Sie Report-To (v0) und behalten Sie nur Reporting-Endpoints bei.

   Eine Ausnahme: Wenn Sie Berichte zu Netzwerkfehler-Logging benötigen, behalten Sie Report-To bei, bis ein neuer Mechanismus für Netzwerkfehler-Logging eingerichtet ist.

Codebeispiele finden Sie im Migrationskochbuch.

Migrationsschritte für CSP-Berichte

Es gibt zwei Möglichkeiten, Berichte über Verstöße gegen Content-Security-Policy zu konfigurieren:

• Mit dem CSP-Header allein über die Anweisung „report-uri“. Dieser bietet eine breite Browserunterstützung in Chrome, Firefox, Safari und Edge. Berichte werden mit dem Inhaltstyp application/csp-report gesendet und haben ein für CSP entwickeltes Format. Diese Berichte werden als „Berichte der Stufe 2“ bezeichnet und basieren nicht auf der Reporting API.
• Bei der Reporting API erfolgt dies über den Report-To-Header (alte Version) oder über die neuere Reporting-Endpoints (Version 1). Dies wird nur in Chrome und Edge unterstützt. Berichtsanfragen haben dasselbe Format wie andere Reporting API-Anfragen und denselben Inhaltstyp (application/reports+json).

Die erste Methode (nur report-uri) wird nicht mehr empfohlen. Die zweite Methode bietet einige Vorteile. Insbesondere können Sie so die Berichterstellung für alle Berichtstypen in einer einzigen Methode einrichten und einen generischen Endpunkt festlegen (da alle Berichtsanfragen, die über die Reporting API – CSP und andere – dasselbe Format haben: application/reports+json.

report-to wird jedoch nur von einigen wenigen Browsern unterstützt. Daher wird empfohlen, report-uri neben dem Reporting API-Ansatz (Report-To oder besser, Reporting-Endpoints) beizubehalten, um Berichte zu CSP-Verstößen von mehreren Browsern zu erhalten. In einem Browser, der report-uri und report-to erkennt, wird report-uri ignoriert, wenn report-to vorhanden ist. In einem Browser, der nur report-uri erkennt, wird nur report-uri berücksichtigt.

1. Schritt 1 (jetzt ausführen): Fügen Sie report-to zusammen mit report-uri hinzu, falls Sie dies noch nicht getan haben. Browser, die nur report-uri (Firefox) unterstützen, verwenden report-uri, Browser, die auch report-to unterstützen(Chrome, Edge), verwenden report-to. Verwenden Sie zur Angabe der benannten Endpunkte, die Sie in report-to verwenden, die beiden Header Report-To und Reporting-Endpoints. Dadurch wird sichergestellt, dass Sie sowohl von älteren als auch von neueren Chrome- und Edge-Clients Berichte erhalten.

2. Schritt 3 (später starten): Sobald alle oder die meisten Ihrer Nutzer auf spätere Chrome- oder Edge-Installationen (Version 96 und höher) aktualisiert haben, entfernen Sie Report-To (v0) und behalten Sie nur Reporting-Endpoints bei. Behalten Sie report-uri bei, damit Sie weiterhin Berichte für Browser erhalten, die diese Funktion unterstützen.

Codebeispiele zu diesen Schritten finden Sie unter Migration der CSP-Berichte.

Migration: Beispielcode

Überblick

Wenn Sie die alte Reporting API (Version 0) verwenden, um Berichte über Verstöße für einen COOP (Header Cross-Origin-Opener-Policy), einen COEP (Cross-Origin-Embedder-Policy) oder eine Dokumentrichtlinie (Header Document-Policy) zu erhalten, müssen Sie diese Richtlinienheader bei der Migration zur Reporting API Version 1 nicht selbst ändern. Sie müssen jedoch vom alten Report-To-Header zum neuen Reporting-Endpoints-Header migrieren.

Wenn Sie die alte Reporting API (v0) verwenden, um Berichte über Verstöße für eine CSP (Content-Security-Policy-Header) zu erhalten, müssen Sie Content-Security-Policy im Rahmen der Migration zur neuen Reporting API (v1) möglicherweise anpassen.

Einfache Migration

Report-To: { group: "main-endpoint", "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "endpoints": [ { "url": "https://reports.example/default" }] }

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
Report-To: { group: "main-endpoint", "max_age": 86400, "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "max_age": 86400, "endpoints": [ { "url": "https://reports.example/default" }] }

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"

Hinweis: Mit v1 können Sie weiterhin bestimmte Berichtstypen an bestimmte Endpunkte senden. Sie können jedoch nur eine URL pro Endpunkt haben.

Alle Seiten beobachten

app.get("/", (request, response) => {
  response.set("Report-To", …)
  response.render(...)
});
app.get("/page1", (request, response) => {
  response.render(...)
});

// Use a middleware to set the reporting endpoint(s) for *all* requests.
app.use(function(request, response, next) {
  response.set("Reporting-Endpoints", …);
  next();
});

app.get("/", (request, response) => {
  response.render(...)
});

app.get("/page1", (request, response) => {
  response.render(...)
});

Migration von CSP-Berichten

Content-Security-Policy: ...; report-uri https://reports.example/main

Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Report-To: main-endpoint="https://reports.example/main"

Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Reporting-Endpoints: main-endpoint="https://reports.example/main"
Report-To: ...

Weitere Informationen

• Webanwendungen mit der Reporting API überwachen (Hauptbeitrag zur Reporting API)
• Spezifikation: Alte Reporting API (Version 0)
• Spezifikation: Neue Reporting API (Version 1)

Hero-Image von Nine Koepfer / @enka80 auf Unsplash, bearbeitet Vielen Dank an Ian Clelland, Eiji Kitamura und Milica Mihajlija für ihre Rezensionen und Vorschläge zu diesem Artikel.