Fence — Schnittstelle · JavaScript-Referenz

Signatur

interface Fence

Beschreibung

Die Schnittstelle Fence gehört zur Fenced Frame API (Teil der Privacy Sandbox). Man erzeugt sie nicht selbst: Der Zugriff läuft ausschließlich über window.fence, und zwar in Dokumenten, die in ein <fencedframe> geladen wurden oder die über eine datenschutzfreundliche API wie Protected Audience (navigator.runAdAuction()) oder Shared Storage (sharedStorage.selectURL()) in einem <iframe> ausgewählt wurden. In allen anderen Dokumenten ist window.fence null.

Wofür braucht man das? Ein Fenced Frame ist stark von der einbettenden Seite abgeschottet: Es gibt kein postMessage, keinen Zugriff auf den DOM des Elternfensters und keinen gemeinsamen Speicher. Damit Werbetreibende trotzdem Impressionen, Klicks oder Konversionen messen können, bietet Fence kontrollierte Kanäle für das Reporting:

reportEvent(event) – sendet ein Ereignis (z. B. einen Klick) an vorab registrierte Reporting-URLs von Käufer (buyer), Verkäufer (seller) usw. oder an eine eigene Ziel-URL.
setReportEventDataForAutomaticBeacons(event) – hinterlegt Daten, die automatisch als Beacon verschickt werden, sobald der Frame eine Navigation der obersten Ebene auslöst (reserved.top_navigation_start / reserved.top_navigation_commit).
getNestedConfigs() – liefert ein Array von FencedFrameConfig-Objekten, mit denen verschachtelte Fenced Frames geladen werden können (z. B. Komponenten-Anzeigen), oder null.
disableUntrustedNetwork() (experimentell) – sperrt den Netzwerkzugriff des Frames dauerhaft und gibt ein Promise zurück; danach darf der Frame unter Umständen auf unpartitionierte Daten zugreifen.

Die Schnittstelle selbst besitzt keinen Konstruktor und keine Eigenschaften – sie ist ein reiner Methoden-Container. Prüfe vor jeder Nutzung, ob window.fence existiert, da derselbe Anzeigen-Code oft auch außerhalb eines Fenced Frames (z. B. in Tests) ausgeführt wird.

Rückgabewert

Typ

Fence | null

Beschreibung

window.fence liefert eine Fence-Instanz innerhalb eines Fenced Frames bzw. eines über Protected Audience/Shared Storage ausgewählten Frames, sonst null.

Beispiele

Verfügbarkeit von window.fence prüfen

// Läuft im Anzeigen-Dokument
const isFenced = typeof window.fence === 'object' && window.fence !== null;

if (isFenced) {
  console.log('Läuft in einem Fenced Frame:', window.fence instanceof Fence);
} else {
  console.log('Kein Fenced Frame – Reporting wird übersprungen.');
}

Läuft in einem Fenced Frame: true

Klick an Käufer und Verkäufer melden (reportEvent)

// Die Reporting-URLs wurden zuvor in reportWin()/reportResult()
// per registerAdBeacon({ click: 'https://…' }) registriert.
const adButton = document.querySelector('#ad-cta');

adButton.addEventListener('click', () => {
  window.fence?.reportEvent({
    eventType: 'click',
    eventData: JSON.stringify({ position: 'hero', ts: Date.now() }),
    destination: ['buyer', 'seller']
  });
});

Daten für automatische Beacons bei Navigation hinterlegen

// Wird beim Klick auf den Anzeigen-Link automatisch als Beacon gesendet,
// sobald die Top-Level-Navigation startet.
window.fence?.setReportEventDataForAutomaticBeacons({
  eventType: 'reserved.top_navigation_start',
  eventData: JSON.stringify({ campaign: 'sommer-2024' }),
  destination: ['buyer', 'seller'],
  once: true
});

document.querySelector('a.ad-link').addEventListener('click', (e) => {
  e.preventDefault();
  window.open('https://shop.example/angebot', '_blank');
});

Verschachtelte Anzeigen mit getNestedConfigs() laden

const configs = window.fence?.getNestedConfigs() ?? [];

configs.slice(0, 3).forEach((config) => {
  const frame = document.createElement('fencedframe');
  frame.config = config; // FencedFrameConfig
  frame.width = 300;
  frame.height = 250;
  document.body.append(frame);
});

console.log(`${configs.length} Komponenten-Konfigurationen erhalten`);

3 Komponenten-Konfigurationen erhalten

// Wichtig · Fallstricke

Experimentell & nur Chromium: Die Fenced Frame API ist derzeit nur in Chrome/Edge (ab 117, teils hinter Privacy-Sandbox-Einstellungen oder Enrollment) verfügbar. Firefox und Safari unterstützen sie nicht. Immer per window.fence-Prüfung bzw. 'HTMLFencedFrameElement' in window absichern.
Nur sicherer Kontext: Erfordert HTTPS (oder localhost).
Kein Konstruktor: new Fence() wirft einen TypeError; die Instanz kommt ausschließlich über window.fence.
reportEvent() sendet nur an Ziele, für die vorher per registerAdBeacon() (Protected Audience) bzw. in Shared Storage eine URL registriert wurde. Nicht registrierte Ereignistypen werden stillschweigend verworfen – es gibt keinen Fehler und keinen Rückgabewert zur Kontrolle.
eventData ist auf eine begrenzte Größe (ca. 64 KB) beschränkt und muss ein String sein; keine personenbezogenen Daten übertragen, da das den Datenschutzzweck der API unterläuft.
Automatische Beacons werden nur bei einer Navigation mit transienter Nutzeraktivierung (echter Klick) ausgelöst.
Nach disableUntrustedNetwork() ist der Netzwerkzugriff unwiderruflich gesperrt – vorher alle Ressourcen laden.

Siehe auch

Window.fence File Range Cache Event