CrashReportContext.initialize() — Methode · JavaScript-Referenz

Signatur

CrashReportContext.prototype.initialize(length)

Beschreibung

Die Methode initialize() der Schnittstelle CrashReportContext (erreichbar über window.crashReport) legt einen Speicherbereich mit der angegebenen Größe in Bytes an. In diesem Bereich speichert der Browser später die Schlüssel-Wert-Paare, die du mit set() festlegst. Stürzt der Renderer-Prozess der Seite ab (z. B. wegen Speichermangel oder eines internen Fehlers), werden diese Daten dem Crash-Bericht beigefügt, den die Reporting API an deinen konfigurierten Endpunkt sendet.

Warum ist das nötig? Bei einem Absturz kann kein JavaScript mehr laufen. Deshalb reserviert der Browser den Speicher im Voraus außerhalb des abstürzenden Prozesses. So bleiben die Daten auch dann lesbar, wenn die Seite selbst nicht mehr reagiert. Die feste Größe verhindert, dass eine Seite unbegrenzt Speicher im Browserprozess belegt.

Rufe initialize() möglichst früh beim Laden der Seite genau einmal auf und warte das zurückgegebene Promise ab, bevor du set() verwendest. Typische Inhalte sind kurze Diagnosedaten wie App-Version, aktuelle Route, Feature-Flags oder der letzte Nutzerschritt. Personenbezogene Daten gehören nicht hinein.

Parameter

Name	Typ	Default	Beschreibung
$length Pflicht	number		Größe des zu reservierenden Speicherbereichs in Bytes. Alle Schlüssel und Werte, die später mit `set()` abgelegt werden, müssen zusammen in diesen Bereich passen. Der Browser legt eine Obergrenze fest (wenige Kilobyte). Ist der Wert zu groß, wird das Promise abgelehnt.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald der Speicherbereich bereitsteht. Es wird abgelehnt (z. B. mit einer DOMException), wenn der Bereich schon initialisiert wurde, die Größe unzulässig ist oder die Funktion im aktuellen Kontext nicht verfügbar ist.

Beispiele

Grundlegende Initialisierung und erste Einträge

// Früh beim Laden der Seite ausführen
const setupCrashContext = async () => {
  if (!('crashReport' in window)) {
    console.log('CrashReportContext wird nicht unterstützt');
    return false;
  }

  await window.crashReport.initialize(1024); // 1 KiB reservieren
  window.crashReport.set('app_version', '4.2.1');
  window.crashReport.set('build', 'prod');
  console.log('Crash-Kontext bereit');
  return true;
};

setupCrashContext();

Crash-Kontext bereit

Fehlerbehandlung bei unzulässiger Größe oder doppeltem Aufruf

const initCrashContext = async (bytes) => {
  try {
    await window.crashReport.initialize(bytes);
    return true;
  } catch (err) {
    // z. B. Größe über dem Browser-Limit oder bereits initialisiert
    console.warn(`initialize(${bytes}) fehlgeschlagen:`, err.name);
    return false;
  }
};

const ok = await initCrashContext(2048);
console.log('Initialisiert:', ok);

// Ein zweiter Aufruf wird abgelehnt
await initCrashContext(2048);

Initialisiert: true initialize(2048) fehlgeschlagen: (Name der DOMException, z. B. InvalidStateError)

Aktuelle Route in einer Single-Page-App mitschreiben

// Wartet, bis der Speicher bereitsteht, bevor set() aufgerufen wird
const crashContextReady = 'crashReport' in window
  ? window.crashReport.initialize(512).then(() => true, () => false)
  : Promise.resolve(false);

const trackRoute = async (path) => {
  if (!(await crashContextReady)) return;
  // Kurz halten: Der Speicher ist fest begrenzt
  window.crashReport.set('route', path.slice(0, 100));
};

window.addEventListener('popstate', () => trackRoute(location.pathname));
trackRoute(location.pathname);

// Wichtig · Fallstricke

Experimentell: Die API ist derzeit nur in Chromium-basierten Browsern verfügbar (Origin Trial bzw. hinter einem Flag). Prüfe sie immer mit 'crashReport' in window. Signatur und Grenzwerte können sich noch ändern.
Reihenfolge: Rufe set() erst auf, wenn das Promise von initialize() erfüllt ist. Vorher oder ganz ohne Initialisierung löst set() eine Ausnahme aus.
Nur einmal pro Dokument: Ein erneuter Aufruf wird abgelehnt. Die Größe lässt sich danach nicht mehr ändern, plane also genug Platz für alle Schlüssel und Werte ein.
Feste Obergrenze: Der Browser begrenzt die Größe auf wenige Kilobyte. Lege nur kurze Diagnosewerte ab, keine Logs und keine serialisierten Zustandsobjekte.
Zustellung: Die Daten kommen nur an, wenn ein Reporting-Endpunkt eingerichtet ist (HTTP-Header Reporting-Endpoints) und der Browser einen Crash-Bericht erzeugt.
Datenschutz: Die Werte werden an einen Server übertragen. Speichere keine personenbezogenen Daten, Tokens oder Passwörter darin.

Siehe auch

CrashReportContext.delete() CrashReportContext.set() SVGPointList.initialize() SVGLengthList.initialize() SVGStringList.initialize()