Migreren naar Reporting API v1

Er is een nieuwe versie van de Reporting API beschikbaar. Deze is privacyvriendelijker en wordt waarschijnlijk door meer browsers ondersteund.

Maud Nalpas

Let op: Dit bericht beschrijft hoe u kunt migreren naar de nieuwe versie van de Reporting API (v1). Als u nog niet bekend bent met de Reporting API of gedetailleerde gebruiksvoorbeelden nodig hebt, ga dan naar het hoofdbericht over de Reporting API .

De rapportage-API informeert u over fouten die zich voordoen op uw website wanneer bezoekers deze gebruiken. Het biedt u inzicht in browserinterventies, browsercrashes, schendingen van het Content Security Policy (CSPB), COOP/COEP-schendingen, waarschuwingen voor verouderde functies en meer.

Er is een nieuwe versie van de Reporting API beschikbaar. De nieuwe API is compacter en wordt waarschijnlijk door meer browsers ondersteund.

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

Samenvatting

Websiteontwikkelaars

Als uw site al rapportagefunctionaliteit heeft : migreer dan naar versie 1 met behulp van de nieuwe header ( Reporting-Endpoints ), maar behoud de oude header ( Report-To ) nog enige tijd. Zie Migratie: voorbeeldcode .

Als je nu rapportagefunctionaliteit aan je site toevoegt : gebruik dan 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.

Rapportageserviceontwikkelaars

Als u een endpointservice onderhoudt of zelf een endpointservice beheert, kunt u meer verkeer verwachten naarmate u of externe ontwikkelaars migreren naar de Reporting API v1 ( Reporting-Endpoints -header).

Lees verder voor meer details en voorbeeldcode!

Netwerkfoutregistratie

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

Er wordt een nieuw mechanisme voor het loggen van netwerkfouten ontwikkeld. Zodra dat beschikbaar is, kunt u overschakelen 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?

• De API-interface is anders.

v0 (legacy)

 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 richtlijn 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 (legacy)

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

v1 (nieuw)

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

• Beide API's ondersteunen dezelfde rapporttypen, met één uitzondering: versie 1 ondersteunt geen netwerkfoutrapporten . Lees meer in de migratiestappen .
• Versie 0 wordt niet en zal niet door alle browsers worden ondersteund. Versie 1 zal naar verwachting in de toekomst wel door meerdere browsers worden ondersteund.

Wat blijft onveranderd?

• De opmaak en structuur van de rapporten blijven ongewijzigd.
• Het verzoek dat de browser naar het eindpunt stuurt, blijft een POST verzoek met Content-type application/reports+json .
• Het toewijzen van bepaalde eindpunten aan bepaalde rapporttypen wordt zowel in versie 0 als in versie 1 ondersteund.
• De rol van het default eindpunt blijft ongewijzigd.

• De Reporting API v1 heeft geen invloed op de ReportingObserver . ReportingObserver behoudt toegang tot alle observeerbare rapporten en het formaat ervan blijft identiek.

Alle verschillen tussen v0 en v1

	Legacy Reporting API (v0) Report-To koptekst	Nieuwe rapportage-API (v1) Reporting-Endpoints koptekst
