Zur Reporting API v1 migrieren

Eine neue Version der Reporting API ist verfügbar. Sie ist datenschutzfreundlicher und wird mit höherer Wahrscheinlichkeit von allen 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 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 größerer Wahrscheinlichkeit plattformübergreifend unterstützt.

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

Zusammenfassung

Websiteentwickler

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 die Berichtsfunktion hinzufügen, verwenden Sie nur die neue Überschrift (Reporting-Endpoints).

⚠️ In beiden Fällen müssen Sie den Reporting-Endpoints-Header für alle Antworten festlegen, aus 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 bei Version 0 wird die Direktive 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 Version 0 und Version 1

	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 sowie 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. Weitere Informationen finden Sie unter Browsersignale.
Endpunkte	Berichte werden an mehrere Berichtsabholer gesendet (mehrere URLs pro Endpunktgruppe).	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`-Headerzeile, um benannte Endpunkte zu konfigurieren.
Berichtstypen, die über diese API generiert werden können	Einstellung Intervention Unfall COOP/COEP Content Security Policy-Ebene 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 dem selben Dokument (derselben Seite) können zusammen gesendet werden.
Unterstützung für Load Balancing / Prioritäten	Ja	Nein

Entwickler von Endpunkten: Mehr Traffic erwartet

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.
• Es werden Tools für die neue Reporting API (Version 1) entwickelt.

Beachten Sie Folgendes:

• 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). Das Protokollieren von Netzwerkfehlern wird derzeit in der Reporting API v1 nicht unterstützt. Es wird ein neuer Mechanismus für die Netzwerkfehlerprotokollierung entwickelt. Bis dahin können Sie die Reporting API v0 verwenden. 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

Ziel dieser Migration ist es, Berichte, die Sie bisher mit Version 0 erhalten haben, nicht zu verlieren.

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. Derzeit gibt es keine Tracking-Fehler für diese Browser. Das 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 (Version 1).
   • Berichte von älteren Chrome- und Edge-Clients dank Report-To (Version 0)

   In Browserinstanzen, die Reporting-Endpoints unterstützen, wird Reporting-Endpoints verwendet. In Instanzen, die Reporting-Endpoints nicht unterstützen, wird auf Report-To zurückgegriffen. 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, bis ein neuer Mechanismus für die Netzwerkfehlerprotokollierung eingeführt wird.

Codebeispiele finden Sie im Migrations-Kochbuch.

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. Diese Funktion 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 des ersten Ansatzes (nur report-uri) wird nicht mehr empfohlen. Der zweite Ansatz bietet einige Vorteile. Insbesondere können Sie damit Berichte für alle Berichtstypen auf dieselbe Weise einrichten und einen generischen Endpunkt festlegen, da alle Berichtsanfragen, die über die Reporting API⏤CSP und andere⏤ generiert werden, dasselbe Format haben application/reports+json.

Allerdings unterstützen nur wenige Browser report-to. Daher wird empfohlen, report-uri neben der Reporting API (Report-To oder besser Reporting-Endpoints) zu verwenden, 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): Fügen Sie report-to neben report-uri hinzu, falls Sie das noch nicht getan haben. 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 von CSP-Berichten.

Migration: Beispielcode

Übersicht

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

Wenn Sie die bisherige Reporting API (Version 0) verwenden, um Verstoßberichte für einen CSP (Content-Security-Policy-Header) zu erhalten, müssen Sie Ihren Content-Security-Policy möglicherweise im Rahmen der Migration zur neuen Reporting API (Version 1) 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 das Netzwerkfehlerprotokoll benötigen, behalten Sie Report-To bis zur Verfügbarkeit eines Ersatzes für das Netzwerkfehlerprotokoll.

Neuer Code (nur mit Version 1)

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. Pro Endpunkt kann jedoch nur eine URL angegeben werden.

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

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, aus denen Berichte generiert werden können.

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 „Report-To (v0)“-Header

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 Überschrift „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: ...

Verwenden Sie die Anweisung report-uri zusammen mit der Anweisung report-to, bis die Anweisung report-to plattformübergreifend 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 (Version 0)
• 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.