FencedFrameConfig.setSharedStorageContext() — Methode · JavaScript-Referenz

Signatur

FencedFrameConfig.prototype.setSharedStorageContext(contextString)

Beschreibung

Ein <fencedframe> ist streng von der einbettenden Seite abgeschottet. Die Seite kann dem Inhalt weder direkt Daten übergeben noch mit ihm kommunizieren. Genau das soll verhindern, dass Informationen über Websites hinweg verknüpft werden. Für manche Aufgaben braucht der Frame-Inhalt aber trotzdem Daten aus dem Kontext der einbettenden Seite, etwa eine Kampagnen- oder Seiten-ID für die Auswertung. Dafür gibt es setSharedStorageContext().

Die Methode hängt einen String an ein FencedFrameConfig-Objekt. Dieses Objekt erhält man von navigator.runAdAuction() (Protected Audience) oder window.sharedStorage.selectURL(), jeweils mit der Option resolveToConfig: true. Der Inhalt im Fenced Frame kann den String nicht direkt lesen. Er steht nur in Shared-Storage-Worklets bereit, die aus dem Fenced Frame gestartet werden, und zwar über die Eigenschaft sharedStorage.context (WorkletSharedStorage.context).

Weil Worklets Daten nur über sichere Ausgabekanäle wie die Private Aggregation API oder selectURL() nach außen geben können, bleibt die Datenschutzgarantie erhalten. Die Kontextdaten können trotzdem in Messungen und Berichte einfließen. Typische Einsätze sind Reichweitenmessung, Auswertung von Kampagnen und Berichte auf Ereignisebene für Werbung.

Parameter

Name	Typ	Default	Beschreibung
$contextString Pflicht	string		Beliebiger String mit Kontextdaten, zum Beispiel ein mit `JSON.stringify()` umgewandeltes Objekt. Er steht später in den Shared-Storage-Worklets des Fenced Frames als `sharedStorage.context` bereit.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Die Methode ändert das FencedFrameConfig-Objekt direkt.

Beispiele

Kontext nach einer Protected-Audience-Auktion setzen

// Einbettende Seite (z. B. Publisher)
const auctionConfig = {
  seller: 'https://ssp.example',
  decisionLogicURL: 'https://ssp.example/decision-logic.js',
  interestGroupBuyers: ['https://dsp.example'],
  resolveToConfig: true // liefert eine FencedFrameConfig statt einer URN
};

const frameConfig = await navigator.runAdAuction(auctionConfig);

if (frameConfig) {
  // Kontextdaten für die Worklets im Fenced Frame hinterlegen
  frameConfig.setSharedStorageContext(JSON.stringify({
    pageId: 'artikel-4711',
    campaignId: 'sommer-2024'
  }));

  const frame = document.createElement('fencedframe');
  frame.config = frameConfig;
  document.querySelector('#ad-slot').append(frame);
}

Kontext im Shared-Storage-Worklet auslesen

// reporting-worklet.js – wird aus dem Fenced Frame geladen
class ReportingOperation {
  async run(data) {
    // Nur hier ist der Kontext-String der einbettenden Seite verfügbar
    const context = JSON.parse(sharedStorage.context ?? '{}');

    // Ausgabe nur über datenschutzkonforme Kanäle, z. B. Private Aggregation
    privateAggregation.contributeToHistogram({
      bucket: BigInt(context.campaignId === 'sommer-2024' ? 1 : 0),
      value: 1
    });
  }
}

register('report-view', ReportingOperation);

Worklet aus dem Fenced Frame starten

// Skript innerhalb des Fenced-Frame-Inhalts (z. B. Werbemittel)
const reportView = async () => {
  await window.sharedStorage.worklet.addModule('/reporting-worklet.js');
  await window.sharedStorage.run('report-view', {
    data: { creative: 'banner-a' }
  });
};

reportView().catch((err) => console.error('Bericht fehlgeschlagen:', err));

// Wichtig · Fallstricke

Kompatibilität: Die Methode ist experimentell und nur in Chromium-Browsern verfügbar. Sie hängt an der Privacy Sandbox, die Google teilweise zurückfährt. Firefox und Safari unterstützen Fenced Frames nicht. Prüfe deshalb vorher mit 'FencedFrameConfig' in window, ob die API da ist.
Zeitpunkt: Rufe die Methode auf, bevor du die Config der Eigenschaft config des <fencedframe> zuweist, also vor der Navigation. Spätere Änderungen wirken nicht mehr auf den geladenen Frame.
Kein direkter Zugriff: Das Dokument im Fenced Frame kann den Kontext weder über window noch über andere Wege lesen. Er ist nur über sharedStorage.context in Shared-Storage-Worklets erreichbar, die aus dem Frame gestartet wurden.
Nur Strings: Übergib Objekte als JSON und parse sie im Worklet wieder mit JSON.parse(). Chromium kann sehr lange Strings kürzen, halte die Daten also knapp.
Datenschutz: Übergib keine personenbezogenen Kennungen. Die API soll Messungen ermöglichen, ohne Nutzer über Websites hinweg zu verfolgen.

Siehe auch

FencedFrameConfig HTMLFencedFrameElement WindowSharedStorage.selectURL() WorkletSharedStorage.context WindowSharedStorage.run()