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

Achtung:In diesem Beitrag wird die Migration zur neuen Version der Reporting API (Version 1) erläutert. Wenn Sie die Reporting API noch nicht kennen oder detaillierte Nutzungsbeispiele benötigen, lesen Sie stattdessen den Hauptartikel zur Reporting API.

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.

Hinweis:Die alte Reporting API heißt Reporting API Version 0. Die neue Reporting API heißt Reporting API v1.

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

Achtung: Wenn Sie die Netzwerkfehlerprotokollierung verwenden, verwenden Sie weiterhin Report-To (Version 0), da die Netzwerkfehlerprotokollierung in der Reporting API Version 1 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

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

Version 0 (alt)

 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

{0 verwendet den Report-To-Header, um benannte Endpunktgruppen zu konfigurieren, und die report-to-Direktive 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 Version 1 wird der Reporting-Endpoints-Header 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 Bericht hat einen anderen Umfang.

Version 0 (alt)

Bei Version 0 können Sie Endpunkte für die Berichterstellung nur für einige Antworten festlegen. Andere Dokumente (Seiten) auf diesem Ursprung verwenden diese Umgebungsendpunkte automatisch.

v1 (neu)

Bei Version 1 müssen Sie den Reporting-Endpoints-Header für alle Antworten festlegen, aus denen Berichte generiert werden können.

• 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

	Header der Legacy Reporting API (Version 0) Report-To	Neue Reporting API (Version 1) Reporting-Endpoints-Header
Unterstützte Browser	Chrome 69 und höher und Edge 69 und höher.	Chrome 96 und höher sowie Edge 96 und höher. Firefox wird unterstützt. Safari erhebt keine Einwände. Browsersignale
Endpunkte	Sendet Berichte an mehrere Report-Collectors (mehrere URLs pro Endpunktgruppe definiert).	Sendet Berichte an bestimmte Berichtsabholer (pro Endpunkt wird nur eine URL definiert).
API-Oberfläche	Verwendet die Kopfzeile `Report-To`, um benannte Endpunktgruppen zu konfigurieren.	Verwendet die `Reporting-Endpoints`-Überschrift, um benannte Endpunkte zu konfigurieren.
Berichtstypen, die über diese API generiert werden können	Einstellung Intervention Unfall COOP/COEP Content-Sicherheitsrichtlinie – Stufe 3 (CSP-Ebene 3) Netzwerkfehlerprotokollierung (NEL) Weitere Informationen zu den Berichtstypen finden Sie im Blogpost zur Reports API.	Unverändert, mit Ausnahme der Netzwerkfehlerprotokollierung (NEL): Diese wird in der neuen Reporting API (Version 1) nicht unterstützt.
Berichtsumfang	Herkunft des Dokuments ermitteln und feststellen kann, dass es von dir stammt.  Die Report-To-Überschrift eines Dokuments wirkt sich auf andere Dokumente (Seiten) aus diesem Ursprung aus. Das url-Feld eines Berichts variiert weiterhin je nach Dokument.	Document. Die Reporting-Endpoints-Überschrift eines Dokuments wirkt sich nur auf dieses Dokument aus. Das url-Feld eines Berichts variiert weiterhin je nach Dokument.
Berichtsisolation (Batchverarbeitung)	Unterschiedliche Dokumente (Seiten) oder Websites/Quellen, die etwa zur selben Zeit einen Bericht generieren und denselben Berichtsendpunkt haben, werden in einem Batch zusammengefasst: Sie werden in derselben Nachricht an den Berichtsendpunkt gesendet.	Berichte aus verschiedenen Dokumenten (Seiten) werden nie zusammen gesendet. Auch wenn zwei Dokumente (Seiten) vom selben Ursprung gleichzeitig einen Bericht für denselben Endpunkt generieren, werden diese nicht in einem Batch zusammengefasst. Dies ist ein Mechanismus, um Datenschutzangriffe zu minimieren. Berichte aus demselben Dokument (Seite) können zusammen gesendet werden.
Unterstützung für Load Balancing/Prioritäten	Ja	Nein

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.

Hinweis: Da nur Chrome und Edge die Reporting API v0 unterstützen, müssen Sie sich bei der Migration zu Version 1 nicht auf andere Browser konzentrieren. Beachten Sie jedoch, dass in Zukunft möglicherweise weitere Browser unterstützt werden. Für diese Browser liegen derzeit keine Tracking-Fehler vor, dies kann sich jedoch ändern.

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.

Allerdings unterstützen nur wenige Browser report-to. Daher wird empfohlen, report-uri parallel zur Reporting API zu verwenden (Report-To oder besser, Reporting-Endpoints), 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 tun): Wenn Sie dies noch nicht getan haben, fügen Sie report-to neben report-uri hinzu. In Browsern, die nur report-uri (Firefox) unterstützen, wird report-uri verwendet. In Browsern, die auch report-to (Chrome, Edge) unterstützen, wird report-to verwendet. Verwenden Sie die Überschriften Report-To und Reporting-Endpoints, um die benannten Endpunkte anzugeben, die Sie in report-to verwenden möchten. So erhalten Sie Berichte sowohl von älteren als auch von neueren Chrome- und Edge-Clients.

