Migreren naar Reporting API v1

Er is een nieuwe versie van de Reporting API beschikbaar. Het is meer privé en wordt waarschijnlijker ondersteund in alle browsers.

Maud Nalpas

Let op: in dit bericht wordt beschreven hoe u kunt migreren naar de nieuwe versie van de Reporting API (v1). Als u nieuw bent bij de Reporting API of gedetailleerde gebruiksvoorbeelden nodig heeft, ga dan naar het hoofdbericht over de Reporting API .

De Reporting API informeert u over fouten die op uw site optreden wanneer bezoekers deze gebruiken. Het geeft u inzicht in browserinterventies, browsercrashes, schendingen van het Content-Security-beleid, COOP/COEP-schendingen, beëindigingswaarschuwingen en meer.

Er is een nieuwe versie van de Reporting API beschikbaar. De nieuwe API is slanker en zal waarschijnlijk in alle browsers worden ondersteund.

Opmerking: De oude Reporting API heet Reporting API v0 . De nieuwe Reporting API heet Reporting API v1 .

Samenvatting

Site-ontwikkelaars

Als u al over rapportagefunctionaliteit voor uw site beschikt : migreer naar v1 met behulp van de nieuwe header ( Reporting-Endpoints ), maar behoud de oude header nog een tijdje ( Report-To ). Zie Migratie: voorbeeldcode .

Als u zojuist rapportagefunctionaliteit aan uw site toevoegt : gebruik alleen de nieuwe header ( Reporting-Endpoints ).

⚠️ Zorg er in beide gevallen voor dat u de header Reporting-Endpoints instelt voor alle reacties die mogelijk rapporten genereren.

Ontwikkelaars van rapportageservices

Als u een eindpuntservice onderhoudt of uw eigen service exploiteert, kunt u meer verkeer verwachten als u of externe ontwikkelaars migreren naar de Reporting API v1 ( Reporting-Endpoints -header).

Blijf lezen voor details en voorbeeldcode!

Netwerkfoutregistratie

Let op: Als u Network Error Logging gebruikt, blijf dan Report-To (v0) gebruiken, omdat Network Error Logging niet wordt ondersteund in de Reporting API v1.

Er zal een nieuw mechanisme voor netwerkfoutregistratie worden ontwikkeld. Zodra dat beschikbaar komt, schakelt u over van Reporting API v0 naar dat nieuwe mechanisme.

Demo en code

• Demosite: nieuwe rapportage-API (v1)
• Code voor de demosite

Verschillen tussen v0 en v1

Wat verandert er

• Het API-oppervlak is anders.

v0 (verouderd)

 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 gebruikt de Report-To -header om benoemde eindpuntgroepen te configureren, en de report-to instructie in andere headers om naar deze eindpuntgroepen te verwijzen.

v1 (nieuw)

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

v1 gebruikt de Reporting-Endpoints header om benoemde eindpunten te configureren. Net als v0 gebruikt het de report-to -richtlijn in andere headers om naar deze eindpuntgroepen te verwijzen.

• De reikwijdte van het rapport is anders.

v0 (verouderd)

