Zur Reporting API v1 migrieren

Eine neue Version der Reporting API ist verfügbar. Diese Funktion ist datenschutzfreundlicher und wird mit größerer Wahrscheinlichkeit in verschiedenen Browsern unterstützt.

Maud Nalpas

Die Reporting API informiert Sie über Fehler, die beim Verwenden Ihrer Website durch Besucher auftreten. Sie bietet über Browser-Maßnahmen, Browser-Abstürze, Verstöße gegen die Content Security Policy, COOP-/COEP-Verstöße, Warnungen zu veralteten Versionen und mehr.

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

Zusammenfassung

Website-Entwickler

Wenn Sie bereits Berichtsfunktionen für Ihre Website haben: Migrieren Sie zu Version 1, indem Sie die neue Kopfzeile verwenden. (Reporting-Endpoints), aber lassen Sie den alten Header eine Zeit lang bestehen (Report-To). Siehe Migration: Beispielcode.

Wenn Sie Ihrer Website gerade eben Berichtsfunktionen hinzufügen: Verwenden Sie nur die neue Kopfzeile. (Reporting-Endpoints)

⚠️ In beiden Fällen muss der Reporting-Endpoints-Header für alle Antworten festgelegt sein, die möglicherweise Berichte zu erstellen.

Entwickler von Diensten für die Berichterstellung

Falls Sie einen Endpunktdienst oder einen eigenen Dienst betreiben, ist mit mehr Traffic zu rechnen, oder externe Entwickler zur Reporting API Version 1 migrieren (Reporting-Endpoints-Header).

Weitere Informationen und Beispielcode finden Sie weiter unten.

Netzwerkfehler-Logging

Ein neuer Mechanismus für das Logging von Netzwerkfehlern wird entwickelt. Sobald diese verfügbar ist, sollten Sie von Version 0 der Reporting API auf dieses neue Verfahren umstellen.

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

• Beide APIs unterstützen dieselben Berichtstypen, mit einer Ausnahme: In Version 1 werden keine Netzwerkfehlerberichte unterstützt. Weitere Informationen finden Sie in den Migrationsschritten.
• v0 wird nicht in Browsern unterstützt. v1 wird mit größerer Wahrscheinlichkeit in Zukunft mehrere Browser an.

Was unverändert bleibt

• 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 v0 als auch in v1 unterstützt.
• Die Rolle des Endpunkts default bleibt unverändert.

• Version 1 der Reporting API hat keine Auswirkungen auf die ReportingObserver. ReportingObserver erhält weiterhin Zugriff auf alle beobachtbaren Berichte im folgenden Format: identisch.

Alle Unterschiede zwischen v0 und v1

Endpunktentwickler: Erwarten Sie mehr Traffic

Wenn Sie Ihren eigenen Server als Endpunkt für die Berichterstellung eingerichtet haben oder wenn Sie eine Entwicklung oder Wartung eines Report Collector als Dienst, ist mit mehr Traffic zu diesem Endpunkt zu rechnen.

Das liegt daran, dass Berichte nicht mit der Reporting API Version 1 erstellt werden, wie dies bei der Reporting API Version 0 der Fall ist. Dementsprechend wird Wenn Anwendungsentwickler mit der Migration zur Reporting API Version 1 beginnen, ändert sich die Anzahl der Berichte bleiben ähnlich, aber die Anzahl der Anfragen an den Endpunktserver nimmt zu.

Anwendungsentwickler: Migrieren Sie zu Reporting-Endpoints (v1)

Was solltest du tun?

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

• Browsersignale sind positiv, das heißt, für v1 zu erwarten ist (im Gegensatz zu v0, die nur in Chrome und Edge).
• Die API ist übersichtlicher.
• Wir entwickeln Tools, die auf der neuen Reporting API (Version 1) basieren.

Vor diesem Hintergrund:

• Wenn auf Ihrer Website bereits die Reporting API Version 0 mit dem Report-To-Header verwendet wird, migrieren Sie zum Reporting API Version 1 (siehe die Migrationsschritte) Wenn Ihre Website bereits die Berichtsfunktionen für Verstöße gegen die Content-Security-Policy enthält, finden Sie die entsprechenden Migrationsschritte für die CSP-Berichterstellung.
• Wenn Sie die Reporting API noch nicht auf Ihrer Website verwenden und jetzt Funktionen zur Berichterstellung hinzufügen: die neue Reporting API (Version 1) (Reporting-Endpoints-Header) verwenden. Es gibt eine Ausnahme this: Wenn Sie Netzwerkfehler-Logging verwenden müssen, nutzen Sie Report-To (v0). Netzwerkfehler-Logging wird derzeit in der Reporting API v1 nicht unterstützt. Ein neuer Mechanismus für das Logging von Netzwerkfehlern bis diese verfügbar ist, verwenden Sie die Reporting API v0. Wenn Sie Netzwerkfehler-Logging benötigen neben anderen Berichtstypen sowohl Report-To (V0) als auch Reporting-Endpoints (V1) verwenden. v0 liefert Netzwerkfehler-Logging und V1 liefert 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 die beiden Überschriften Report-To (V0) und Reporting-Endpoints (V1).

   Die 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 und Instanzen, die dies nicht tun, auf Report-To zurückgreifen. Das Anfrage- und Berichtsformat ist für v0 und v1.

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

   Mit v0 konnten Sie Berichtsendpunkte nur für einige Antworten und andere Dokumente festlegen. (Seiten) dieser Quelle dieses "Ambiente" verwenden. Endpunkt. Bei v1 gibt es aufgrund des Unterschieds zwischen Umfang festgelegt haben, müssen Sie den Reporting-Endpoints-Header für alle Antworten festlegen, die möglicherweise Berichte.

