Zur Reporting API v1 migrieren

Eine neue Version der Reporting API ist verfügbar. Sie bietet mehr Datenschutz und wird voraussichtlich von mehr Browsern unterstützt.

Maud Nalpas

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

Eine neue Version der Reporting API ist verfügbar. Die neue API ist schlanker und wird voraussichtlich von mehr Browsern unterstützt.

Zusammenfassung

Websiteentwickler

Wenn Sie bereits eine Berichtsfunktion für Ihre Website haben: Migrieren Sie zu v1, indem Sie den neuen Header (Reporting-Endpoints) verwenden, aber den Legacy-Header (Report-To) noch einige Zeit beibehalten. Weitere Informationen finden Sie unter Migration: Beispielcode.

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

⚠️ In beiden Fällen müssen Sie den Header Reporting-Endpoints für alle Antworten festlegen, die Berichte generieren können.

Entwickler von Berichtsdiensten

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

Weitere Informationen und Beispielcode finden Sie unten.

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

• Demowebsite: neue Reporting API (v1)
• 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 anders.

• Beide APIs unterstützen dieselben Berichtstypen, mit einer Ausnahme: v1 unterstützt keine Berichte zu Netzwerkfehlern. Weitere Informationen finden Sie unter Migrationsschritte.
• v0 wird nicht von allen Browsern unterstützt und wird auch in Zukunft nicht von allen Browsern unterstützt. v1 wird in Zukunft voraussichtlich von mehr Browsern unterstützt.

Was bleibt unverändert?

• Das Format und die Struktur der Berichte bleiben unverändert.
• Die vom Browser an den Endpunkt gesendete Anfrage ist weiterhin eine POST-Anfrage vom Typ Content-type application/reports+json.
• Das Zuordnen 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 v1 hat keine Auswirkungen auf die ReportingObserver. ReportingObserver hat weiterhin Zugriff auf alle beobachtbaren Berichte und ihr Format ist identisch.

Alle Unterschiede zwischen v0 und v1

Endpunktentwickler: Mehr Traffic erwartet

Wenn Sie einen eigenen Server als Berichtsendpunkt eingerichtet haben oder einen Berichtssammler als Dienst entwickeln oder verwalten, ist mit mehr Traffic zu diesem Endpunkt zu rechnen.

Das liegt daran, dass Berichte mit der Reporting API v1 nicht zusammengefasst werden wie mit der Reporting API v0. Wenn Anwendungsentwickler also zur Reporting API v1 migrieren, bleibt die Anzahl der Berichte ähnlich, aber das Volumen der Anfragen an den Endpunktserver nimmt zu.

Anwendungsentwickler: Zu Reporting-Endpoints (v1) migrieren

Was solltet ihr tun?

Die Verwendung der neuen Reporting API (v1) bietet mehrere Vorteile ✅:

• Die Browsersignale sind positiv, was bedeutet, dass v1 voraussichtlich von mehr Browsern unterstützt wird (im Gegensatz zu v0, das nur in Chrome und Edge unterstützt wird).
• Die API ist schlanker.
• Es werden Tools für die neue Reporting API (v1) entwickelt.

Beachten Sie Folgendes:

• Wenn Ihre Website bereits die Reporting API v0 mit dem Report-To Header verwendet, migrieren Sie zur Reporting API v1 (siehe die Migrationsschritte). Wenn Ihre Website bereits eine Berichtsfunktion für Verstöße gegen die Content Security Policy verwendet, lesen Sie die spezifischen Migrationsschritte für die CSP-Berichterstellung.
• Wenn Ihre Website die Reporting API noch nicht verwendet und Sie jetzt eine Berichtsfunktion hinzufügen, verwenden Sie die neue Reporting API (v1) (den Header Reporting-Endpoints). Es gibt eine Ausnahme hierfür: Wenn Sie die Netzwerkfehlerprotokollierung verwenden müssen, verwenden Sie Report-To (v0). Die Netzwerkfehlerprotokollierung wird derzeit in der Reporting API v1 nicht unterstützt. Es wird ein neuer Mechanismus für die Netzwerkfehlerprotokollierung entwickelt. Bis dieser verfügbar ist, verwenden Sie die Reporting API v0. Wenn Sie die Netzwerkfehlerprotokollierung zusammen mit anderen Berichtstypen benötigen, verwenden Sie sowohl Report-To (v0) als auch Reporting-Endpoints (v1). Mit v0 erhalten Sie die Netzwerkfehlerprotokollierung und mit v1 Berichte aller anderen Typen.

