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

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

Eric Bidelman
Twitter GitHub Page d'accueil

ReportingObserver vous indique quand votre site utilise une API obsolète ou s'exécute dans une intervention du navigateur. La fonctionnalité de base est arrivée dans Chrome 69. Depuis Chrome 84, elle peut être utilisée par 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 de solutions d'analyse à des fins d'analyse.

En quoi est-ce utile ? Jusqu'à cette API, les avertissements d'abandon et d'intervention n'étaient disponibles dans les outils de développement que sous forme de messages de la console. Les interventions, en particulier, ne sont déclenchées que par différentes contraintes du monde réel, telles que les conditions de l'appareil et du réseau. Ainsi, il se peut que vous ne voyiez jamais ces messages lorsque vous développez/testez un site en local. 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.

Contexte

Il y a quelque temps, j'ai rédigé un article de blog (Observer votre application Web), car j'ai trouvé fascinant le nombre d'API permettant de surveiller le "contenu" d'une application Web. Par exemple, certaines API peuvent observer des informations sur le DOM : ResizeObserver, IntersectionObserver et MutationObserver. PerformanceObserver capture les mesures des performances. Des méthodes telles que window.onerror et window.onunhandledrejection nous signalent même en cas de problème.

Toutefois, 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 concernant les abandons et les interventions dans la console DevTools.
Avertissements déclenchés par le navigateur dans la console DevTools

On pense naturellement que window.onerror capture ces avertissements. Ce n'est pas le cas. En effet, window.onerror ne se déclenche pas pour les avertissements générés directement par le 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 du code.

ReportingObserver place le jeu. Elle offre un moyen programmatique d'être averti des avertissements émis par les navigateurs, tels que des abandons et des interventions. Vous pouvez l'utiliser comme un outil de création de rapports et perdre moins de temps à vous demander si les utilisateurs rencontrent des problèmes inattendus sur votre site en ligne.

L'API

ReportingObserver est semblable aux autres API Observer, telles que IntersectionObserver et ResizeObserver. Vous lui rappelez et vous obtenez des informations. Les informations reçues par le rappel sont une liste des 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. Il existe actuellement 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 des situations telles que le chargement différé d'une bibliothèque qui utilise un ReportingObserver. L'observateur est ajouté tardivement, mais vous ne ratez rien de ce qui s'est passé avant le 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 de solutions d'analyse

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

observer.observe();

Soyez informé lorsque des API seront 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. Il s'agit même d'un outil utile pour comprendre l'état de votre code base (ou son absence). Envoyez des rapports à un backend, informez-vous des problèmes du monde réel, mettez à jour le code, et c'est parti !

Travaux futurs

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

Autres ressources

Image héros de Sieuwert Otterloo sur Unsplash.