Zur Reporting API v1 migrieren

Eine neue Version der Reporting API ist verfügbar. Sie ist datenschutzfreundlicher und wird mit größerer Wahrscheinlichkeit von allen Browsern unterstützt.

Maud Nalpas

Die Reporting API informiert Sie über Fehler, die auf Ihrer Website auftreten, wenn Nutzer sie verwenden. Sie erhalten unter anderem Informationen zu Browsereingriffen, Browserabstürzen, Verstößen gegen die Content-Security-Policy, COOP-/COEP-Verstößen und Warnungen zur Einstellung von Funktionen.

Eine neue Version der Reporting API ist verfügbar. Die neue API ist schlanker und wird mit höherer Wahrscheinlichkeit browserübergreifend unterstützt.

Zusammenfassung

Website-Entwickler

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

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

⚠️ In beiden Fällen muss die Reporting-Endpoints-Kopfzeile für alle Antworten festgelegt sein, mit denen Berichte generiert werden können.

Entwickler von Berichtsdiensten

Wenn Sie einen Endpunktdienst verwalten oder Ihren eigenen betreiben, ist mit mehr Traffic zu rechnen, wenn Sie oder externe Entwickler zur Reporting API v1 (Reporting-Endpoints-Header) migrieren.

Weiter unten finden Sie Details und Beispielcode.

Netzwerkfehlerprotokollierung

Es wird ein neuer Mechanismus für die Netzwerkfehlerprotokollierung entwickelt. Sobald dieser verfügbar ist, wechseln Sie von der Reporting API v0 zu diesem neuen Mechanismus.

Demo und Code

• Demo-Website: neue Reporting API (Version 1)
• Code für die Demo-Website

Unterschiede zwischen Version 0 und Version 1

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 Bericht hat einen anderen Umfang.

• Beide APIs unterstützen dieselben Berichtstypen, mit einer Ausnahme: Version 1 unterstützt keine Netzwerkfehlerberichte. Weitere Informationen finden Sie in den Schritten zur Migration.
• Version 0 wird nicht und wird auch in Zukunft nicht von allen Browsern unterstützt. Version 1 wird in Zukunft mit größerer Wahrscheinlichkeit von mehreren Browsern unterstützt.

Was bleibt unverändert?

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

• Die Reporting API Version 1 hat keine Auswirkungen auf die ReportingObserver. ReportingObserver hat weiterhin Zugriff auf alle Berichte, die sich beobachten lassen, und das Format bleibt unverändert.

Alle Unterschiede zwischen v0 und v1

Endpunktentwickler: Erwarten Sie mehr Traffic

Wenn Sie Ihren eigenen Server als Berichtsendpunkt eingerichtet haben oder einen Berichts-Collector als Dienst entwickeln oder verwalten, ist mit mehr Traffic auf diesen Endpunkt zu rechnen.

Das liegt daran, dass Berichte mit der Reporting API v1 nicht in Batches verarbeitet werden, wie es bei der Reporting API v0 der Fall ist. Wenn Entwickler also zur Reporting API v1 migrieren, bleibt die Anzahl der Berichte zwar gleich, aber das Anfragevolumen an den Endpunktserver steigt.

Anwendungsentwickler: Zu Reporting-Endpoints (v1) migrieren

Was solltest du tun?

Die neue Reporting API (Version 1) bietet mehrere Vorteile: ✅

• Die Browsersignale sind positiv. Das bedeutet, dass für Version 1 eine browserübergreifende Unterstützung erwartet werden kann, im Gegensatz zu Version 0, die nur in Chrome und Edge unterstützt wird.
• Die API ist schlanker.
• Wir entwickeln Tools, die auf der neuen Reporting API (Version 1) basieren.

Vor diesem Hintergrund:

