NotRestoredReasons.url — Eigenschaft · JavaScript-Referenz

Signatur

NotRestoredReasons.url

Beschreibung

Die Eigenschaft url eines NotRestoredReasons-Objekts gibt an, zu welchem Dokument ein Eintrag im Bericht über fehlgeschlagene Back/Forward-Cache-Wiederherstellungen (bfcache) gehört. Das kann die Hauptseite sein oder ein eingebetteter <iframe>. Den Einstieg in den Bericht liefert PerformanceNavigationTiming.notRestoredReasons.

Gebraucht wird der Wert vor allem beim Performance-Monitoring: Wenn Nutzer über „Zurück“ oder „Vorwärts“ navigieren und die Seite nicht sofort aus dem bfcache kommt, lässt sich damit auswerten, welche Seite oder welcher Frame die Wiederherstellung blockiert hat. Oft kombiniert man url mit reasons, blocked, id, name und src und läuft den Baum rekursiv über children ab.

Wichtig: Bei ursprungsübergreifenden (Cross-Origin) iframes ist url aus Datenschutzgründen null. Dann hilft nur src weiter, also der Wert des src-Attributs aus Sicht des Elterndokuments. Für die Seite auf oberster Ebene ist url immer gesetzt.

Rückgabewert

Typ

string | null

Beschreibung

Die vollständige URL des Dokuments als String. Bei ursprungsübergreifenden iframes null.

Beispiele

URL der Hauptseite nach Zurück-Navigation auslesen

const [nav] = performance.getEntriesByType('navigation');
const nrr = nav?.notRestoredReasons;

if (nrr) {
  console.log('Nicht aus bfcache wiederhergestellt:', nrr.url);
  console.log('Blockiert:', nrr.blocked);
  console.log('Gründe:', nrr.reasons?.map((r) => r.reason));
} else {
  console.log('Kein Bericht (keine History-Navigation oder API nicht unterstützt)');
}

Nicht aus bfcache wiederhergestellt: https://example.com/produkte Blockiert: true Gründe: ["unload-listener"]

Frame-Baum rekursiv durchlaufen, Cross-Origin berücksichtigen

const sammleBlocker = (node, liste = []) => {
  if (node.blocked) {
    liste.push({
      // url ist bei Cross-Origin-iframes null -> auf src ausweichen
      dokument: node.url ?? `(cross-origin) ${node.src ?? 'unbekannt'}`,
      gruende: node.reasons?.map((r) => r.reason) ?? []
    });
  }
  node.children?.forEach((kind) => sammleBlocker(kind, liste));
  return liste;
};

const [nav] = performance.getEntriesByType('navigation');
if (nav?.notRestoredReasons) {
  console.table(sammleBlocker(nav.notRestoredReasons));
}

┌─────────┬──────────────────────────────────────────┬──────────────────────┐ │ (index) │ dokument │ gruende │ │ 0 │ (cross-origin) https://ads.example/frame │ [] │ └─────────┴──────────────────────────────────────────┴──────────────────────┘

Bericht per sendBeacon an ein Analyse-Backend senden

window.addEventListener('pageshow', (event) => {
  if (event.persisted) return; // aus bfcache wiederhergestellt -> alles gut

  const [nav] = performance.getEntriesByType('navigation');
  const nrr = nav?.notRestoredReasons;
  if (!nrr) return;

  const daten = {
    url: nrr.url,
    blocked: nrr.blocked,
    reasons: nrr.reasons?.map((r) => r.reason) ?? [],
    frames: nrr.children?.map((c) => c.url ?? c.src) ?? []
  };
  navigator.sendBeacon('/analytics/bfcache', JSON.stringify(daten));
});

// Wichtig · Fallstricke

Browser-Unterstützung: Die Eigenschaft ist experimentell und bisher nur in Chromium-Browsern (ab Chrome/Edge 123) verfügbar. Prüfe vorher mit 'notRestoredReasons' in PerformanceNavigationTiming.prototype, ob die API vorhanden ist.
null bei Cross-Origin: Bei ursprungsübergreifenden iframes ist url immer null. Deshalb stets mit ?? auf src oder einen Platzhalter ausweichen.
notRestoredReasons selbst ist null, wenn keine History-Navigation (Zurück/Vorwärts) stattfand. Wurde die Seite erfolgreich aus dem bfcache wiederhergestellt, entsteht kein neuer Navigationseintrag.
Datenschutz: Die URL kann Query-Parameter mit personenbezogenen Daten enthalten. Vor dem Senden an ein Analyse-System gegebenenfalls kürzen, z. B. mit new URL(nrr.url).pathname.
Die Eigenschaft ist schreibgeschützt; Zuweisungen werden stillschweigend ignoriert.

Siehe auch

NotRestoredReasons.src NotRestoredReasons.id NotRestoredReasons.name NotRestoredReasons.children NotRestoredReasons.reasons