HTMLFencedFrameElement — Schnittstelle · JavaScript-Referenz

Signatur

interface HTMLFencedFrameElement extends HTMLElement

Beschreibung

HTMLFencedFrameElement ist die DOM-Schnittstelle zum Element <fencedframe>. Ein Fenced Frame bettet Inhalte ähnlich wie ein <iframe> ein. Er ist aber streng von der einbettenden Seite abgeschottet: Einbettende Seite und eingebetteter Inhalt können weder auf das DOM des anderen zugreifen noch direkt über postMessage() kommunizieren. Beide Seiten teilen auch keinen Speicher und keine Cookies (Partitionierung). So lassen sich Daten mehrerer Websites anzeigen, ohne dass Tracking über Websites hinweg möglich wird. Das ist die Grundlage der Privacy Sandbox, etwa für die Protected Audience API (früher FLEDGE) und Shared Storage.

Anders als bei einem <iframe> gibt es kein src-Attribut. Den Inhalt legt man ausschließlich über die Eigenschaft config fest, die ein FencedFrameConfig-Objekt erwartet. Solche Objekte erzeugt man normalerweise nicht selbst. Man erhält sie von APIs wie navigator.runAdAuction() oder window.sharedStorage.selectURL(), wenn dort die Option resolveToConfig: true gesetzt ist. Die eigentliche URL bleibt dabei für die einbettende Seite unsichtbar (opak).

Die Schnittstelle erbt alle Eigenschaften und Methoden von HTMLElement und ergänzt diese Eigenschaften:

config: Das FencedFrameConfig-Objekt, das bestimmt, welcher Inhalt geladen wird. Eine neue Zuweisung löst eine neue Navigation aus.
width / height: Spiegeln die gleichnamigen HTML-Attribute wider (als Zeichenkette).
allow: Spiegelt das Attribut allow wider, also die Permissions Policy für den eingebetteten Inhalt.

Nutzen Sie diese Schnittstelle, wenn Sie als Werbe- oder Plattform-Anbieter Anzeigen aus Protected-Audience-Auktionen oder per Shared Storage ausgewählte Inhalte datenschutzkonform ausliefern wollen. Für normale Einbettungen bleibt HTMLIFrameElement die richtige Wahl.

Parameter

Name	Typ	Default	Beschreibung
$config	FencedFrameConfig \| null	null	Eigenschaft: legt fest, welcher Inhalt im Fenced Frame angezeigt wird. Den Wert liefern z. B. `navigator.runAdAuction()` oder `sharedStorage.selectURL()` mit `resolveToConfig: true`.
$width	string	""	Eigenschaft: spiegelt das HTML-Attribut `width` wider (Breite in CSS-Pixeln, als Zeichenkette).
$height	string	""	Eigenschaft: spiegelt das HTML-Attribut `height` wider (Höhe in CSS-Pixeln, als Zeichenkette).
$allow	string	""	Eigenschaft: spiegelt das Attribut `allow` wider, also die Permissions Policy, z. B. `"attribution-reporting; run-ad-auction"`.

Rückgabewert

Typ

HTMLFencedFrameElement

Beschreibung

Eine Instanz entsteht über document.createElement("fencedframe") oder durch das Parsen eines <fencedframe>-Tags. Einen öffentlichen Konstruktor gibt es nicht.

Beispiele

Unterstützung prüfen und Element erzeugen

// Gibt es Fenced Frames in diesem Browser?
const supportsFencedFrames = 'HTMLFencedFrameElement' in window;

if (supportsFencedFrames) {
  const frame = document.createElement('fencedframe');
  frame.width = '300';
  frame.height = '250';
  frame.allow = 'attribution-reporting';
  document.querySelector('#ad-slot').append(frame);
  console.log(frame instanceof HTMLFencedFrameElement, frame.config);
} else {
  console.log('Fenced Frames nicht verfügbar – Fallback nutzen');
}

true null // oder: Fenced Frames nicht verfügbar – Fallback nutzen

Gewinner-Anzeige einer Protected-Audience-Auktion anzeigen

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

  const config = await navigator.runAdAuction(auctionConfig);
  if (!config) {
    console.log('Keine Anzeige hat die Auktion gewonnen');
    return;
  }

  const frame = document.createElement('fencedframe');
  frame.width = '728';
  frame.height = '90';
  frame.config = config; // startet die Navigation, die URL bleibt verborgen
  document.getElementById('banner').append(frame);
};

showAd().catch(console.error);

Inhalt per Shared Storage auswählen

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

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

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

loadVariant();

Attribute widerspiegeln und auslesen

// HTML: <fencedframe id="ad" width="320" height="50" allow="attribution-reporting"></fencedframe>
const frame = document.getElementById('ad');

console.log(frame.width, frame.height, frame.allow);
frame.height = '100';
console.log(frame.getAttribute('height'));

320 50 attribution-reporting 100

// Wichtig · Fallstricke

Experimentell: Nur Chromium-basierte Browser (Chrome, Edge ab 115) unterstützen die Schnittstelle, und auch dort teils nur mit aktivierten Privacy-Sandbox-APIs. Firefox und Safari unterstützen sie nicht. Prüfen Sie daher immer mit 'HTMLFencedFrameElement' in window und sehen Sie einen Fallback vor, etwa ein <iframe> mit kontextueller Werbung.

Es gibt kein src. Ein Fenced Frame lässt sich nicht mit einer beliebigen URL befüllen, sondern nur über ein FencedFrameConfig.
Die einbettende Seite erfährt die tatsächliche URL nicht. config ist opak, und Größenänderungen nach der Navigation werden dem Inhalt nicht mitgeteilt, damit kein Informationskanal entsteht.
Die Kommunikation ist absichtlich eingeschränkt: kein postMessage(), kein contentWindow, kein Zugriff auf window.parent oder window.top. Berichte laufen im Frame über window.fence.reportEvent().
Der eingebettete Inhalt muss mit dem Antwort-Header Supports-Loading-Mode: fenced-frame ausgeliefert werden, sonst lädt er nicht.
Die Permissions Policy (allow) ist stark begrenzt. Nur datenschutzverträgliche Features lassen sich delegieren, und eine Einbettung schlägt fehl, wenn ein benötigtes Feature in der einbettenden Seite gesperrt ist.
width und height sind Zeichenketten und keine Zahlen.

Siehe auch

HTMLIFrameElement HTMLAnchorElement HTMLEmbedElement HTMLFormElement HTMLMediaElement HTMLSelectedContentElement