Signatur
Beschreibung
Mit observe() startest du einen zuvor mit new ReportingObserver(callback, options) erzeugten Observer. Erst nach dem Aufruf landen neu erzeugte Berichte in der Berichts-Warteschlange des Observers und werden gebündelt an den Callback übergeben. Welche Berichtstypen gesammelt werden, legst du im Konstruktor fest, nicht in observe(). Die Methode selbst nimmt keine Argumente.
Solche Berichte erzeugt der Browser zum Beispiel, wenn deine Seite veraltete APIs nutzt (deprecation), wenn er aus Sicherheits- oder Performancegründen eingreift (intervention), bei Absturzberichten (crash, nur über den Reporting-Endpunkt) oder bei Verstößen gegen die Content Security Policy (csp-violation). Damit kannst du Probleme aus echten Nutzersitzungen einsammeln und etwa per navigator.sendBeacon() an dein Monitoring schicken.
Hast du im Konstruktor buffered: true gesetzt, bekommst du nach observe() auch Berichte, die schon vor dem Erzeugen des Observers entstanden sind. Mit disconnect() beendest du die Beobachtung. takeRecords() leert die Warteschlange sofort und gibt die noch nicht zugestellten Berichte zurück.
Rückgabewert
undefined).Beispiele
Deprecation-Berichte beobachten
const observer = new ReportingObserver((reports, obs) => {
for (const report of reports) {
console.log(report.type, report.body.id, report.body.message);
}
}, { types: ['deprecation'], buffered: true });
// Ab jetzt werden Berichte gesammelt (inkl. bereits gepufferter)
observer.observe();Berichte an ein Monitoring-Backend senden
const sendReports = (reports) => {
const payload = reports.map((r) => ({
type: r.type,
url: r.url,
body: r.body?.toJSON ? r.body.toJSON() : r.body
}));
navigator.sendBeacon('/api/browser-reports', JSON.stringify(payload));
};
const observer = new ReportingObserver(sendReports, {
types: ['deprecation', 'intervention'],
buffered: true
});
observer.observe();
// Beim Verlassen der Seite noch offene Berichte mitschicken
addEventListener('pagehide', () => {
const pending = observer.takeRecords();
if (pending.length) sendReports(pending);
});Feature-Erkennung und Beenden der Beobachtung
if ('ReportingObserver' in window) {
const observer = new ReportingObserver((reports) => {
console.warn(`${reports.length} Bericht(e) erhalten`);
});
observer.observe();
// Nach 30 Sekunden nicht mehr beobachten
setTimeout(() => observer.disconnect(), 30_000);
} else {
console.info('ReportingObserver wird nicht unterstützt');
}// Wichtig · Fallstricke
- Keine Argumente: Berichtstypen (
types) undbufferedwerden im Konstruktor gesetzt. Übergibst du Optionen anobserve(), werden sie ignoriert. - Asynchrone Zustellung: Der Callback wird nicht sofort bei jedem Bericht aufgerufen, sondern gebündelt und mit Verzögerung. Brauchst du die Berichte sofort (z. B. beim Entladen der Seite), nutze
takeRecords(). - Nicht alle Typen sind beobachtbar:
crash-Berichte und bestimmte Netzwerkberichte gibt es nur über den HTTP-HeaderReporting-Endpoints, nicht über den JavaScript-Observer. - Browser-Kompatibilität: Chromium-Browser unterstützen die API seit Version 69, Firefox seit 110, Safari nur teilweise. Prüfe vorher mit
'ReportingObserver' in window, ob die API vorhanden ist. Welche Berichtstypen tatsächlich erzeugt werden, hängt vom Browser ab. - Datenschutz: Berichte können URLs und Quelltext-Positionen enthalten. Prüfe deshalb, welche Daten du an Dritte weitergibst.