Connaître l'état de votre code avec l'API ReportingObserver

Recherchez les API obsolètes dans vos applications de production.

ReportingObserver vous indique quand votre site utilise une API obsolète ou rencontre une intervention du navigateur. La fonctionnalité de base a été introduite dans Chrome 69. Depuis Chrome 84, il peut être utilisé dans les workers.

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

observer.observe();

Utilisez le rappel pour envoyer des rapports à un backend ou à un fournisseur d'analyse pour analyse.

Pourquoi est-ce utile ? Avant cette API, les avertissements d'abandon et d'intervention n'étaient disponibles que dans les outils de développement sous forme de messages de la console. Les interventions, en particulier, ne sont déclenchées que par diverses contraintes réelles, telles que les conditions de l'appareil et du réseau. Par conséquent, il est possible que vous ne voyiez jamais ces messages lorsque vous développez ou testez un site localement. ReportingObserver fournit une solution à ce problème. Lorsque les utilisateurs rencontrent des problèmes potentiels dans la nature, les développeurs Web peuvent en être informés.

Arrière-plan

Il y a quelque temps, j'ai écrit un article de blog (Observer votre application Web), car j'ai trouvé fascinant le nombre d'API permettant de surveiller les "éléments" qui se produisent dans une application Web. Par exemple, il existe des API qui peuvent observer des informations sur le DOM : ResizeObserver, IntersectionObserver, MutationObserver. PerformanceObserver enregistre les mesures de performances. Et des méthodes comme window.onerror et window.onunhandledrejection nous permettent même de savoir quand un problème survient.

Cependant, il existe d'autres types d'avertissements qui ne sont pas capturés par les API existantes. Lorsque votre site utilise une API obsolète ou se heurte à une intervention du navigateur, les outils de développement sont les premiers à vous en informer :

Avertissements de la console DevTools concernant les abandons et les interventions.
Avertissements initiés par le navigateur dans la console des outils de développement.

On pourrait naturellement penser que window.onerror capture ces avertissements. Non. En effet, window.onerror ne se déclenche pas pour les avertissements générés directement par l'user-agent lui-même. Il se déclenche pour les erreurs d'exécution (exceptions JavaScript et erreurs de syntaxe) causées par l'exécution de code.

ReportingObserver prend le relais. Il permet d'être averti de manière programmatique des avertissements émis par le navigateur, tels que les abandons et les interventions. Vous pouvez l'utiliser comme outil de reporting et vous inquiéter moins de savoir si les utilisateurs rencontrent des problèmes inattendus sur votre site en ligne.

L'API

ReportingObserver n'est pas différent des autres API Observer telles que IntersectionObserver et ResizeObserver. Vous lui fournissez un rappel, il vous fournit des informations. Les informations reçues par le rappel sont une liste de problèmes causés par la page :

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

Rapports filtrés

Les rapports peuvent être préfiltrés pour n'observer que certains types de rapports. Pour le moment, il existe deux types de rapports : 'deprecation' et 'intervention'.

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

Rapports mis en mémoire tampon

Utilisez l'option buffered: true lorsque vous souhaitez afficher les rapports générés avant la création de l'instance d'observateur :

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

Cette option est idéale pour les situations telles que le chargement différé d'une bibliothèque qui utilise un ReportingObserver. L'observateur est ajouté tardivement, mais vous ne manquez rien de ce qui s'est passé plus tôt lors du chargement de la page.

Arrêter l'observation

Arrêtez l'observation à l'aide de la méthode disconnect() :

observer.disconnect();

Exemples

Signaler les interventions du navigateur à un fournisseur d'analyse

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

observer.observe();

Recevoir une notification lorsque des API vont être supprimées

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

Conclusion

ReportingObserver vous offre un moyen supplémentaire de découvrir et de surveiller les problèmes potentiels dans votre application Web. C'est même un outil utile pour comprendre l'état de votre code base (ou son absence). Envoyez des rapports à un backend, découvrez les problèmes réels, mettez à jour le code et profitez-en !

Prochains ajouts

À l'avenir, j'espère que ReportingObserver deviendra l'API de facto pour détecter tous les types de problèmes en JavaScript. Imaginez une API capable de détecter tout ce qui ne va pas dans votre application :

Ressources supplémentaires :

Image héros par Sieuwert Otterloo sur Unsplash.