Location.ancestorOrigins — Eigenschaft · JavaScript-Referenz

Signatur

get Location.prototype.ancestorOrigins

Beschreibung

Die schreibgeschützte Eigenschaft location.ancestorOrigins gibt eine statische DOMStringList zurück. Sie enthält die Ursprünge (Origins, also Schema, Host und Port wie https://example.com) aller Browsing-Kontexte, in die das aktuelle Dokument eingebettet ist. Der erste Eintrag (Index 0) ist der Ursprung des direkten Elternfensters. Der letzte Eintrag gehört zum obersten Fenster (window.top).

Wichtig ist sie vor allem für Inhalte, die in <iframe>-Elementen fremder Seiten laufen, zum Beispiel Widgets, Zahlungsformulare, Werbung oder Einbettungs-Player. Normalerweise kann ein Dokument aus einem anderen Ursprung weder parent.location noch top.location lesen. Über ancestorOrigins erfährt es trotzdem, wer es einbettet, ohne auf document.referrer angewiesen zu sein. Die Angabe kann nur der Browser setzen und ist damit verlässlicher als ein Referrer.

In einem Dokument der obersten Ebene, das also nicht eingebettet ist, ist die Liste leer (length === 0). Die Liste ist eine Momentaufnahme. Wird das Dokument später in einen anderen Rahmen verschoben, passt sie sich nicht an. Einzelne Einträge liest man mit item(index) oder über die Indexschreibweise. Mit contains(string) prüft man, ob ein Ursprung vorkommt.

Rückgabewert

Typ

DOMStringList

Beschreibung

Statische, schreibgeschützte Liste von Ursprungs-Strings (z. B. "https://example.com"). Sie ist vom direkten Elternfenster bis zum obersten Fenster geordnet und leer, wenn das Dokument nicht eingebettet ist. Verborgene oder undurchsichtige Ursprünge (opaque origins) erscheinen als "null".

Beispiele

Alle Ursprünge der Einbettungskette ausgeben

// Läuft innerhalb eines iframes
const origins = location.ancestorOrigins;

if (!origins || origins.length === 0) {
  console.log('Nicht eingebettet (oder API nicht unterstützt).');
} else {
  // DOMStringList ist kein Array, deshalb Array.from verwenden
  Array.from(origins).forEach((origin, i) => {
    console.log(`Ebene ${i + 1}: ${origin}`);
  });
  console.log('Oberstes Fenster:', origins[origins.length - 1]);
}

Ebene 1: https://partner.example Ebene 2: https://shop.example Oberstes Fenster: https://shop.example

Widget nur auf erlaubten Seiten anzeigen

const ALLOWED = new Set(['https://kunde-a.example', 'https://kunde-b.example']);

const isEmbeddedByAllowedParent = () => {
  const list = location.ancestorOrigins;
  if (!list) return null;           // Unterstützung fehlt → unbekannt
  if (list.length === 0) return true; // direkt aufgerufen
  // Jede Ebene der Kette muss erlaubt sein
  return Array.from(list).every((origin) => ALLOWED.has(origin));
};

const result = isEmbeddedByAllowedParent();
if (result === false) {
  document.body.textContent = 'Dieses Widget darf hier nicht eingebettet werden.';
} else {
  console.log('Widget wird geladen …');
}

Widget wird geladen …

Feature-Detection mit Fallback auf document.referrer

const getParentOrigin = () => {
  if (window.top === window) return null; // kein iframe

  if ('ancestorOrigins' in location) {
    return location.ancestorOrigins.item(0); // direktes Elternfenster
  }
  // Fallback: ungenauer, kann durch die Referrer-Policy fehlen
  try {
    return document.referrer ? new URL(document.referrer).origin : null;
  } catch {
    return null;
  }
};

console.log('Eltern-Ursprung:', getParentOrigin());
console.log(location.ancestorOrigins?.contains('https://shop.example'));

Eltern-Ursprung: https://partner.example true

// Wichtig · Fallstricke

Browser-Kompatibilität: Chrome, Edge, Opera und Safari (auch mobil) unterstützen die Eigenschaft seit vielen Jahren. Firefox hat sie lange nicht unterstützt und erst in neueren Versionen eingeführt. Deshalb immer mit 'ancestorOrigins' in location oder optionaler Verkettung (?.) prüfen.
Rückgabewert ist kein Array: DOMStringList hat weder map noch includes oder forEach. Stattdessen Array.from(), item() oder contains() verwenden.
Einträge mit "null": Ursprünge aus Sandbox-iframes ohne allow-same-origin, data:-URLs und ähnliche undurchsichtige Ursprünge erscheinen als String "null". Einige Browser verbergen den Ursprung außerdem, wenn das einbettende <iframe> referrerpolicy=\"no-referrer\" setzt.
Sicherheit: Der Wert kommt zwar vom Browser, eine Prüfung im Client lässt sich aber umgehen, etwa durch direktes Aufrufen oder manipulierte Skripte. Echten Schutz vor unerwünschtem Einbetten (Clickjacking) bieten nur die HTTP-Header Content-Security-Policy: frame-ancestors bzw. X-Frame-Options.
Die Liste ist statisch. Sie wird beim Erzeugen des Dokuments festgelegt und bei späteren Änderungen der Einbettung nicht aktualisiert.

Siehe auch

Location Location.origin DOMStringList Document.referrer Window.top Window.parent VideoTrackGenerator.writable