Browserondersteuning	Chrome 69+ en Edge 69+.	Chrome 96+ en Edge 96+. Firefox ondersteunt het. Safari heeft er geen bezwaar tegen. Zie browsersignalen .
Eindpunten	Verstuurt rapporten naar een van de meerdere rapportverzamelaars (meerdere URL's gedefinieerd per eindpuntgroep).	Verstuurt rapporten naar specifieke rapportverzamelaars (er is slechts één URL per eindpunt gedefinieerd).
API-oppervlak	Gebruikt de `Report-To` header om benoemde eindpuntgroepen te configureren.	Gebruikt de `Reporting-Endpoints` header om benoemde eindpunten te configureren.
Soorten rapporten die via deze API kunnen worden gegenereerd	Afschrijving Interventie Botsing COOP/COEP Content-Security-Policy Level 3 (CSP Level 3) Netwerkfoutregistratie (NEL) Lees meer over de verschillende rapporttypen in het artikel over de rapportage-API .	Onveranderd, behalve wat betreft netwerkfoutregistratie (NEL): dit wordt niet ondersteund in de nieuwe rapportage-API (v1) .
Rapportbereik	Oorsprong. Report-To header van een document is van invloed op andere documenten (pagina's) van die oorsprong. Het url veld van een rapport verschilt echter per document.	Document. Reporting-Endpoints -header van een document is alleen van invloed op dat document. Het url veld van een rapport verschilt nog steeds per document.
Rapportisolatie (batchverwerking)	Verschillende documenten (pagina's) of sites/bronnen die rond hetzelfde tijdstip een rapport genereren en die hetzelfde rapportage-eindpunt hebben, worden gebundeld: ze worden in hetzelfde bericht naar het rapportage-eindpunt verzonden.	Rapporten van verschillende documenten (pagina's) worden nooit tegelijk verzonden. Zelfs als twee documenten (pagina's) van dezelfde bron tegelijkertijd een rapport genereren voor hetzelfde eindpunt, worden deze niet gebundeld. Dit is een mechanisme om privacyaanvallen te voorkomen. Rapporten die betrekking hebben op hetzelfde document (pagina) mogen samen worden verzonden.
Ondersteuning voor taakverdeling / prioriteiten	Ja	Nee

Ontwikkelaars van eindpunten: 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 doordat rapporten met de Reporting API v1 niet in batches worden verwerkt zoals met de Reporting API v0. Daarom zal het aantal rapporten gelijk blijven wanneer applicatieontwikkelaars overstappen naar de Reporting API v1, maar het aantal verzoeken aan de endpointserver zal toenemen.

Applicatieontwikkelaars: Migreer naar Reporting-Endpoints (v1)

Wat moet je doen?

Het gebruik van de nieuwe Reporting API (v1) biedt diverse voordelen ✅:

• De signalen van de browsers zijn positief , wat betekent dat er voor v1 ondersteuning voor meerdere browsers verwacht kan worden (in tegenstelling tot v0, dat alleen in Chrome en Edge wordt ondersteund).
• De API is gestroomlijnder.
• Er wordt momenteel tooling ontwikkeld rondom 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 gebruikmaakt van rapportagefunctionaliteit voor schendingen van het Content Security Policy, raadpleeg dan de specifieke migratiestappen voor CSP-rapportage .
• Als uw site de Reporting API nog niet gebruikt en u nu rapportagefunctionaliteit toevoegt: gebruik dan de nieuwe Reporting API (v1) (de Reporting-Endpoints -header). Er is één uitzondering : als u netwerkfoutregistratie nodig hebt, gebruik dan Report-To (v0). Netwerkfoutregistratie wordt momenteel niet ondersteund in Reporting API v1. Er wordt een nieuw mechanisme voor netwerkfoutregistratie ontwikkeld; tot die tijd gebruikt u Reporting API v0. Als u netwerkfoutregistratie nodig hebt in combinatie met andere rapporttypen, gebruik dan zowel Report-To (v0) als Reporting-Endpoints (v1). v0 biedt netwerkfoutregistratie en v1 biedt rapporten van alle andere typen.

Migratiestappen

Het doel van deze migratie is om de rapporten die u met v0 ontving, niet te verliezen .

Let op: Omdat alleen Chrome en Edge de Reporting API v0 ondersteunen, hoeft u zich tijdens uw migratie naar v1 niet op andere browsers te richten. Houd er echter rekening mee dat bredere browserondersteuning mogelijk in de toekomst zal plaatsvinden. Er zijn momenteel geen bugs gevonden voor deze browsers, maar dit kan veranderen.

1. Stap 1 (nu uitvoeren) : 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, gebruiken Reporting-Endpoints , en instanties die dat niet doen, vallen terug op Report-To . Het aanvraag- en rapportformaat is hetzelfde voor v0 en v1.

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

   Met versie 0 kon je ervoor kiezen om rapportage-eindpunten alleen voor bepaalde reacties in te stellen, en andere documenten (pagina's) van die oorsprong zouden dit 'omgevings'-eindpunt gebruiken. Met versie 1 moet je, vanwege het verschil in bereik, de header Reporting-Endpoints instellen voor alle reacties die mogelijk rapporten genereren.

3. Stap 3 (start later): Zodra al uw gebruikers of de meeste gebruikers zijn overgestapt naar een recentere versie van Chrome of Edge (96 en later), verwijdert u Report-To (v0) en behoudt u alleen Reporting-Endpoints .

   Eén uitzondering: als u toch rapporten over netwerkfouten nodig hebt, behoud dan Report-To totdat er een nieuw mechanisme voor netwerkfoutenregistratie beschikbaar is.

Zie de codevoorbeelden in het migratiehandboek .

Migratiestappen voor CSP-rapportage

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

• Met alleen de CSP-header via de report-uri richtlijn. Dit wordt breed ondersteund door browsers zoals Chrome, Firefox, Safari en Edge. Rapporten worden verzonden met het contenttype application/csp-report en hebben een formaat dat specifiek is voor CSP. Deze rapporten worden "CSP Level 2-rapporten" genoemd en zijn niet afhankelijk van de Reporting API.
• Met de Reporting API kan dat via Report-To header (legacy) of de nieuwere Reporting-Endpoints (v1). Dit wordt alleen ondersteund in Chrome en Edge. Rapportverzoeken hebben dezelfde opmaak als andere Reporting API-verzoeken en hetzelfde content-type application/reports+json .

Het gebruik van de eerste methode (alleen report-uri ) wordt niet langer aanbevolen en de tweede methode biedt een aantal voordelen. Met name kunt u hiermee op één manier rapportage instellen voor alle rapporttypen en een generiek eindpunt definiëren (omdat alle rapportaanvragen die via de Reporting API, CSP en andere API's worden gegenereerd, dezelfde indeling application/reports+json .

Slechts een paar browsers ondersteunen echter report-to . Daarom wordt aangeraden om report-uri te behouden naast de Reporting API-aanpak ( Report-To of beter nog, Reporting-Endpoints ) om CSP-schendingsrapporten van meerdere browsers te ontvangen. In een browser die report-uri als 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 overweging genomen.

1. Stap 1 (nu doen) : Als je het nog niet hebt toegevoegd, voeg dan report-to toe naast report-uri . Browsers die alleen report-uri ondersteunen (Firefox) gebruiken report-uri , en browsers die ook report-to ondersteunen (Chrome, Edge) gebruiken report-to . Om de benoemde eindpunten te specificeren die je in report-to wilt gebruiken, gebruik je zowel de headers Report-To als Reporting-Endpoints . Dit zorgt ervoor dat je rapporten ontvangt van zowel oudere als nieuwere Chrome- en Edge-clients.

2. Stap 3 (start later): Zodra al uw gebruikers of de meeste van uw gebruikers zijn overgestapt naar een recentere versie van Chrome of Edge (96 en later), verwijdert u Report-To (v0) en behoudt u alleen Reporting-Endpoints . Behoud report-uri zodat u nog steeds rapporten ontvangt voor browsers die deze ondersteunen.

Zie de codevoorbeelden voor deze stappen in de CSP-rapportagemigratie .

Migratie: voorbeeldcode

Overzicht

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

Als u de oude Reporting API (v0) gebruikt om rapporten over schendingen van een CSP ( Content-Security-Policy header) te verkrijgen, 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 (overgangscode 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 uw site al rapportagefunctionaliteit heeft, kunt u Report-To tijdelijk behouden (totdat de meeste Chrome- en Edge-clients zijn bijgewerkt) om te voorkomen dat rapporten verloren gaan.

Als u netwerkfoutregistratie nodig hebt, behoud dan Report-To totdat een vervanging voor netwerkfoutregistratie beschikbaar is .

Nieuwe code (alleen voor 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 API v1 ondersteunen.

Houd er rekening mee dat je met versie 1 nog steeds specifieke rapporttypen naar specifieke eindpunten kunt sturen. Je kunt echter slechts één URL per eindpunt hebben.

Alle pagina's bekijken

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 instellen voor slechts bepaalde reacties. 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 versie 1), 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 versie 1 moet u de header Reporting-Endpoints instellen voor alle reacties die mogelijk rapporten genereren.

CSP-rapportagemigratie

Verouderde code, met alleen 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).

Verbeterde legacy-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 voor `report-uri`. `report-uri` blijft behouden voor achterwaartse compatibiliteit; verschillende browsers ondersteunen report-to niet, maar wel report-uri .

Toch kan dit nog beter: deze code gebruikt de Reporting API v0 ( Report-To header). Migreer naar v1: zie de 'Nieuwe code'-voorbeelden hieronder (in groen).

Nieuwe code, met report-uri en de report-to-richtlijn met de Reporting-Endpoints (v1)-header.

Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Reporting-Endpoints: main-endpoint="https://reports.example/main"
Report-To: ...

Houd de report-uri -richtlijn naast de report-to -richtlijn totdat de report-to richtlijn door alle browsers wordt ondersteund. Zie de tabel met browsercompatibiliteit .

Laat Report-To tijdelijk naast Reporting-Endpoints staan. Zodra de meeste bezoekers van Chrome en Edge zijn overgestapt naar browserversie 96 of hoger, kunt u Report-To verwijderen.

Verder lezen

• Monitor uw webapplicatie met de Reporting API (hoofdartikel over de Reporting API)
• Specificatie: legacy Reporting API (v0)
• Specificatie: nieuwe rapportage-API (v1)

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