ReportingObserver

ReportingObserver est le versant intra-page de la Reporting API. Au lieu d'envoyer les reports à un serveur, il les transmet au JavaScript de la même page, ce qui vous permet de journaliser les dépréciations, les interventions et les violations de politique côté client. Il expose aussi un tampon des reports générés avant le démarrage de l'observer.

Ce qu'il observe

Un ReportingObserver voit les types de report que le navigateur expose à la page : deprecation, intervention et csp-violation, plus, là où le navigateur les prend en charge, coep, permissions-policy-violation et integrity-violation. Vous pouvez tous les observer ou filtrer sur des types précis.

Il n'expose pas tous les types de report. Les reports crash n'atteignent jamais un ReportingObserver, car la page a disparu avant qu'un callback ait pu s'exécuter, un crash n'est donc livré qu'à un endpoint serveur. Les reports csp-hash sont eux aussi réservés à un endpoint serveur. Pour le reporting de crash, et pour toute agrégation entre utilisateurs, utilisez plutôt un endpoint serveur.

Utilisation de base

Vous construisez un observer avec un callback et des options, puis vous appelez observe().

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

observer.observe();

Le constructeur prend (callback, options). Dans options, types est un tableau de types de report à surveiller (omettez-le pour observer tous les types observables), et buffered: true livre les reports générés avant l'appel à observe(), depuis le tampon de reports du navigateur, ce qui est la façon de récupérer les dépréciations déclenchées tôt pendant le chargement de la page. L'observer dispose aussi de disconnect() pour s'arrêter, et de takeRecords() pour extraire et vider de façon synchrone les reports en file. ReportingObserver est disponible dans les Web Workers comme dans les documents.

Quand l'utiliser plutôt qu'un endpoint serveur

Utilisez ReportingObserver quand vous voulez les reports dans votre propre code client : faire remonter les dépréciations aux développeurs dans un build de staging, ou alimenter en violations un pipeline d'erreurs front-end que vous exploitez déjà. Utilisez un endpoint serveur (le reste de cette référence) quand vous avez besoin des reports de crash, ou quand vous voulez agréger les reports sur l'ensemble de vos utilisateurs plutôt que par session. CentralCSP collecte le flux hors bande, côté serveur, qui est celui sur lequel vous construisez la surveillance et l'alerting.

Prise en charge par les navigateurs

ReportingObserver est disponible dans les navigateurs actuels, après avoir d'abord été diffusé dans Chromium. La prise en charge n'est pas uniforme selon le type de report : observer deprecation est la plus largement disponible, et l'API n'expose jamais qu'une partie des types de report que définit la Reporting API (deprecation, intervention et csp-violation, avec coep, permissions-policy-violation et integrity-violation là où ils sont pris en charge). Les reports de crash n'en font pas partie ; ils sont livrés à un endpoint serveur uniquement. Confirmez les types précis dont vous dépendez avant de vous reposer sur l'API en production.

Voir aussi

• Comment fonctionne la Reporting API
• Report de dépréciation
• Report d'intervention
• ReportingObserver en JavaScript, un guide pratique

Sources

• MDN, ReportingObserver
• W3C, Reporting API