Esegui la migrazione all'API di reporting v1

È disponibile una nuova versione dell'API di reporting. È più privata e più probabile che sia supportata su tutti i browser.

Maud Nalpas

L'API di reporting ti informa sugli errori che si verificano sul tuo sito quando i visitatori lo utilizzano. Ti offre visibilità sugli interventi del browser, sugli arresti anomali del browser, sulle violazioni di Content-Security-Policy, sulle violazioni di COOP/COEP, sugli avvisi di ritiro e altro ancora.

È disponibile una nuova versione dell'API di reporting. La nuova API è più snella e più probabile che sia supportata su tutti i browser.

Riepilogo

Sviluppatori di siti

Se hai già una funzionalità di reporting per il tuo sito: esegui la migrazione alla versione v1 utilizzando la nuova intestazione (Reporting-Endpoints), ma mantieni l'intestazione legacy per un po' di tempo (Report-To). Vedi Migrazione: esempio di codice.

Se stai aggiungendo la funzionalità di reporting al tuo sito in questo momento: utilizza solo la nuova intestazione (Reporting-Endpoints).

⚠️ In entrambi i casi, assicurati di impostare l'intestazione Reporting-Endpoints su tutte le risposte che potrebbero generare report.

Sviluppatori di servizi di reporting

Se gestisci un servizio di endpoint o ne gestisci uno tuo, prevedi più traffico man mano che tu o gli sviluppatori esterni eseguite la migrazione all'API di reporting v1 (intestazione Reporting-Endpoints).

Continua a leggere per i dettagli e l'esempio di codice.

Registrazione degli errori di rete

Verrà sviluppato un nuovo meccanismo per la registrazione degli errori di rete. Una volta disponibile, passa dall'API di reporting v0 a questo nuovo meccanismo.

Demo e codice

• Sito demo: nuova API di reporting (v1)
• Codice per il sito demo

Differenze tra v0 e v1

Che cosa cambia

• La piattaforma API è diversa.

 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

• L'ambito del report è diverso.

• Entrambe le API supportano gli stessi tipi di report, con un'eccezione: la versione v1 non supporta i report sugli errori di rete. Scopri di più nei passaggi di migrazione.
• La versione v0 non è e non sarà supportata su tutti i browser. In futuro, è più probabile che la versione v1 sia supportata su più browser.

Che cosa rimane invariato

• Il formato e la struttura dei report rimangono invariati.
• La richiesta inviata dal browser all'endpoint rimane una richiesta POST di Content-type application/reports+json.
• Il mapping di determinati endpoint a determinati tipi di report è supportato sia nella versione v0 sia nella versione v1.
• Il ruolo dell'endpoint default rimane invariato.

• L'API di reporting v1 non ha alcun impatto su ReportingObserver. ReportingObserver continua ad avere accesso a tutti i report osservabili e il loro formato è identico.

Tutte le differenze tra v0 e v1

Sviluppatori di endpoint: prevedete più traffico

Se hai configurato il tuo server come endpoint di reporting o se stai sviluppando o gestendo un agente di raccolta di report come servizio, prevedi più traffico verso questo endpoint.

Questo perché i report non vengono raggruppati con l'API di reporting v1 come con l'API di reporting v0. Di conseguenza, man mano che gli sviluppatori di applicazioni iniziano la migrazione all'API di reporting v1, il numero di report rimarrà simile, ma il volume di richieste al server dell'endpoint aumenterà.

Sviluppatori di applicazioni: eseguite la migrazione a Reporting-Endpoints (v1)

Cosa dovresti fare?

L'utilizzo della nuova API di reporting (v1) offre diversi vantaggi ✅:

• I segnali del browser sono positivi, il che significa che è possibile prevedere il supporto cross-browser per la versione v1 (a differenza della versione v0, supportata solo in Chrome ed Edge).
• L'API è più snella.
• Sono in fase di sviluppo strumenti basati sulla nuova API di reporting (v1).

Tenendo presente quanto sopra:

• Se il tuo sito utilizza già l'API di reporting v0 con l'intestazione Report-To, esegui la migrazione all' API di reporting v1 (vedi i passaggi di migrazione). Se il tuo sito utilizza già la funzionalità di reporting per le violazioni di Content-Security-Policy, controlla i passaggi di migrazione specifici per il reporting CSP.
• Se il tuo sito non utilizza ancora l'API di reporting e ora stai aggiungendo la funzionalità di reporting: utilizza la nuova API di reporting (v1) (l'intestazione Reporting-Endpoints). Esiste un'eccezione a questo: se devi utilizzare la registrazione degli errori di rete, utilizza Report-To (v0). La registrazione degli errori di rete non è attualmente supportata nell'API di reporting v1. Verrà sviluppato un nuovo meccanismo per la registrazione degli errori di rete. Fino a quando non sarà disponibile, utilizza l'API di reporting v0. Se hai bisogno della registrazione degli errori di rete insieme ad altri tipi di report, utilizza sia Report-To (v0) sia Reporting-Endpoints (v1). La versione v0 ti offre la registrazione degli errori di rete e la versione v1 ti offre report di tutti gli altri tipi.

Passi per la migrazione

L'obiettivo di questa migrazione è non perdere i report che ricevevi con la versione v0.

