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

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.

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

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.

 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 Bericht hat einen anderen Umfang.

• 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 plattformübergreifend 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

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

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 bei, bis ein neuer Mechanismus für die Netzwerkfehlerprotokollierung eingeführt wird.

Codebeispiele finden Sie im Migrations-Rezeptbuch.

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 alte 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

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