3. Schritt 3 (später beginnen): Nachdem alle oder die meisten Nutzer eine Aktualisierung auf Chrome oder Edge vorgenommen haben Installationen (96 und höher), entfernen Sie Report-To (Version 0) und behalten Sie nur Reporting-Endpoints bei.

   Eine Ausnahme: Wenn Sie Berichte zur Protokollierung von Netzwerkfehlern benötigen, speichern Sie Report-To, bis ein neuer für das Logging von Netzwerkfehlern.

Codebeispiele finden Sie im Cookbook zur Migration.

Migrationsschritte für CSP-Berichte

Bei Content-Security-Policy gibt es zwei Möglichkeiten: können folgendermaßen konfiguriert werden:

• Mit dem CSP-Header allein über die report-uri-Anweisung. Diese Methode wird von zahlreichen Browsern unterstützt, Chrome, Firefox, Safari und Edge. Meldungen werden mit dem Inhaltstyp application/csp-report gesendet und haben ein CSP-spezifisches Format. Diese Berichte werden als „CSP-Level-2-Berichte“ bezeichnet. und nicht auf die Reporting API.
• Mit der Reporting API über den Report-To-Header (alte Version) oder die neuere Version Reporting-Endpoints (Version 1). Dies wird nur in Chrome und Edge unterstützt. Berichtsanfragen enthalten die gleiches 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 hat 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 generiert wurden, und andere das gleiche Format haben: application/reports+json.

report-to wird jedoch nur von wenigen Browsern unterstützt. Daher wird empfohlen, report-uri parallel zur Reporting API (Report-To) zu verwenden oder besser, Reporting-Endpoints), um Berichte über CSP-Verstöße von mehreren Browsern zu erhalten. In einer 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 tun): Wenn Sie dies noch nicht getan haben, fügen Sie report-to neben report-uri hinzu. Browser, die nur report-uri (Firefox) unterstützen, verwenden report-uri, und Browser, die auch unterstützen report-to(Chrome, Edge) verwendet report-to. Zum Angeben der benannten Endpunkte, die Sie verwenden Verwenden Sie in report-to die beiden Header Report-To und Reporting-Endpoints. So erhalten Sie Berichte von älteren und neueren Chrome- und Edge-Clients.

2. Schritt 3 (später beginnen): Nachdem alle oder die meisten Nutzer eine Aktualisierung auf Chrome oder Edge vorgenommen haben Installationen (96 und höher), entfernen Sie Report-To (Version 0) und behalten Sie nur Reporting-Endpoints bei. Notizen report-uri, damit Sie weiterhin Berichte für Browser erhalten, die das nur unterstützen.

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

Migration: Beispielcode

Übersicht

Wenn Sie die alte Reporting API (v0) verwenden, um Berichte zu Verstößen für einen COOP zu erhalten (Cross-Origin-Opener-Policy-Header), ein COEP (Cross-Origin-Embedder-Policy) oder eine Dokumentrichtlinie (Document-Policy-Header): Sie müssen diese Richtlinien-Header bei der Migration nicht selbst ändern. Reporting API Version 1. Sie müssen lediglich vom alten Report-To-Header in den neuen Reporting-Endpoints-Header.

Wenn Sie die alte Reporting API (v0) verwenden, um Berichte zu Verstößen für eine CSP zu erhalten (Content-Security-Policy Header), müssen Sie eventuell Ihre Content-Security-Policy im Rahmen von die Migration zur neuen Reporting API (Version 1) durchzuführen.

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"

Mit Version 1 können Sie weiterhin bestimmte Berichtstypen an bestimmte Endpunkte senden. Aber Sie kann 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

• Webanwendung mit der Reporting API überwachen (Hauptbeitrag zur Reporting API)
• Spezifikation: Legacy Reporting API (v0)
• Spezifikation: Neue Reporting API (v1)

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 Artikel