2. 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. Behalten Sie report-uri bei, damit Sie weiterhin Berichte für Browser erhalten, die nur diese Option unterstützen.

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

Migration: Beispielcode

Übersicht

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

Wenn Sie die alte Reporting API (Version 0) verwenden, um Berichte zu Verstößen für eine CSP (Content-Security-Policy-Header) zu erhalten, müssen Sie Content-Security-Policy im Rahmen der Migration zur neuen Reporting API (Version 1) möglicherweise 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 und 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 Sie auf Ihrer Website bereits Berichtsfunktionen haben, sollten Sie Report-To nur vorübergehend verwenden, bis die meisten Chrome- und Edge-Clients aktualisiert wurden. Andernfalls gehen Berichte verloren.

Wenn Sie die Netzwerkfehlerprotokollierung benötigen, behalten Sie Report-To bis zur Verfügbarkeit eines Ersatzes für die Netzwerkfehlerprotokollierung.

Neuer Code (nur für v1)

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

So könnte Ihr Code in Zukunft aussehen, sobald die meisten Chrome- und Edge-Clients aktualisiert wurden und die API v1 unterstützen.

Mit Version 1 können Sie weiterhin bestimmte Berichtstypen an bestimmte Endpunkte senden. Sie können jedoch nur eine URL pro Endpunkt haben.

Alle Seiten beobachten

Alter Code (mit v0), z. B. mit Express

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

Bei Version 0 können Sie Endpunkte für die Berichterstellung nur für einige Antworten festlegen. Andere Dokumente (Seiten) an diesem Ursprung verwenden diese Umgebungsendpunkte automatisch. 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(...)
});

Bei Version 1 müssen Sie den Reporting-Endpoints-Header für alle Antworten festlegen, die Berichte generieren könnten.

Migration von CSP-Berichten

Älterer Code, nur mit report-uri

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

Die Verwendung von nur report-uri wird nicht mehr empfohlen. Wenn Ihr Code so aussieht, sollten Sie migrieren. Unten finden Sie Beispiele für neuen Code (grün).

Besserer Legacy-Code mit „report-uri“ und der „report-to“-Anweisung 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"

Besser: In diesem Code wird „report-to“ verwendet, der neuere Ersatz für „report-uri“. Aus Gründen der Abwärtskompatibilität wird „report-uri“ weiterhin unterstützt. Einige Browser unterstützen report-to nicht, aber report-uri.

Das könnte aber noch besser sein: In diesem Code wird die Reporting API v0 (Report-To-Header) verwendet. Zur Version 1 migrieren: Siehe die Beispiele für „Neuer Code“ unten (grün).

Neuer Code mit „report-uri“ und der „report-to“-Anweisung mit der Kopfzeile „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: ...

Die report-uri-Anweisung muss parallel zur report-to-Anweisung beibehalten werden, bis die report-to-Anweisung in den Browsern unterstützt wird. Weitere Informationen finden Sie in der Tabelle zur Browserkompatibilität.

Lassen Sie Report-To vorübergehend neben Reporting-Endpoints. Sobald die meisten Ihrer Chrome- und Edge-Besucher auf eine Browserversion höher als 96 umgestiegen sind, 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)

Viele Grüße Ian Clelland, Eiji Kitamura und Milica Mihajlija für ihre Rezensionen und Vorschläge zu diesem Artikel.