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

Achtung:In diesem Beitrag wird beschrieben, wie Sie zur neuen Version der Reporting API (v1) migrieren. Wenn Sie die Reporting API noch nicht kennen oder detaillierte Anwendungsbeispiele benötigen, lesen Sie stattdessen den Hauptbeitrag zur Reporting API statt.

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.

Hinweis:Die Legacy-Reporting API heißt Reporting API v0. Die neue Reporting API heißt Reporting API v1.

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

Achtung: Wenn Sie die Netzwerkfehlerprotokollierung verwenden, verwenden Sie weiterhin Report-To (v0), da die Netzwerkfehlerprotokollierung in der Reporting API v1 nicht unterstützt wird.

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.

v0 (Legacy)

 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

In v0 wird der Report-To Header verwendet, um benannte Endpunktgruppen zu konfigurieren, und die report-to Anweisung in anderen Headern, um auf diese Endpunktgruppen zu verweisen.

v1 (neu)

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

In v1 wird der Header Reporting-Endpoints verwendet, um benannte Endpunkte zu konfigurieren. Wie in v0 wird die Anweisung report-to in anderen Headern verwendet, um auf diese Endpunktgruppen zu verweisen.

• Der Umfang des Berichts ist anders.

v0 (Legacy)

Mit v0 können Sie Berichtsendpunkte nur für einige Antworten festlegen. Andere Dokumente (Seiten) in dieser Quelle verwenden automatisch diese Umgebungsendpunkte.

v1 (neu)

Mit v1 müssen Sie den Header Reporting-Endpoints für alle Antworten festlegen, die Berichte generieren können.

• 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

	Legacy-Reporting API (v0) Report-To Header	Neue Reporting API (v1) Reporting-Endpoints Header
Unterstützte Browser	Chrome 69+ und Edge 69+.	Chrome 96+ und Edge 96+. Firefox wird unterstützt. Safari hat keine Einwände. Weitere Informationen finden Sie unter Browsersignale.
Endpunkte	Sendet Berichte an mehrere Berichtssammler (mehrere URLs pro Endpunktgruppe definiert).	Sendet Berichte an bestimmte Berichtssammler (nur eine URL pro Endpunkt definiert).
API-Oberfläche	Verwendet den `Report-To` Header, um benannte Endpunktgruppen zu konfigurieren.	Verwendet den `Reporting-Endpoints` Header, um benannte Endpunkte zu konfigurieren.
Berichtstypen, die über diese API generiert werden können	Einstellung Intervention Absturz COOP/COEP Content Security Policy Level 3 (CSP Level 3) Netzwerkfehlerprotokollierung (Network Error Logging, NEL) Weitere Informationen zu den Berichtstypen finden Sie im Beitrag zur Reporting API.	Unverändert, mit Ausnahme der Netzwerkfehlerprotokollierung (Network Error Logging, NEL) : Diese wird in der neuen Reporting API (v1) nicht unterstützt.
Berichtsumfang	Quelle. Der Report-To-Header eines Dokuments wirkt sich auf andere Dokumente (Seiten) aus dieser Quelle aus. Das Feld url eines Berichts variiert weiterhin je nach Dokument.	Dokument. Der Reporting-Endpoints-Header eines Dokuments wirkt sich nur auf dieses Dokument aus. Das Feld url eines Berichts variiert weiterhin je nach Dokument.
Berichtsisolierung (Batching)	Verschiedene Dokumente (Seiten) oder Websites/Quellen, die etwa zur gleichen Zeit einen Bericht generieren und denselben Berichtsendpunkt haben, werden zusammengefasst: Sie werden in derselben Nachricht an den Berichtsendpunkt gesendet.	Berichte aus verschiedenen Dokumenten (Seiten) werden nie zusammen gesendet. Auch wenn zwei Dokumente (Seiten) aus derselben Quelle gleichzeitig einen Bericht für denselben Endpunkt generieren, werden sie nicht zusammengefasst. Dieser Mechanismus dient zur Eindämmung von Datenschutzangriffen. Berichte aus demselben Dokument (Seite) können zusammen gesendet werden.
Unterstützung für Load-Balancing / Prioritäten	Ja	Nein

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.

Hinweis:Da nur Chrome und Edge die Reporting API v0 unterstützen, müssen Sie sich bei der Migration zu v1 nicht auf andere Browser konzentrieren. Es ist jedoch möglich, dass die Unterstützung für weitere Browser hinzukommt. Derzeit gibt es keine Tracking-Fehler für diese Browser, aber das kann sich ändern.

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

Legacy-Code (mit v0)

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

Neuer Code (Übergangscode mit v0 neben v1)

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" }] }

Wenn Ihre Website bereits eine Berichtsfunktion hat, behalten Sie Report-To nur vorübergehend bei (bis die meisten Chrome- und Edge-Clients aktualisiert wurden), um keine Berichte zu verlieren.

Wenn Sie die Netzwerkfehlerprotokollierung benötigen, behalten Sie Report-To bei, bis ein Ersatz für die Netzwerkfehlerprotokollierung verfügbar ist.

Neuer Code (nur mit v1)

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

So kann Ihr Code in Zukunft aussehen, wenn die meisten Chrome- und Edge-Clients aktualisiert wurden und die API v1 unterstützen.

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

Legacy-Code (mit v0), z. B. mit Express

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

Mit v0 können Sie Berichtsendpunkte nur für einige Antworten festlegen. Andere Dokumente (Seiten) in dieser Quelle verwenden automatisch diese Umgebungsendpunkte. Hier werden die für "/" festgelegten Endpunkte für alle Antworten verwendet, z. B. für page1.

Neuer Code (mit v1), z. B. mit Express

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

Mit v1 müssen Sie den Header Reporting-Endpoints für alle Antworten festlegen, die Berichte generieren können.

Migration der CSP-Berichterstellung

Legacy-Code, nur mit report-uri

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

Die Verwendung von report-uri allein wird nicht mehr empfohlen. Wenn Ihr Code so aussieht wie oben, migrieren Sie. Beispiele für neuen Code finden Sie unten (in Grün).

Besserer Legacy-Code mit report-uri und der Anweisung report-to mit dem Header Report-To (v0)

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

Dieser Code ist besser, da er report-to verwendet, den neueren Ersatz für report-uri. report-uri wird weiterhin aus Gründen der Abwärtskompatibilität beibehalten. Einige Browser unterstützen report-to , aber nicht report-uri.

Das könnte noch besser sein: Dieser Code verwendet die Reporting API v0 (Report-To-Header). Migrieren Sie zu v1. Beispiele für neuen Code finden Sie unten (in Grün).

Neuer Code mit report-uri und der Anweisung report-to mit dem Header Reporting-Endpoints (v1)

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

Behalten Sie die Anweisung report-uri neben der Anweisung report-to bei, bis die Anweisung report-to von allen Browsern unterstützt wird. Weitere Informationen finden Sie in der Browserkompatibilitätstabelle.

Behalten Sie Report-To vorübergehend neben Reporting-Endpoints bei. Sobald die meisten Ihrer Chrome- und Edge-Besucher auf Browserversionen ab 96 aktualisiert haben, entfernen Sie 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.