HTMLFencedFrameElement.config — Eigenschaft · JavaScript-Referenz

Signatur

HTMLFencedFrameElement.config

Beschreibung

Die Eigenschaft config des HTMLFencedFrameElement enthält ein FencedFrameConfig-Objekt. Es beschreibt die Navigation eines <fencedframe>-Elements, also welchen Inhalt der Frame anzeigt. Weist du der Eigenschaft eine neue Konfiguration zu, navigiert der Fenced Frame sofort zum zugehörigen Inhalt. Ein Fenced Frame hat kein src-Attribut. Der Inhalt lässt sich nur über config festlegen.

Ein FencedFrameConfig kannst du nicht selbst aus einer URL bauen. Du bekommst es von einer Privacy-Sandbox-API, zum Beispiel von navigator.runAdAuction() (Protected Audience API) oder window.sharedStorage.selectURL() (Shared Storage API). Dabei musst du jeweils die Option resolveToConfig: true übergeben. Die Ziel-URL steckt „undurchsichtig“ (opak) im Objekt: Die einbettende Seite erfährt nicht, welcher Inhalt, zum Beispiel welche Werbung, ausgewählt wurde.

So kann eine Seite personalisierte Inhalte einbetten, etwa Werbung aus einer Auktion, ohne dass einbettende Seite und eingebetteter Inhalt Daten über die Nutzerin oder den Nutzer austauschen. Liest du die Eigenschaft aus, bekommst du das aktuell gesetzte Konfigurationsobjekt oder null, wenn noch keines zugewiesen wurde.

Parameter

Name	Typ	Default	Beschreibung
$value (Setter) Pflicht	FencedFrameConfig		Ein Konfigurationsobjekt, zum Beispiel aus `navigator.runAdAuction({ …, resolveToConfig: true })` oder `sharedStorage.selectURL(…, { resolveToConfig: true })`. Wenn du es zuweist, navigiert der Fenced Frame zum hinterlegten Inhalt.

Rückgabewert

Typ

FencedFrameConfig | null

Beschreibung

Das aktuell gesetzte FencedFrameConfig-Objekt oder null, wenn noch keine Konfiguration zugewiesen wurde. Die Ziel-URL im Objekt kannst du nicht auslesen.

Beispiele

Gewinner einer Protected-Audience-Auktion anzeigen

const zeigeWerbung = async () => {
  // Funktion vorhanden? Nur in Chromium-Browsern
  if (!('HTMLFencedFrameElement' in window) || !navigator.runAdAuction) {
    console.log('Fenced Frames / Protected Audience nicht verfügbar');
    return;
  }

  const auctionConfig = {
    seller: 'https://ssp.example',
    decisionLogicURL: 'https://ssp.example/auction-logic.js',
    interestGroupBuyers: ['https://dsp.example'],
    resolveToConfig: true // liefert FencedFrameConfig statt URN
  };

  const config = await navigator.runAdAuction(auctionConfig);
  if (!config) {
    console.log('Kein Gewinner in der Auktion');
    return;
  }

  const frame = document.createElement('fencedframe');
  frame.width = 300;
  frame.height = 250;
  frame.config = config; // startet die Navigation
  document.querySelector('#ad-slot').append(frame);
  console.log(frame.config instanceof FencedFrameConfig);
};

zeigeWerbung();

true

Inhalt per Shared Storage auswählen (A/B-Test)

const ladeVariante = async () => {
  await window.sharedStorage.worklet.addModule('/ab-test-worklet.js');

  const config = await window.sharedStorage.selectURL(
    'ab-test',
    [
      { url: 'https://cdn.example/banner-a.html' },
      { url: 'https://cdn.example/banner-b.html' }
    ],
    { resolveToConfig: true }
  );

  const frame = document.querySelector('fencedframe#banner');
  frame.config = config;
};

ladeVariante();

Aktuellen Zustand prüfen

const frame = document.createElement('fencedframe');
console.log(frame.config); // noch keine Konfiguration

// Konfiguration aus einem anderen Fenced Frame übernehmen
const vorhandener = document.querySelector('fencedframe#ad');
if (vorhandener?.config) {
  frame.config = vorhandener.config;
}

null

// Wichtig · Fallstricke

Experimentell und nur in Chromium verfügbar: Fenced Frames gehören zur Privacy Sandbox von Google. Firefox und Safari unterstützen sie nicht. Prüfe vor der Nutzung mit 'HTMLFencedFrameElement' in window, ob die Funktion vorhanden ist, und sieh eine Ausweichlösung vor. Die Privacy-Sandbox-APIs werden noch weiterentwickelt oder teilweise wieder eingestellt. Prüfe deshalb den aktuellen Stand, bevor du sie in Produktion einsetzt.
Kein eigenes Objekt aus einer URL: Du kannst nicht einfach eine URL-Zeichenkette zuweisen. config erwartet ein FencedFrameConfig, das eine Privacy-Sandbox-API erzeugt hat. Vergisst du dort resolveToConfig: true, bekommst du eine opake urn:uuid:-Zeichenkette zurück. Diese ist nur für ein normales <iframe> gedacht.
Response-Header nötig: Der eingebettete Inhalt muss mit dem Header Supports-Loading-Mode: fenced-frame ausgeliefert werden, sonst wird er nicht geladen. Zusätzlich müssen die Permissions Policies (run-ad-auction, shared-storage-select-url) die jeweilige API erlauben.
Abschottung: Die ausgewählte URL, Größenangaben aus der Auktion und der Inhalt des Frames bleiben der einbettenden Seite verborgen. postMessage und der Zugriff auf das DOM über Frame-Grenzen hinweg funktionieren nicht. Die im Element angegebene Größe kann durch die Konfiguration festgelegt oder überschrieben werden.

Siehe auch

Fence HTMLFencedFrameElement.height HTMLFencedFrameElement.allow HTMLFencedFrameElement.width HTMLIFrameElement.loading