Window.fence — Eigenschaft · JavaScript-Referenz

Signatur

get Window.fence

Beschreibung

Die schreibgeschützte Eigenschaft window.fence gehört zur Fenced Frame API. Diese API ist Teil der Privacy Sandbox. Ein <fencedframe> ähnelt einem <iframe>, ist aber stark von der einbettenden Seite abgeschottet. So können zum Beispiel Werbeanzeigen aus der Protected Audience API oder Inhalte, die per Shared Storage ausgewählt wurden, angezeigt werden, ohne dass eingebettete Seite und Rahmen Daten über Websites hinweg austauschen können.

Über das zurückgegebene Fence-Objekt kann das Dokument im Fenced Frame trotzdem kontrolliert mit der Außenwelt kommunizieren. Das Objekt bietet vor allem diese Methoden:

reportEvent(): meldet ein Ereignis, etwa einen Klick oder eine Sichtbarkeit, an vorher registrierte Berichtsziele (Käufer, Verkäufer usw.).
setReportEventDataForAutomaticBeacons(): legt Daten fest, die bei einer Navigation der obersten Ebene automatisch als Beacon gesendet werden.
getNestedConfigs(): liefert FencedFrameConfig-Objekte für verschachtelte Fenced Frames.

Man nutzt window.fence also nur innerhalb von Inhalten, die in einem Fenced Frame angezeigt werden, typischerweise in Werbemitteln. In normalen Dokumenten und in gewöhnlichen <iframe>s ist der Wert null. Deshalb sollte man vor jeder Nutzung prüfen, ob ein Fence-Objekt vorhanden ist.

Rückgabewert

Typ

Fence | null

Beschreibung

Ein Fence-Objekt, wenn das Dokument in einem <fencedframe> (oder einem dazugehörigen Kontext) läuft. Sonst null. In Browsern ohne Unterstützung ist die Eigenschaft undefined.

Beispiele

Prüfen, ob das Dokument in einem Fenced Frame läuft

// Vorsichtige Prüfung: undefined (keine Unterstützung) und null (kein Fenced Frame)
const inFencedFrame = () => Boolean(window.fence);

if (inFencedFrame()) {
  console.log('Läuft in einem <fencedframe>');
} else {
  console.log('Normaler Kontext – Fence-API nicht verfügbar');
}

Normaler Kontext – Fence-API nicht verfügbar

Klick auf eine Anzeige an Käufer und Verkäufer melden

// Im Werbemittel innerhalb des Fenced Frames
const ctaButton = document.querySelector('#cta');

ctaButton?.addEventListener('click', () => {
  if (!window.fence) return;

  window.fence.reportEvent({
    eventType: 'click',
    eventData: JSON.stringify({ adId: 'summer-sale-42', ts: Date.now() }),
    destination: ['buyer', 'seller']
  });
});

Automatischen Beacon für die Navigation der obersten Ebene festlegen

// Daten, die bei einer Navigation der obersten Ebene automatisch gesendet werden
const prepareNavigationBeacon = () => {
  window.fence?.setReportEventDataForAutomaticBeacons({
    eventType: 'reserved.top_navigation_start',
    eventData: JSON.stringify({ campaign: 'q3', slot: 'sidebar' }),
    destination: ['seller', 'buyer']
  });
};

document.querySelector('a.landing')?.addEventListener('pointerdown', prepareNavigationBeacon);

Verschachtelte Konfigurationen abrufen

// Zum Beispiel für Komponenten-Anzeigen (Ad Components)
const configs = window.fence?.getNestedConfigs() ?? [];

configs.forEach((config, index) => {
  const child = document.createElement('fencedframe');
  child.config = config;
  child.id = `component-${index}`;
  document.body.append(child);
});

console.log(`${configs.length} verschachtelte Konfiguration(en) gefunden`);

0 verschachtelte Konfiguration(en) gefunden

// Wichtig · Fallstricke

Experimentell und nicht standardisiert: Die Eigenschaft gibt es derzeit nur in Chromium-Browsern (Chrome, Edge) ab etwa Version 115. Firefox und Safari unterstützen sie nicht. Dort ist window.fence undefined.
Außerhalb eines Fenced Frames immer null: Das gilt auch für normale <iframe>s. Prüfen Sie deshalb immer mit window.fence?.… oder if (window.fence).
Berichte gehen nur an registrierte Ziele: reportEvent() sendet nur an Ziele, die vorher registriert wurden, bei der Protected Audience API etwa über registerAdBeacon() in reportWin() bzw. reportResult(). Fehlt diese Registrierung, wird der Bericht stillschweigend verworfen.
Größe von eventData begrenzt: Der Wert muss ein String sein, und seine Größe ist begrenzt (derzeit rund 64 KB). Serialisieren Sie Objekte mit JSON.stringify().
Datenschutz: Die API ist gezielt eingeschränkt, damit Daten nicht über Websites hinweg abfließen. Versuche, sie zu umgehen, zum Beispiel über postMessage, scheitern, weil zwischen Fenced Frame und einbettender Seite kein Kommunikationskanal besteht.
Die API entwickelt sich weiter. Methoden wie disableUntrustedNetwork() oder notifyEvent() sind zum Teil nur hinter Flags oder in neueren Versionen verfügbar.

Siehe auch

Fence Window Window.event Window.frames Window.length