DeprecationReport — Schnittstelle · JavaScript-Referenz

Signatur

interface DeprecationReport extends Report { type: "deprecation"; url: string; body: DeprecationReportBody }

Beschreibung

Ein DeprecationReport ist ein Bericht der Reporting API, den der Browser erzeugt, sobald eine Seite eine veraltete (deprecated) API verwendet, zum Beispiel synchrones XMLHttpRequest im Haupt-Thread, document.write() für Skripte aus fremden Quellen oder bestimmte veraltete Event-Eigenschaften. Die Eigenschaft type hat dabei immer den Wert "deprecation". In body steht ein DeprecationReportBody mit genaueren Angaben: welche Funktion betroffen ist, an welcher Stelle im Code sie aufgerufen wurde und ab wann sie voraussichtlich entfernt wird.

Man erzeugt solche Berichte nicht selbst. Man bekommt sie auf zwei Wegen: im Client über einen ReportingObserver mit { types: ["deprecation"] } oder auf dem Server, indem der Browser sie an einen Endpunkt schickt, der mit dem HTTP-Header Reporting-Endpoints festgelegt wurde.

Das ist nützlich für die Überwachung im Produktivbetrieb. So erfährt man früh, welche Teile einer großen Codebasis (oder welche Drittanbieter-Skripte) Funktionen nutzen, die bald wegfallen. Man kann den Code dann umstellen, bevor ein Browser-Update die Seite kaputt macht.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string	"deprecation"	Eigenschaft (nur lesbar): Art des Berichts, bei diesem Typ immer `"deprecation"`.
$url Pflicht	string		Eigenschaft (nur lesbar): URL des Dokuments, in dem die veraltete Funktion benutzt wurde.
$body Pflicht	DeprecationReportBody		Eigenschaft (nur lesbar): Details mit `id` (Kennung der Funktion), `message` (lesbarer Text), `anticipatedRemoval` (`Date` oder `null`), `sourceFile`, `lineNumber` und `columnNumber` (jeweils möglicherweise `null`).
$toJSON()	function		Methode des Basis-Interfaces `Report`: gibt eine JSON-taugliche Darstellung des Berichts zurück, praktisch zum Weiterschicken an einen eigenen Server.

Rückgabewert

Typ

DeprecationReport

Beschreibung

Wird nicht direkt erzeugt. Instanzen kommen als Array-Elemente im Callback eines ReportingObserver an oder als Rückgabewert von observer.takeRecords().

Beispiele

Veraltungsberichte mit ReportingObserver abfangen

const observer = new ReportingObserver((reports) => {
  for (const report of reports) {
    const { id, message, sourceFile, lineNumber, anticipatedRemoval } = report.body;
    console.warn(`[${report.type}] ${id}: ${message}`);
    console.warn(`  in ${sourceFile}:${lineNumber}`);
    if (anticipatedRemoval) {
      console.warn(`  Entfernung geplant ab: ${anticipatedRemoval.toLocaleDateString('de-DE')}`);
    }
  }
}, { types: ['deprecation'], buffered: true });

observer.observe();

// Löst in Chromium einen Veraltungsbericht aus (synchrones XHR im Haupt-Thread)
const xhr = new XMLHttpRequest();
xhr.open('GET', location.href, false);
xhr.send();

[deprecation] XMLHttpRequestSynchronousInNonWorkerOutsideBeforeUnload: Synchronous XMLHttpRequest on the main thread is deprecated ... in https://example.com/app.js:17

Berichte gesammelt an einen eigenen Server senden

const queue = [];

const observer = new ReportingObserver((reports) => {
  queue.push(...reports.map((r) => r.toJSON()));
}, { types: ['deprecation'], buffered: true });

observer.observe();

// Beim Verlassen der Seite noch nicht zugestellte Berichte mitnehmen und senden
document.addEventListener('visibilitychange', () => {
  if (document.visibilityState !== 'hidden') return;
  queue.push(...observer.takeRecords().map((r) => r.toJSON()));
  if (queue.length === 0) return;
  navigator.sendBeacon('/api/deprecations', JSON.stringify(queue));
  queue.length = 0;
});

Serverseitiger Empfang über Reporting-Endpoints (Node.js/Express)

import express from 'express';

const app = express();

// Browser anweisen, Berichte an /reports zu senden
app.use((req, res, next) => {
  res.set('Reporting-Endpoints', 'default="/reports"');
  next();
});

app.post('/reports', express.json({ type: 'application/reports+json' }), (req, res) => {
  for (const report of req.body) {
    if (report.type === 'deprecation') {
      console.log(`${report.url} -> ${report.body.id} (${report.body.sourceFile}:${report.body.lineNumber})`);
    }
  }
  res.sendStatus(204);
});

app.use(express.static('public'));
app.listen(3000);

https://localhost:3000/ -> XMLHttpRequestSynchronousInNonWorkerOutsideBeforeUnload (https://localhost:3000/app.js:17)

// Wichtig · Fallstricke

Browser-Kompatibilität: Veraltungsberichte gibt es zuverlässig nur in Chromium-Browsern (Chrome, Edge, Opera). In Firefox steckt ReportingObserver hinter einer Einstellung, Safari unterstützt ihn nur teilweise. Vorher prüfen, ob die API da ist: if ('ReportingObserver' in window).
Die Werte von id und message legt jeder Browser selbst fest und sie sind nicht standardisiert. Zum Gruppieren am besten id nutzen, aber nicht erwarten, dass die Kennungen in allen Browsern gleich lauten.
sourceFile, lineNumber, columnNumber und anticipatedRemoval können null sein. Bei Skripten aus fremden Quellen ohne CORS werden die Ortsangaben oft weggelassen.
Ohne buffered: true bekommt der Observer nur Berichte, die nach observe() entstehen. Den Observer deshalb möglichst früh registrieren.
Der Browser meldet jede veraltete Funktion pro Seite meist nur einmal, nicht bei jedem Aufruf.
Der ältere Header Report-To gilt als veraltet. Für neue Projekte Reporting-Endpoints verwenden. Die Zustellung an den Server erfolgt nur über HTTPS und mit Verzögerung.
Datenschutz: Berichte enthalten URLs, die Parameter wie Tokens mitführen können. Vor dem Speichern auf dem Server bereinigen.

Siehe auch

COEPViolationReport CSPViolationReport InterventionReport MutationRecord RTCStatsReport