Codezustand mit der ReportingObserver API ermitteln

Verworfene APIs in Ihren Produktions-Apps finden.

ReportingObserver informiert Sie, wenn auf Ihrer Website eine eingestellte API verwendet wird oder ein Browsereingriff erfolgt. Die grundlegenden Funktionen wurden ursprünglich in Chrome 69 eingeführt. Seit Chrome 84 kann sie in Workern verwendet werden.

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

observer.observe();

Verwenden Sie den Callback, um Berichte zur Analyse an ein Backend oder einen Analyseanbieter zu senden.

Warum ist das nützlich? Bis zur Einführung dieser API waren Warnungen zu Einstellungen und Interventionen nur in den Entwicklertools als Konsolennachrichten verfügbar. Insbesondere werden Eingriffe nur durch verschiedene reale Einschränkungen wie Geräte- und Netzwerkbedingungen ausgelöst. Daher werden diese Meldungen möglicherweise nie angezeigt, wenn Sie eine Website lokal entwickeln oder testen. ReportingObserver bietet eine Lösung für dieses Problem. Wenn Nutzer potenzielle Probleme feststellen, können Webentwickler darüber benachrichtigt werden.

Hintergrund

Vor einiger Zeit habe ich einen Blogpost (Observing your web app) geschrieben, weil ich es faszinierend fand, wie viele APIs es gibt, um die „Dinge“ zu beobachten, die in einer Web-App passieren. Es gibt beispielsweise APIs, die Informationen über das DOM beobachten können: ResizeObserver, IntersectionObserver, MutationObserver. PerformanceObserver erfasst Leistungsmesswerte. Und Methoden wie window.onerror und window.onunhandledrejection informieren uns sogar, wenn etwas schiefgeht.

Es gibt jedoch andere Arten von Warnungen, die von den vorhandenen APIs nicht erfasst werden. Wenn auf Ihrer Website eine veraltete API verwendet wird oder ein Browser-Eingriff erfolgt, werden Sie in den Entwicklertools als Erstes darüber informiert:

Warnungen in der Entwicklertools-Konsole zu Einstellungen und Eingriffen.
Vom Browser initiierte Warnungen in der Entwicklertools-Konsole.

Man könnte meinen, dass window.onerror diese Warnungen erfasst. Nein. Das liegt daran, dass window.onerror nicht für Warnungen ausgelöst wird, die direkt vom User-Agent selbst generiert werden. Er wird bei Laufzeitfehlern (JavaScript-Ausnahmen und Syntaxfehlern) ausgelöst, die durch die Codeausführung verursacht werden.

ReportingObserver übernimmt die Arbeit. Sie bietet eine programmatische Möglichkeit, über vom Browser ausgegebene Warnungen wie Einstellungen und Interventionen benachrichtigt zu werden. Sie können es als Berichtstool verwenden und müssen sich weniger Sorgen machen, dass Nutzer auf Ihrer Live-Website auf unerwartete Probleme stoßen.

Mit der API

ReportingObserver unterscheidet sich nicht von den anderen Observer-APIs wie IntersectionObserver und ResizeObserver. Sie geben einen Callback an und erhalten Informationen. Die Informationen, die der Callback empfängt, sind eine Liste von Problemen, die die Seite verursacht hat:

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

Gefilterte Berichte

Berichte können vorab gefiltert werden, um nur bestimmte Berichtstypen zu sehen. Derzeit gibt es zwei Berichtstypen: 'deprecation' und 'intervention'.

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

Zwischengespeicherte Berichte

Verwenden Sie die Option buffered: true, wenn Sie die Berichte sehen möchten, die vor dem Erstellen der Beobachterinstanz generiert wurden:

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

Diese Option eignet sich hervorragend für Situationen wie das Lazy Loading einer Bibliothek, die ein ReportingObserver verwendet. Der Beobachter wird zwar spät hinzugefügt, aber Sie verpassen nichts, was zuvor beim Seitenaufbau passiert ist.

Beobachtung beenden

Beenden Sie die Beobachtung mit der Methode disconnect():

observer.disconnect();

Beispiele

Browser-Interventionen an einen Analyseanbieter melden

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

observer.observe();

Benachrichtigungen erhalten, wenn APIs entfernt werden

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

Fazit

ReportingObserver bietet Ihnen eine zusätzliche Möglichkeit, potenzielle Probleme in Ihrer Webanwendung zu erkennen und zu überwachen. Es ist sogar ein nützliches Tool, um den Zustand Ihrer Codebasis (oder das Fehlen davon) zu verstehen. Berichte an ein Backend senden, über reale Probleme Bescheid wissen, Code aktualisieren, fertig!

Zukünftige Funktionen

Ich hoffe, dass ReportingObserver in Zukunft die De-facto-API zum Erfassen aller Arten von Problemen in JavaScript wird. Stellen Sie sich eine API vor, die alles erfasst, was in Ihrer App schiefgeht:

Weitere Informationen:

Hero-Image von Sieuwert Otterloo auf Unsplash.