1. Passaggio 1 (esegui ora): utilizza entrambe le intestazioni: Report-To (v0) e Reporting-Endpoints (v1).

   In questo modo, ottieni:

   • Report dei client Chrome ed Edge più recenti grazie a Reporting-Endpoints (v1).
   • Report dei client Chrome ed Edge meno recenti grazie a Report-To (v0).

   Le istanze del browser che supportano Reporting-Endpoints utilizzeranno Reporting-Endpoints, mentre le istanze che non lo supportano eseguiranno il fallback a Report-To. Il formato della richiesta e del report è lo stesso per la versione v0 e la versione v1.

2. Passaggio 2 (esegui ora): assicurati che l'intestazione Reporting-Endpoints sia impostata su tutte le risposte che potrebbero generare report.

   Con la versione v0, puoi scegliere di impostare gli endpoint di reporting solo su alcune risposte e altri documenti (pagine) di questa origine utilizzerebbero questo endpoint "ambientale". Con la versione v1, a causa della differenza di ambito, devi impostare l'intestazione Reporting-Endpoints su tutte le risposte che potrebbero generare report.

3. Passaggio 3 (inizia in un secondo momento): una volta che tutti o la maggior parte degli utenti hanno eseguito l'aggiornamento alle installazioni di Chrome o Edge più recenti (96 e versioni successive), rimuovi Report-To (v0) e mantieni solo Reporting-Endpoints.

   Un'eccezione: se hai bisogno di report sulla registrazione degli errori di rete, mantieni Report-To finché non sarà disponibile un nuovo meccanismo per la registrazione degli errori di rete.

Vedi esempi di codice nel ricettario di migrazione.

Passaggi di migrazione per il reporting CSP

Esistono due modi per configurare i report sulle violazioni di Content-Security-Policy:

• Solo con l'intestazione CSP tramite la direttiva report-uri. Questa direttiva è ampiamente supportata dai browser, tra cui Chrome, Firefox, Safari ed Edge. I report vengono inviati con il tipo di contenuto application/csp-report e hanno un formato specifico per CSP. Questi report sono chiamati "report CSP livello 2" e non si basano sull'API di reporting.
• Con l'API di reporting, ovvero tramite l'intestazione Report-To (legacy) o la più recente Reporting-Endpoints (v1). Questa direttiva è supportata solo in Chrome ed Edge. Le richieste di report hanno lo stesso formato delle altre richieste dell'API di reporting e lo stesso tipo di contenuto application/reports+json.

L'utilizzo del primo approccio (solo report-uri) non è più consigliato e l'utilizzo del secondo approccio offre alcuni vantaggi. In particolare, ti consente di utilizzare un unico modo per configurare il reporting per tutti i tipi di report, nonché di impostare un endpoint generico (perché tutte le richieste di report generate tramite l'API di reporting, CSP e altre, hanno lo stesso formato application/reports+json.

Tuttavia, solo alcuni browser supportano report-to. Pertanto, ti consigliamo di mantenere report-uri insieme all'approccio dell'API di reporting (Report-To o, meglio, Reporting-Endpoints) per ricevere report sulle violazioni CSP da più browser. In un browser che riconosce report-uri e report-to, report-uri verrà ignorato se è presente report-to. In un browser che riconosce solo report-uri, verrà considerato solo report-uri.

1. Passaggio 1 (esegui ora): se non l'hai ancora fatto, aggiungi report-to insieme a report-uri. I browser che supportano solo report-uri (Firefox) utilizzeranno report-uri, mentre i browser che supportano anche report-to(Chrome, Edge) utilizzeranno report-to. Per specificare gli endpoint denominati che utilizzerai in report-to, utilizza entrambe le intestazioni Report-To e Reporting-Endpoints. In questo modo, riceverai report sia dai client Chrome ed Edge meno recenti sia da quelli più recenti.

2. Passaggio 3 (inizia in un secondo momento): una volta che tutti o la maggior parte degli utenti hanno eseguito l'aggiornamento alle installazioni di Chrome o Edge più recenti (96 e versioni successive), rimuovi Report-To (v0) e mantieni solo Reporting-Endpoints. Mantieni report-uri per continuare a ricevere report per i browser che lo supportano.

Vedi esempi di codice per questi passaggi nella migrazione del reporting CSP.

Migrazione: esempio di codice

Panoramica

Se utilizzi l'API di reporting legacy (v0) per ricevere report sulle violazioni per un'intestazione COOP (Cross-Origin-Opener-Policy), COEP (Cross-Origin-Embedder-Policy) o di policy del documento (Document-Policy): non devi modificare queste intestazioni delle policy durante la migrazione all'API di reporting v1. Devi invece eseguire la migrazione dall'intestazione legacy Report-To alla nuova intestazione Reporting-Endpoints.

Se utilizzi l'API di reporting legacy (v0) per ricevere report sulle violazioni per un'intestazione CSP (Content-Security-Policy), potresti dover modificare Content-Security-Policy nell'ambito della migrazione alla nuova API di reporting (v1).

Migrazione di base

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"

Tieni presente che con la versione v1 puoi comunque inviare tipi di report specifici a endpoint specifici. Tuttavia, puoi avere un solo URL per endpoint.

Osservare tutte le pagine

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

Migrazione del reporting CSP

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

Per approfondire

• Monitorare l'applicazione web con l'API di reporting (post principale sull'API di reporting)
• Specifica: API di reporting legacy (v0)
• Specifica: nuova API di reporting (v1)

Un ringraziamento speciale a Ian Clelland, Eiji Kitamura e Milica Mihajlija per le loro recensioni e i loro suggerimenti su questo articolo.