Conoscere l'integrità del codice con l'API ReportingAnnotar

Trova le API deprecate nelle tue app di produzione.

Eric Bidelman
Twitter GitHub Homepage

ReportingObserver ti consente di sapere quando il tuo sito utilizza un'API deprecata o esegue un intervento nel browser. La funzionalità di base era disponibile in origine in Chrome 69. A partire da Chrome 84, può essere utilizzato nei worker.

const observer = new ReportingObserver((reports, observer) => {
  for (const report of reports) {
    console.log(report.type, report.url, report.body);
  }
}, {buffered: true});

observer.observe();

Utilizza il callback per inviare report per l'analisi a un provider di backend o di analisi.

Perché è utile? Fino a quando questa API, gli avvisi di ritiro e intervento erano disponibili solo in DevTools come messaggi della console. Gli interventi, in particolare, sono attivati solo da vari vincoli del mondo reale, come le condizioni del dispositivo e della rete. Di conseguenza, potresti non vedere mai questi messaggi durante lo sviluppo/il test di un sito a livello locale. ReportingObserver fornisce una soluzione a questo problema. Quando gli utenti riscontrano potenziali problemi in natura, gli sviluppatori web possono ricevere notifiche al riguardo.

Contesto

Qualche tempo fa ho scritto un post del blog (Observing your web app) perché ho trovato affascinante quante API ci siano per monitorare le "contenuti" che si verificano in un'app web. Ad esempio, esistono API in grado di osservare le informazioni sul DOM: ResizeObserver, IntersectionObserver, MutationObserver. PerformanceObserver acquisisce le misurazioni del rendimento. Metodi come window.onerror e window.onunhandledrejection ci fanno perfino sapere se qualcosa va storto.

Tuttavia, esistono altri tipi di avvisi che non vengono acquisiti dalle API esistenti. Quando il tuo sito utilizza un'API deprecata o viene eseguito con un intervento nel browser, DevTools è la prima cosa che te ne indica:

Avvisi della console DevTools per ritiri e interventi.
Avvisi avviati dal browser nella console DevTools.

Si potrebbe pensare che window.onerror catturi questi avvisi. Non lo fa. Questo perché window.onerror non si attiva per gli avvisi generati direttamente dallo user agent stesso. Si attiva per errori di runtime (eccezioni JavaScript ed errori di sintassi) causati dall'esecuzione del codice.

ReportingObserver si libera. Offre un modo programmatico per ricevere notifiche relative ad avvisi emessi dal browser, come ritiri e interventi. Puoi utilizzarlo come strumento di segnalazione e perdere meno sonno chiedendoti se gli utenti riscontrano problemi imprevisti sul sito pubblicato.

L'API

ReportingObserver è diverso dalle altre API Observer, come IntersectionObserver e ResizeObserver. Gli chiedi di richiamarti per ottenere informazioni. Le informazioni ricevute dal callback sono un elenco dei problemi causati dalla pagina:

const observer = new ReportingObserver((reports, observer) => {
  for (const report of reports) {
    // → report.type === 'deprecation'
    // → report.url === 'https://reporting-observer-api-demo.glitch.me'
    // → report.body.id === 'XMLHttpRequestSynchronousInNonWorkerOutsideBeforeUnload'
    // → report.body.message === 'Synchronous XMLHttpRequest is deprecated...'
    // → report.body.lineNumber === 11
    // → report.body.columnNumber === 22
    // → report.body.sourceFile === 'https://reporting-observer-api-demo.glitch.me'
    // → report.body.anticipatedRemoval === <JS_DATE_STR> or null
  }
});

observer.observe();

Report filtrati

I report possono essere prefiltrati in modo da osservare solo determinati tipi di report. Al momento, sono disponibili due tipi di report: 'deprecation' e 'intervention'.

const observer = new ReportingObserver((reports, observer) => {
  …
}, {types: ['deprecation']});

Report su cui è stato eseguito il buffering

Utilizza l'opzione buffered: true se vuoi visualizzare i report generati prima della creazione dell'istanza dell'osservatore:

const observer = new ReportingObserver((reports, observer) => {
  …
}, {types: ['intervention'], buffered: true});

Questa opzione è ottima in situazioni come il caricamento lento di una libreria che utilizza un ReportingObserver. L'osservatore viene aggiunto in ritardo, ma non perdi nulla di ciò che è successo prima del caricamento pagina.

Interrompi osservazione

Interrompi l'osservazione con il metodo disconnect():

observer.disconnect();

Esempi

Segnalare gli interventi del browser a un provider di analisi

const observer = new ReportingObserver((reports, observer) => {
  for (const report of reports) {
    sendReportToAnalytics(JSON.stringify(report.body));
  }
}, {types: ['intervention'], buffered: true});

observer.observe();

Ricevi una notifica quando le API verranno rimosse

const observer = new ReportingObserver((reports, observer) => {
  for (const report of reports) {
    if (report.type === 'deprecation') {
      sendToBackend(`Using a deprecated API in ${report.body.sourceFile} which will be
                     removed on ${report.body.anticipatedRemoval}. Info: ${report.body.message}`);
    }
  }
});

observer.observe();

Conclusione

ReportingObserver offre un ulteriore modo per scoprire e monitorare potenziali problemi nella tua app web. È anche uno strumento utile per comprendere lo stato della tua codebase (o la sua mancanza). Invia report al backend, ricevi informazioni sui problemi reali, aggiorna il codice e usa i profitti.

Lavoro futuro

In futuro, spero che ReportingObserver diventi l'API di fatto per rilevare tutti i tipi di problemi in JavaScript. Immagina un'API per individuare tutto ciò che va storto nell'app:

Risorse aggiuntive:

Immagine hero di Sieuwert Otterloo su Unsplash.