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

Trova le API deprecate nelle tue app di produzione.

ReportingObserver ti consente di sapere quando il tuo sito utilizza un'API deprecata o si verifica un intervento del browser. La funzionalità di base è stata introdotta originariamente 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 i report a un backend o a un provider di analisi per l'analisi.

Perché è utile? Prima di questa API, gli avvisi di ritiro e intervento erano disponibili solo in DevTools come messaggi della console. In particolare, gli interventi vengono attivati solo da vari vincoli reali, come le condizioni del dispositivo e della rete. Pertanto, potresti non visualizzare mai questi messaggi durante lo sviluppo o il test di un sito in locale. ReportingObserver fornisce una soluzione a questo problema. Quando gli utenti riscontrano potenziali problemi sul campo, gli sviluppatori web possono ricevere una notifica.

Sfondo

Qualche tempo fa, ho scritto un blog post (Osservazione della tua app web) perché ho trovato affascinante il numero di API disponibili per monitorare le "cose" che accadono in un'app web. Ad esempio, esistono API che possono osservare informazioni sul DOM: ResizeObserver, IntersectionObserver, MutationObserver. PerformanceObserver acquisisce le misurazioni del rendimento. Inoltre, metodi come window.onerror e window.onunhandledrejection ci informano anche quando 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 si scontra con un intervento del browser, DevTools è il primo a informarti:

Avvisi della console DevTools relativi a ritiro e interventi.
Avvisi avviati dal browser nella console DevTools.

Si potrebbe pensare che window.onerror acquisisca questi avvisi. No. Questo perché window.onerror non viene attivato per gli avvisi generati direttamente dallo user agent stesso. Viene attivato per gli errori di runtime (eccezioni JavaScript ed errori di sintassi) causati dall'esecuzione di codice.

ReportingObserver compensa la differenza. Fornisce un modo programmatico per ricevere notifiche sugli avvisi emessi dal browser, come ritiri e interventi. Puoi utilizzarlo come strumento di generazione dei report e dormire sonni più tranquilli senza chiederti se gli utenti riscontrano problemi imprevisti sul tuo sito pubblicato.

L'API

ReportingObserver non è diversa dalle altre API Observer, come IntersectionObserver e ResizeObserver. Tu fornisci un callback e l'API ti fornisce informazioni. Le informazioni ricevute dal callback sono un elenco di 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 pre-filtrati per 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 di cui è stato eseguito il buffering

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

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

Questa opzione è ideale per situazioni come il caricamento lento di una libreria che utilizza un ReportingObserver. L'observer viene aggiunto in ritardo, ma non ti perdi nulla di ciò che è accaduto in precedenza durante il caricamento della pagina.

Interrompi l'osservazione

Interrompi l'osservazione utilizzando il metodo disconnect():

observer.disconnect();

Esempi

Segnala gli interventi del browser a un fornitore 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 stanno per essere 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 ti offre un modo aggiuntivo per scoprire e monitorare potenziali problemi nella tua app web. È anche uno strumento utile per comprendere lo stato di integrità del tuo codebase (o la sua mancanza). Invia i report a un backend, scopri i problemi reali, aggiorna il codice e guadagna.

Lavoro futuro

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

Risorse aggiuntive:

Immagine hero di Sieuwert Otterloo su Unsplash.