Met v0 kunt u rapportage-eindpunten alleen voor bepaalde reacties instellen. Andere documenten (pagina's) op die oorsprong zouden automatisch deze omgevingseindpunten gebruiken.

v1 (nieuw)

Met v1 moet u de header Reporting-Endpoints instellen voor alle reacties die mogelijk rapporten genereren.

• Beide API's ondersteunen dezelfde rapporttypen, met één uitzondering: v1 ondersteunt geen netwerkfoutrapporten . Lees meer in de migratiestappen .
• v0 wordt niet ondersteund in browsers en zal dit ook niet worden ondersteund. Het is waarschijnlijker dat v1 in de toekomst door meerdere browsers wordt ondersteund.

Wat onveranderd blijft

• Het formaat en de structuur van de rapporten zijn ongewijzigd.
• Het verzoek dat door de browser naar het eindpunt wordt verzonden, blijft een POST verzoek van Content-type application/reports+json .
• Het toewijzen van bepaalde eindpunten aan bepaalde rapporttypen wordt ondersteund in zowel v0 als v1.
• De rol van het default blijft ongewijzigd.

• De Reporting API v1 heeft geen invloed op de ReportingObserver . ReportingObserver blijft toegang krijgen tot alle waarneembare rapporten, en hun formaat is identiek.

Alle verschillen tussen v0 en v1

	Verouderde rapportage-API (v0) Report-To koptekst	Nieuwe rapportage-API (v1) Koptekst Reporting-Endpoints
Browser-ondersteuning	Chroom 69+ en Edge 69+.	Chroom 96+ en Edge 96+. Firefox ondersteunt. Safari heeft geen bezwaar. Zie browsersignalen .
Eindpunten	Verzendt rapporten naar meerdere rapportverzamelaars (meerdere URL's gedefinieerd per eindpuntgroep).	Verzendt rapporten naar specifieke rapportverzamelaars (slechts één URL gedefinieerd per eindpunt).
API-oppervlak	Gebruikt de header `Report-To` om benoemde eindpuntgroepen te configureren.	Gebruikt de header `Reporting-Endpoints` om benoemde eindpunten te configureren.
Typen rapporten die via deze API kunnen worden gegenereerd	Afschrijving Interventie Crash COOP/COEP Inhoudsbeveiligingsbeleid niveau 3 (CSP niveau 3) Netwerkfoutregistratie (NEL) Lees meer over de rapporttypen in het Reporting API-bericht .	Ongewijzigd, behalve van Network Error Logging (NEL): dit wordt niet ondersteund in de nieuwe Reporting API (v1) .
Rapportbereik	Oorsprong. Report-To koptekst van een document heeft invloed op andere documenten (pagina's) vanaf die oorsprong. Het url veld van een rapport verschilt nog steeds per document.	Document. Reporting-Endpoints header van een document heeft alleen invloed op dat document. Het url veld van een rapport verschilt nog steeds per document.
Rapportisolatie (batching)	Verschillende documenten (pagina's) of sites/oorsprongen die rond dezelfde tijd een rapport genereren en die hetzelfde rapportage-eindpunt hebben, worden samengevoegd: ze worden in hetzelfde bericht naar het rapportage-eindpunt verzonden.	Rapporten uit verschillende documenten (pagina's) worden nooit samen verzonden. Zelfs als twee documenten (pagina's) van dezelfde oorsprong tegelijkertijd een rapport genereren voor hetzelfde eindpunt, worden deze niet in batches verwerkt. Dit is een mechanisme om privacyaanvallen te beperken. Rapporten uit hetzelfde document (pagina) kunnen samen worden verzonden.
Ondersteuning voor taakverdeling/prioriteiten	Ja	Nee

Eindpuntontwikkelaars: verwacht meer verkeer

Als u uw eigen server als rapportage-eindpunt hebt ingesteld, of als u een rapportverzamelaar als service ontwikkelt of onderhoudt, kunt u meer verkeer naar dat eindpunt verwachten.

Dit komt omdat rapporten niet in batches worden verwerkt met de Reporting API v1, zoals wel het geval is met de Reporting API v0. Naarmate applicatieontwikkelaars beginnen te migreren naar de Reporting API v1, zal het aantal rapporten dus vergelijkbaar blijven, maar zal het aantal verzoeken aan de eindpuntserver toenemen.

Applicatieontwikkelaars: migreren naar Reporting-Endpoints (v1)

Wat moet je doen?

Het gebruik van de nieuwe Reporting API (v1) heeft verschillende voordelen ✅:

• Browsersignalen zijn positief , wat betekent dat ondersteuning voor meerdere browsers kan worden verwacht voor v1 (in tegenstelling tot v0 die alleen wordt ondersteund in Chrome en Edge).
• De API is slanker.
• Er wordt tooling ontwikkeld rond de nieuwe Reporting API (v1).

Met dit in gedachten:

• Als uw site al gebruikmaakt van de Reporting API v0 met de Report-To -header, migreer dan naar de Reporting API v1 (zie de migratiestappen ). Als uw site al rapportagefunctionaliteit gebruikt voor schendingen van het Content-Security-beleid, controleer dan de specifieke migratiestappen voor CSP-rapportage .
• Als uw site de Reporting API nog niet gebruikt en u nu rapportagefunctionaliteit toevoegt: gebruik de nieuwe Reporting API (v1) (de Reporting-Endpoints -header). Hierop bestaat één uitzondering : als u Network Error Logging wilt gebruiken, gebruik dan Report-To (v0). Netwerkfoutregistratie wordt momenteel niet ondersteund in de Reporting API v1. Er zal een nieuw mechanisme voor netwerkfoutregistratie worden ontwikkeld⏤totdat dit beschikbaar is, kunt u de Reporting API v0 gebruiken. Als u netwerkfoutregistratie nodig heeft naast andere rapporttypen, gebruikt u zowel Report-To (v0) als Reporting-Endpoints (v1). v0 biedt u netwerkfoutregistratie en v1 geeft u rapporten van alle andere typen.

Migratie stappen

Uw doel bij deze migratie is om geen rapporten kwijt te raken die u voorheen met v0 kreeg.

Opmerking: Omdat alleen Chrome en Edge de Reporting API v0 ondersteunen, hoeft u zich tijdens uw migratie naar v1 niet op andere browsers te concentreren. Houd er echter rekening mee dat er mogelijk bredere browserondersteuning komt. Er zijn momenteel geen trackingbugs voor deze browsers, maar dit kan veranderen.

1. Stap 1 (nu doen) : Gebruik beide headers: Report-To (v0) en Reporting-Endpoints (v1).

   Hiermee krijg je:

   • Rapporten van nieuwere Chrome- en Edge-clients dankzij Reporting-Endpoints (v1).
   • Rapporten van oudere Chrome- en Edge-clients dankzij Report-To (v0).

   Browserinstanties die Reporting-Endpoints ondersteunen, zullen Reporting-Endpoints gebruiken, en instanties die dat niet doen, zullen terugvallen op Report-To . Het aanvraag- en rapportformaat is hetzelfde voor v0 en v1.

2. Stap 2 (nu doen): Zorg ervoor dat de header Reporting-Endpoints is ingesteld op alle reacties die mogelijk rapporten genereren.

   Met v0 kunt u ervoor kiezen om rapportage-eindpunten alleen voor bepaalde reacties in te stellen, terwijl andere documenten (pagina's) op die oorsprong dit 'omgevings'-eindpunt zouden gebruiken. Met v1 moet u vanwege het verschil in bereik de header Reporting-Endpoints instellen voor alle reacties die mogelijk rapporten genereren.

3. Stap 3 (begin later): Zodra alle of de meeste van uw gebruikers zijn bijgewerkt naar latere Chrome- of Edge-installaties (96 en hoger), verwijdert u Report-To (v0) en behoudt u alleen Reporting-Endpoints .

   Eén uitzondering: als u rapporten over het loggen van netwerkfouten nodig heeft, kunt u Report-To gebruiken totdat er een nieuw mechanisme voor het loggen van netwerkfouten beschikbaar is.

Zie codevoorbeelden in het migratiekookboek .

Migratiestappen voor CSP-rapportage

Er zijn twee manieren waarop rapporten over schendingen van het Content-Security-beleid kunnen worden geconfigureerd:

• Met alleen de CSP-header via de report-uri -richtlijn. Dit heeft brede browserondersteuning, in Chrome, Firefox, Safari en Edge. Rapporten worden verzonden met het inhoudstype application/csp-report en hebben een indeling die specifiek is voor CSP. Deze rapporten worden 'CSP Level 2-rapporten' genoemd en zijn niet afhankelijk van de Reporting API.
• Met de Reporting API is dat via Report-To header (legacy) of de nieuwere Reporting-Endpoints (v1). Dit wordt alleen ondersteund in Chrome en Edge. Rapportaanvragen hebben dezelfde indeling als andere Reporting API-aanvragen en hetzelfde inhoudstype application/reports+json .

Het gebruik van de eerste benadering (alleen report-uri ) wordt niet langer aanbevolen en het gebruik van de tweede benadering heeft enkele voordelen. Het stelt u met name in staat om op één manier rapportage in te stellen voor alle rapporttypen en om een ​​generiek eindpunt in te stellen (omdat alle rapportverzoeken die via de Reporting API⏤CSP en andere⏤worden gegenereerd dezelfde indeling hebben application/reports+json .

Slechts enkele browsers ondersteunen echter report-to . Het wordt daarom aanbevolen om report-uri te gebruiken naast de Reporting API-aanpak ( Report-To of beter, Reporting-Endpoints ) om CSP-schendingsrapporten van meerdere browsers te ontvangen. In een browser die report-uri en report-to herkent, wordt report-uri genegeerd als report-to aanwezig is. In een browser die alleen report-uri herkent, wordt alleen report-uri in aanmerking genomen.

1. Stap 1 (nu doen) : Als u het nog niet heeft toegevoegd, voegt u report-to naast report-uri . Browsers die alleen report-uri ondersteunen (Firefox) zullen report-uri gebruiken, en browsers die ook report-to ondersteunen (Chrome, Edge) zullen report-to gebruiken. Als u de benoemde eindpunten wilt opgeven die u in report-to gaat gebruiken, gebruikt u de headers Report-To en Reporting-Endpoints . Dit zorgt ervoor dat u rapporten ontvangt van zowel oudere als nieuwere Chrome- en Edge-clients.

2. Stap 3 (begin later): Zodra alle of de meeste van uw gebruikers zijn bijgewerkt naar latere Chrome- of Edge-installaties (96 en hoger), verwijdert u Report-To (v0) en behoudt u alleen Reporting-Endpoints . Bewaar report-uri zodat u nog steeds rapporten ontvangt voor browsers die dit alleen ondersteunen.

Zie codevoorbeelden voor deze stappen bij de migratie van CSP-rapportage .

Migratie: voorbeeldcode

Overzicht

Als u de verouderde Reporting API (v0) gebruikt om overtredingsrapporten te ontvangen voor een COOP ( Cross-Origin-Opener-Policy header), een COEP ( Cross-Origin-Embedder-Policy ) of een documentbeleid ( Document-Policy header ): u hoeft deze beleidsheaders zelf niet te wijzigen wanneer u migreert naar Reporting API v1. Wat u wel nodig heeft, is migreren van de oude Report-To -header naar de nieuwe Reporting-Endpoints -header.

Als u de oude Reporting API (v0) gebruikt om schendingsrapporten te ontvangen voor een CSP ( Content-Security-Policy header), moet u mogelijk uw Content-Security-Policy aanpassen als onderdeel van uw migratie naar de nieuwe Reporting API ( v1).

Basismigratie

Verouderde code (met v0)

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

Nieuwe code (transitiecode met v0 naast 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" }] }

Als u al over rapportagefunctionaliteit op uw site beschikt, kunt u Report-To slechts tijdelijk gebruiken (totdat de meeste Chrome- en Edge-clients zijn bijgewerkt) om te voorkomen dat rapporten verloren gaan.

Als u Network Error Logging nodig heeft, gebruik dan Report-To totdat vervanging voor Network Error Logging beschikbaar komt .

Nieuwe code (alleen met v1)

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

Zo kan uw code er in de toekomst uitzien, zodra de meeste Chrome- en Edge-clients zijn bijgewerkt en de API v1.

Houd er rekening mee dat u met v1 nog steeds specifieke rapporttypen naar specifieke eindpunten kunt verzenden. Maar u kunt slechts één URL per eindpunt hebben.

Alle pagina's observeren

Legacy code (met v0), bijvoorbeeld met Express

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

Met v0 kunt u rapportage-eindpunten alleen voor bepaalde reacties instellen. Andere documenten (pagina's) op die oorsprong gebruiken automatisch deze omgevingseindpunten. Hier worden de eindpunten die zijn ingesteld voor "/" gebruikt voor alle reacties, bijvoorbeeld voor page1 .

Nieuwe code (met v1), bijvoorbeeld met 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(...)
});

Met v1 moet u de header Reporting-Endpoints instellen voor alle reacties die mogelijk rapporten genereren.

Migratie van CSP-rapportage

Verouderde code, alleen met report-uri

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

Het gebruik van alleen report-uri wordt niet langer aanbevolen . Als uw code er zoals hierboven uitziet, migreer dan. Zie de nieuwe codevoorbeelden hieronder (in groen).

Betere oudere code, met report-uri en de report-to-richtlijn met de 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"

Dit is beter: deze code gebruikt report-to, de nieuwere vervanging van report-uri. Het houdt nog steeds report-uri bij voor achterwaartse compatibiliteit; verschillende browsers ondersteunen report-to niet, maar wel report-uri .

Toch kan dit beter: deze code maakt gebruik van de Reporting API v0 ( Report-To header). Migreren naar v1: zie onderstaande voorbeelden van 'Nieuwe code' (in groen).

Nieuwe code, met report-uri en de report-to-richtlijn met de 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: ...

Laat de report-uri -richtlijn naast de report-to -richtlijn staan ​​totdat de report-to -richtlijn in alle browsers wordt ondersteund. Zie de browsercompatibiliteitstabel .

Bewaar Report-To tijdelijk naast Reporting-Endpoints . Zodra de meeste van uw Chrome- en Edge-bezoekers zijn geüpgraded naar 96+ browserversies, verwijdert u Report-To .

Verder lezen

• Monitor uw webapplicatie met de Reporting API (hoofdpost over de Reporting API)
• Specificatie: verouderde Reporting API (v0)
• Specificatie: nieuwe Reporting API (v1)

Met veel dank aan Ian Clelland, Eiji Kitamura en Milica Mihajlija voor hun recensies en suggesties voor dit artikel.