Migrationsschritte

Ziel dieser Migration ist es, keine Berichte zu verlieren , die Sie mit v0 erhalten haben.

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

   Dadurch erhalten Sie Folgendes:

   • 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 das nicht tun, greifen auf Report-To zurück. Das Anfrage- und Berichtsformat ist für v0 und v1 identisch.

2. Schritt 2 (jetzt ausführen) : Achten Sie darauf, dass der Header Reporting-Endpoints für alle Antworten festgelegt ist, die Berichte generieren können.

   Mit v0 konnten Sie Berichtsendpunkte nur für einige Antworten festlegen. Andere Dokumente (Seiten) in dieser Quelle verwendeten diesen „Umgebungs“-Endpunkt. Aufgrund des Unterschieds im Umfang müssen Sie mit v1 den Header Reporting-Endpoints für alle Antworten festlegen, die Berichte generieren können.

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

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

Codebeispiele finden Sie im Migrationshandbuch.

Migrationsschritte für die CSP-Berichterstellung

Es gibt zwei Möglichkeiten, Content-Security-Policy Verstoßberichte zu konfigurieren:

• Nur mit dem CSP-Header über die Anweisung report-uri. Diese 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 Reports“ bezeichnet und sind nicht von der Reporting API abhängig.
• Mit der Reporting API, d. h. über den Header Report-To (Legacy) oder den neueren Header Reporting-Endpoints (v1). Diese 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 damit eine einzige Methode verwenden, um die Berichterstellung für alle Berichtstypen einzurichten, sowie einen generischen Endpunkt festlegen, da alle Berichtsanfragen, die über die Reporting API generiert werden (CSP und andere), dasselbe Format haben: application/reports+json.

Allerdings unterstützen nur wenige Browser report-to. Daher wird empfohlen, report-uri neben der Reporting API-Methode (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): Wenn Sie sie noch nicht hinzugefügt haben, fügen Sie report-to neben report-uri hinzu. Browser, die nur report-uri unterstützen (Firefox), verwenden report-uri. Browser, die auch report-to unterstützen(Chrome, Edge), verwenden report-to. Um die benannten Endpunkte anzugeben, die Sie in report-to verwenden, verwenden Sie beide Header: Report-To und Reporting-Endpoints. So erhalten Sie Berichte von älteren und neueren Chrome- und Edge-Clients.

2. Schritt 3 (später ausführen) : Sobald alle oder die meisten Ihrer Nutzer auf neuere Chrome- oder Edge-Installationen (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 nur diese unterstützen.

Codebeispiele für diese Schritte finden Sie unter Migration der CSP-Berichterstellung.

Migration: Beispielcode

Übersicht

Wenn Sie die Legacy-Reporting API (v0) verwenden, um Berichte zu Verstößen für einen COOP-Header (Cross-Origin-Opener-Policy), einen COEP-Header (Cross-Origin-Embedder-Policy) oder einen Dokumentrichtlinien-Header (Document-Policy) zu erhalten, müssen Sie diese Richtlinien-Header bei der Migration zur Reporting API v1 nicht ändern. Sie müssen jedoch vom Legacy-Header Report-To zum neuen Header Reporting-Endpoints migrieren.

Wenn Sie die Legacy-Reporting API (v0) verwenden, um Berichte zu Verstößen für einen CSP-Header (Content-Security-Policy) zu erhalten, müssen Sie möglicherweise Ihre Content-Security-Policy im Rahmen der Migration zur neuen Reporting API (v1) 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"

Beachten Sie, dass Sie mit v1 weiterhin bestimmte Berichtstypen an bestimmte Endpunkte senden können. 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 der CSP-Berichterstellung

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

• Webanwendung mit der Reporting API beobachten (Hauptbeitrag zur Reporting API)
• Spezifikation: Legacy-Reporting API (v0)
• Spezifikation: neue Reporting API (v1)

Vielen Dank an Ian Clelland, Eiji Kitamura und Milica Mihajlija für ihre Überprüfung und ihre Vorschläge zu diesem Artikel.