• Wenn auf Ihrer Website bereits die Reporting API v0 mit dem Report-To-Header verwendet wird, migrieren Sie zu Reporting API v1 (siehe Migrationsschritte). Wenn auf Ihrer Website bereits die Meldefunktion für Verstöße gegen die Content Security Policy verwendet wird, lesen Sie die Migrationsschritte für CSP-Meldungen.
• Wenn auf Ihrer Website noch keine Reporting API verwendet wird und Sie jetzt Berichtsfunktionen hinzufügen: Verwenden Sie die neue Reporting API (Version 1) (Reporting-Endpoints-Header). Es gibt eine Ausnahme: Wenn Sie die Netzwerkfehlerprotokollierung verwenden müssen, verwenden Sie Report-To (v0). Netzwerkfehler-Logging wird derzeit in der Reporting API v1 nicht unterstützt. Wir entwickeln einen neuen Mechanismus für das Logging von Netzwerkfehlern. Verwenden Sie bis zur Verfügbarkeit die Reporting API Version 0. Wenn Sie Netzwerkfehlerprotokolle neben anderen Berichtstypen benötigen, verwenden Sie sowohl Report-To (v0) als auch Reporting-Endpoints (v1). Mit v0 erhalten Sie Netzwerkfehlerprotokolle und mit v1 Berichte aller anderen Typen.

Migrationsschritte

Bei dieser Migration möchten Sie keine Berichte verlieren, die Sie bisher mit Version 0 erhalten haben.

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

   Sie haben folgende Vorteile:

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

   Browserinstanzen, die Reporting-Endpoints unterstützen, verwenden Reporting-Endpoints. Bei Instanzen, die dies nicht unterstützen, wird Report-To verwendet. Das Anfrage- und Berichtsformat ist für Version 0 und Version 1 identisch.

2. Schritt 2 (jetzt ausführen): Achten Sie darauf, dass der Reporting-Endpoints-Header für alle Antworten festgelegt ist, aus denen Berichte generiert werden könnten.

   Bei Version 0 konnten Sie Berichtsendpunkte nur für einige Antworten festlegen. Andere Dokumente (Seiten) an diesem Ursprung verwendeten dann diesen „ambienten“ Endpunkt. Bei Version 1 müssen Sie aufgrund der unterschiedlichen Ausweitung den Reporting-Endpoints-Header für alle Antworten festlegen, aus denen Berichte generiert werden können.

3. Schritt 3 (später beginnen): Sobald alle oder die meisten Ihrer Nutzer auf eine neuere Chrome- oder Edge-Version (96 und höher) umgestellt haben, entfernen Sie Report-To (v0) und belassen Sie nur Reporting-Endpoints.

   Eine Ausnahme: Wenn Sie Berichte zur Netzwerkfehlerprotokollierung benötigen, behalten Sie Report-To bei, bis ein neuer Mechanismus für die Netzwerkfehlerprotokollierung eingeführt wird.

Codebeispiele finden Sie im Cookbook zur Migration.

Migrationsschritte für CSP-Berichte

Es gibt zwei Möglichkeiten, Berichte zu Verstößen gegen die Content-Security-Policy zu konfigurieren:

• Nur mit dem CSP-Header über die report-uri-Anweisung Diese Funktion wird von vielen Browsern unterstützt, darunter Chrome, Firefox, Safari und Edge. Berichte werden mit dem Inhaltstyp application/csp-report gesendet und haben ein CSP-spezifisches Format. Diese Berichte werden als „CSP Level 2-Berichte“ bezeichnet und beruhen nicht auf der Reporting API.
• Bei der Reporting API ist das über den Report-To-Header (alt) oder den neueren Reporting-Endpoints (v1) möglich. 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 Verwendung der ersten Methode (nur report-uri) wird nicht mehr empfohlen. Die zweite Methode bietet einige Vorteile. Insbesondere können Sie die Berichterstellung für alle Berichtstypen auf dieselbe Weise einrichten und einen generischen Endpunkt festlegen, da alle Berichtsanfragen, die über die Reporting API und andere über das Reporting API generiert werden, das gleiche Format application/reports+json haben.

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"

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(...)
});

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