Eine neue Version der Reporting API ist verfügbar. Sie ist sicherer und wird eher in verschiedenen Browsern unterstützt.
Die Reporting API informiert Sie über Fehler, die auf Ihrer Website auftreten, wenn Besucher sie verwenden. Sie erhalten unter anderem Einblick in Browsereingriffe, Browserabstürze, Verstöße gegen die Content Security Policy, COOP/COEP-Verstöße und Warnungen zur Einstellung.
Eine neue Version der Reporting API ist verfügbar. Die neue API ist schlanker und wird eher in verschiedenen Browsern unterstützt.
Zusammenfassung
Websiteentwickler
Wenn Sie bereits Berichtsfunktionen für Ihre Website haben: Migrieren Sie zu Version 1, indem Sie den neuen Header (Reporting-Endpoints
) verwenden, aber den alten Header noch eine Zeit lang verwenden (Report-To
).
Weitere Informationen finden Sie unter Migration: Beispielcode.
Wenn Sie Ihrer Website gerade Berichtsfunktionen hinzufügen: Verwenden Sie nur den neuen Header (Reporting-Endpoints
).
⚠️ In beiden Fällen musst du den Reporting-Endpoints
-Header für alle Antworten festlegen, die Berichte generieren könnten.
Entwickler von Meldediensten
Wenn Sie einen Endpunktdienst betreiben oder Ihren eigenen betreiben, müssen Sie mit mehr Traffic rechnen, wenn Sie oder externe Entwickler zur Reporting API Version 1 migrieren (Reporting-Endpoints
-Header).
Lesen Sie weiter, um mehr über Details und Beispielcode zu erfahren.
Logging von Netzwerkfehlern
Für die Protokollierung von Netzwerkfehlern wird ein neuer Mechanismus entwickelt. Sobald diese Funktion verfügbar ist, können Sie von Version 0 der Reporting API zu diesem neuen Mechanismus wechseln.
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 unterschiedlich.
In v0 können Sie Endpunkte für die Berichterstellung nur für bestimmte Antworten festlegen. Andere Dokumente (Seiten) dieses Ursprungs würden diese Inaktivendpunkte automatisch verwenden.
In v1 müssen Sie den Reporting-Endpoints
-Header für alle Antworten festlegen, die Berichte generieren könnten.
- Beide APIs unterstützen dieselben Berichtstypen, mit einer Ausnahme: v1 unterstützt keine Netzwerkfehlerberichte. Weitere Informationen finden Sie in den Migrationsschritten.
- v0 wird nicht in verschiedenen Browsern unterstützt und wird auch in Zukunft nicht unterstützt. In Zukunft wird v1 voraussichtlich in mehreren Browsern unterstützt.
Was unverändert bleibt
- Format und Struktur der Berichte bleiben unverändert.
- Die vom Browser an den Endpunkt gesendete Anfrage bleibt eine
POST
-Anfrage mit dem WertContent-type
application/reports+json
. - Die Zuordnung 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 Version 1 hat keine Auswirkungen auf die
ReportingObserver
.ReportingObserver
erhält 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 oder höher und Edge 69 oder höher. | Chrome 96 oder höher und Edge 96 oder höher. Firefox wird unterstützt. Safari widerspricht nicht. Siehe Browsersignale. |
Endpunkte | Sendet Berichte an einen von mehreren Collectors (mehreren pro Endpunktgruppe sind mehrere URLs definiert). | Sendet Berichte an bestimmte Report-Collectors (nur eine URL pro Endpunkt definiert). |
API-Oberfläche | Verwendet den Header `Report-To` , um benannte Endpunktgruppen zu konfigurieren. |
Verwendet den Header `Reporting-Endpoints` , um benannte Endpunkte zu konfigurieren. |
Berichtstypen, die über diese API erstellt werden können |
|
Unverändert, mit Ausnahme von Netzwerkfehler-Logging (NEL): Dies wird in der neuen Reporting API (Version 1) nicht unterstützt. |
Berichtsumfang | Herkunft des Dokuments ermitteln und feststellen kann, dass es von dir stammt. Der Report-To -Header eines Dokuments wirkt sich auf andere Dokumente (Seiten) aus diesem Ursprung aus.
Das Feld url eines Berichts variiert dennoch je nach Dokument.
|
Document. Der Reporting-Endpoints -Header eines Dokuments wirkt sich nur auf dieses Dokument aus.
Das Feld url eines Berichts variiert dennoch je nach Dokument.
|
Berichtsisolation (Batchverarbeitung) | Verschiedene Dokumente (Seiten) oder Websites/Ursprünge, die ungefähr zur gleichen Zeit einen Bericht generieren und denselben Berichtsendpunkt haben, werden in Batches zusammengefasst. Sie werden in derselben Nachricht an den Endpunkt der Berichterstellung gesendet. |
|
Unterstützung für Load Balancing / Prioritäten | Ja | Nein |
Endpunktentwickler: Mehr Traffic erwarten
Wenn Sie Ihren eigenen Server als Endpunkt für die Berichterstellung eingerichtet haben oder wenn Sie einen Report Collector als Dienst entwickeln oder verwalten, sollten Sie mehr Traffic an diesen Endpunkt erwarten.
Das liegt daran, dass Berichte nicht im Batch mit der Reporting API Version 1 zusammengefasst werden wie mit der Reporting API Version 0. Wenn Anwendungsentwickler zur Reporting API Version 1 migrieren, bleibt die Anzahl der Berichte ähnlich, das Volumen der Anfragen an den Endpunktserver wird jedoch zunehmen.
Anwendungsentwickler: Zu Reporting-Endpoints
migrieren (v1)
Was solltet ihr tun?
Die neue Reporting API (v1) bietet mehrere Vorteile ✅:
- Browsersignale sind positiv, was bedeutet, dass für v1 eine browserübergreifende Unterstützung zu erwarten ist (im Gegensatz zu v0, die nur in Chrome und Edge unterstützt wird).
- Die API ist schlanker.
- Tools werden rund um das neue Reporting API (v1) entwickelt.
Beachten Sie Folgendes:
- Wenn Ihre Website bereits die Reporting API Version 0 mit dem Header
Report-To
verwendet, migrieren Sie zur Reporting API Version 1 (siehe Migrationsschritte). Wenn auf Ihrer Website bereits Berichtsfunktionen für Content-Security-Policy-Verstöße verwendet werden, lesen Sie die Migrationsschritte für CSP-Berichte. - Wenn auf Ihrer Website die Reporting API noch nicht verwendet wird und Sie jetzt Berichtsfunktionen hinzufügen, verwenden Sie die neue Reporting API (Version 1) (
Reporting-Endpoints
-Header). Es gibt jedoch eine Ausnahme: Verwenden SieReport-To
(v0), wenn Sie Netzwerkfehler-Logging verwenden müssen. Netzwerkfehler-Logging wird derzeit in der Reporting API v1 nicht unterstützt. Ein neuer Mechanismus für Netzwerkfehler-Logging wird entwickelt. Verwenden Sie die Reporting API Version 0, bis dieser verfügbar ist. Wenn Sie Netzwerkfehler-Logging neben anderen Berichtstypen benötigen, verwenden Sie sowohlReport-To
(V0) als auchReporting-Endpoints
(V1). Mit v0 erhalten Sie Netzwerkfehler-Logging und v1 liefert Berichte aller anderen Typen.
Migrationsanleitung
Ihr Ziel bei dieser Migration ist es, keine Berichte zu verlieren, die Sie früher mit Version 0 erhalten haben.
Schritt 1 (jetzt ausführen): Verwenden Sie beide Header:
Report-To
(V0) undReporting-Endpoints
(V1).Das bringt Ihnen folgende 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, verwendenReporting-Endpoints
. Instanzen, die dies nicht tun, greifen aufReport-To
zurück. Das Anfrage- und Berichtsformat ist für v0 und v1 gleich.- Berichte von neueren Chrome- und Edge-Clients dank
Schritt 2 (jetzt ausführen): Der Header
Reporting-Endpoints
muss für alle Antworten festgelegt sein, die Berichte generieren können.Mit v0 konnten Sie Endpunkte für die Berichterstellung nur für bestimmte Antworten festlegen. Andere Dokumente (Seiten) an diesem Ursprung würden diesen „Inaktiven“ Endpunkt verwenden. Aufgrund der unterschiedlichen Gültigkeitsbereich müssen Sie bei Version 1 für alle Antworten, die Berichte generieren könnten, den Header
Reporting-Endpoints
festlegen.Schritt 3 (später starten): Sobald alle oder die meisten Ihrer Nutzer auf spätere Chrome- oder Edge-Installationen (Version 96 und höher) aktualisiert haben, entfernen Sie
Report-To
(v0) und behalten Sie nurReporting-Endpoints
bei.Eine Ausnahme: Wenn Sie Berichte zu Netzwerkfehler-Logging benötigen, behalten Sie
Report-To
bei, bis ein neuer Mechanismus für Netzwerkfehler-Logging eingerichtet ist.
Codebeispiele finden Sie im Migrationskochbuch.
Migrationsschritte für CSP-Berichte
Es gibt zwei Möglichkeiten, Berichte über Verstöße gegen Content-Security-Policy zu konfigurieren:
- Mit dem CSP-Header allein über die Anweisung „
report-uri
“. Dieser bietet eine breite Browserunterstützung in Chrome, Firefox, Safari und Edge. Berichte werden mit dem Inhaltstypapplication/csp-report
gesendet und haben ein für CSP entwickeltes Format. Diese Berichte werden als „Berichte der Stufe 2“ bezeichnet und basieren nicht auf der Reporting API. - Bei der Reporting API erfolgt dies über den
Report-To
-Header (alte Version) oder über die neuereReporting-Endpoints
(Version 1). 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 erste Methode (nur report-uri
) wird nicht mehr empfohlen. Die zweite Methode bietet einige Vorteile. Insbesondere können Sie so die Berichterstellung für alle Berichtstypen in einer einzigen Methode einrichten und einen generischen Endpunkt festlegen (da alle Berichtsanfragen, die über die Reporting API – CSP und andere – dasselbe Format haben: application/reports+json
.
report-to
wird jedoch nur von einigen wenigen Browsern unterstützt.
Daher wird empfohlen, report-uri
neben dem Reporting API-Ansatz (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.
Schritt 1 (jetzt ausführen): Fügen Sie
report-to
zusammen mitreport-uri
hinzu, falls Sie dies noch nicht getan haben. Browser, die nurreport-uri
(Firefox) unterstützen, verwendenreport-uri
, Browser, die auchreport-to
unterstützen(Chrome, Edge), verwendenreport-to
. Verwenden Sie zur Angabe der benannten Endpunkte, die Sie inreport-to
verwenden, die beiden HeaderReport-To
undReporting-Endpoints
. Dadurch wird sichergestellt, dass Sie sowohl von älteren als auch von neueren Chrome- und Edge-Clients Berichte erhalten.Schritt 3 (später starten): Sobald alle oder die meisten Ihrer Nutzer auf spätere Chrome- oder Edge-Installationen (Version 96 und höher) aktualisiert haben, entfernen Sie
Report-To
(v0) und behalten Sie nurReporting-Endpoints
bei. Behalten Siereport-uri
bei, damit Sie weiterhin Berichte für Browser erhalten, die diese Funktion unterstützen.
Codebeispiele zu diesen Schritten finden Sie unter Migration der CSP-Berichte.
Migration: Beispielcode
Überblick
Wenn Sie die alte Reporting API (Version 0) verwenden, um Berichte über Verstöße für einen COOP (Header Cross-Origin-Opener-Policy
), einen COEP (Cross-Origin-Embedder-Policy
) oder eine Dokumentrichtlinie (Header Document-Policy
) zu erhalten, müssen Sie diese Richtlinienheader bei der Migration zur Reporting API Version 1 nicht selbst ändern. Sie müssen jedoch vom alten Report-To
-Header zum neuen Reporting-Endpoints
-Header migrieren.
Wenn Sie die alte Reporting API (v0) verwenden, um Berichte über Verstöße für eine CSP (Content-Security-Policy
-Header) zu erhalten, müssen Sie Content-Security-Policy
im Rahmen der Migration zur neuen Reporting API (v1) möglicherweise 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"
Hinweis: Mit v1 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
- Webanwendungen mit der Reporting API überwachen (Hauptbeitrag zur Reporting API)
- Spezifikation: Alte Reporting API (Version 0)
- Spezifikation: Neue Reporting API (Version 1)
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 zu diesem Artikel.