new ReportingObserver() — Methode · JavaScript-Referenz

Signatur

new ReportingObserver(callback, options)

Beschreibung

Der Konstruktor ReportingObserver() erzeugt einen Beobachter für die Reporting API. Der Browser erstellt Berichte, wenn eine Seite z. B. veraltete APIs nutzt (deprecation), wenn er selbst eingreift, etwa weil er eine Anfrage blockiert (intervention), oder wenn eine Content Security Policy verletzt wird (csp-violation). Mit einem ReportingObserver kommt man direkt in JavaScript an diese Berichte, ohne einen Server-Endpunkt einrichten zu müssen.

Durch den Konstruktoraufruf allein wird noch nichts beobachtet. Erst observe() startet die Beobachtung. Neue Berichte werden gesammelt und asynchron in Gruppen an die Callback-Funktion übergeben. Mit takeRecords() holt man noch ausstehende Berichte sofort ab, mit disconnect() beendet man die Beobachtung.

Typische Einsatzfälle: Deprecation-Warnungen aus der Produktion an ein eigenes Monitoring melden, Browser-Eingriffe (Interventions) erkennen oder CSP-Verstöße clientseitig protokollieren. Über options.types schränkt man ein, welche Berichtstypen man erhält. Mit options.buffered bekommt man zusätzlich Berichte, die schon vor dem Erstellen des Observers entstanden sind.

Parameter

Name	Typ	Default	Beschreibung
$callback Pflicht	(reports: Report[], observer: ReportingObserver) => void		Wird aufgerufen, sobald neue Berichte vorliegen. Erhält ein Array von `Report`-Objekten (mit `type`, `url`, `body`) und den Observer selbst.
$options	object	{}	Optionales Konfigurationsobjekt.
$options.types	string[]	alle Typen	Liste der Berichtstypen, die gemeldet werden sollen, z. B. `['deprecation', 'intervention', 'csp-violation']`. Fehlt die Angabe, werden alle Typen gemeldet.
$options.buffered	boolean	false	Bei `true` werden auch Berichte übergeben, die schon vor dem Erstellen des Observers im Puffer lagen.

Rückgabewert

Typ

ReportingObserver

Beschreibung

Eine neue ReportingObserver-Instanz. Sie beobachtet erst, wenn man observe() aufruft.

Beispiele

Deprecation- und Intervention-Berichte protokollieren

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

observer.observe();

[deprecation] Synchronous XMLHttpRequest on the main thread is deprecated ...

Berichte gesammelt an einen Monitoring-Endpunkt senden

const sendReports = (reports) => {
  if (reports.length === 0) return;
  const payload = reports.map(({ type, url, body }) => ({
    type,
    url,
    body: body?.toJSON ? body.toJSON() : body
  }));
  navigator.sendBeacon('/api/browser-reports', JSON.stringify(payload));
};

const observer = new ReportingObserver(sendReports, { buffered: true });
observer.observe();

// Vor dem Verlassen der Seite noch ausstehende Berichte abholen
document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'hidden') {
    sendReports(observer.takeRecords());
  }
});

Feature-Erkennung und CSP-Verstöße beobachten

if ('ReportingObserver' in window) {
  const observer = new ReportingObserver((reports) => {
    reports.forEach(({ body }) => {
      console.warn('CSP-Verstoß:', body.effectiveDirective, body.blockedURL);
    });
  }, { types: ['csp-violation'] });

  observer.observe();

  // Beobachtung nach 60 Sekunden beenden
  setTimeout(() => observer.disconnect(), 60_000);
} else {
  console.info('ReportingObserver wird nicht unterstützt.');
}

CSP-Verstoß: script-src-elem https://evil.example/x.js

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-Browser unterstützen die API seit Version 69 vollständig. In Firefox und Safari werden nur einzelne Berichtstypen unterstützt. Deshalb immer per 'ReportingObserver' in window prüfen. Nicht unterstützte Typen in types werden einfach ignoriert.
Der Konstruktor startet keine Beobachtung. Ohne observe() wird der Callback nie aufgerufen.
Der Callback läuft asynchron und bekommt die Berichte in Gruppen, also nicht sofort beim Auslösen. Vor dem Entladen der Seite deshalb takeRecords() aufrufen, sonst gehen Berichte verloren.
Ohne buffered: true fehlen Berichte, die entstanden sind, bevor der Observer erstellt wurde, etwa beim frühen Laden der Seite.
Nicht alle Berichte erreichen JavaScript: Typen wie crash oder Netzwerkfehler gehen nur an Server-Endpunkte, die über den HTTP-Header Reporting-Endpoints konfiguriert sind.
Berichte können URLs und Teile des Quelltexts enthalten. Vor dem Senden an Dritte auf Datenschutz achten und die Daten möglichst kürzen.

Siehe auch

new DragEvent() new ResizeObserver() new MutationObserver() new PerformanceObserver() new PressureObserver()