Signatur
Beschreibung
Die schreibgeschützte Eigenschaft context des Interfaces WorkletSharedStorage ist nur innerhalb eines Shared-Storage-Worklets über das globale Objekt sharedStorage verfügbar. Sie enthält einen String, den die einbettende Seite vorher mit FencedFrameConfig.setSharedStorageContext() an die Konfiguration eines <fencedframe> gehängt hat.
Damit lassen sich Daten auf Ereignisebene aus der Einbettungsseite wie eine Kampagnen-ID, eine Seitenkategorie oder eine Platzierungs-ID sicher in das Worklet bringen. Direkt aus dem Fenced Frame kommt man an diese Daten nicht heran. Im Worklet kann man sie mit übergreifenden Shared-Storage-Daten kombinieren und zum Beispiel über die Private Aggregation API (privateAggregation.contributeToHistogram()) melden, ohne dass Daten zwischen den Websites durchsickern.
So läuft das typischerweise ab:
- Die einbettende Seite erhält eine
FencedFrameConfig, etwa vonnavigator.runAdAuction({ resolveToConfig: true })odersharedStorage.selectURL(..., { resolveToConfig: true }). - Sie ruft
config.setSharedStorageContext("…")auf und weist die Konfiguration danach dem<fencedframe>zu. - Der Inhalt im Fenced Frame lädt ein Worklet mit
window.sharedStorage.worklet.addModule()und startet eine Operation mitwindow.sharedStorage.run(). - In der Operation liest man den Wert mit
sharedStorage.contextaus.
Rückgabewert
setSharedStorageContext() gesetzt wurde. Ist kein Kontext gesetzt oder läuft das Worklet nicht aus einem passend konfigurierten Fenced Frame heraus, ist der Wert undefined.Beispiele
Kontext auf der einbettenden Seite setzen
// Einbettende Seite (z. B. Publisher-Seite)
const frameConfig = await navigator.runAdAuction({
seller: 'https://ssp.example',
decisionLogicURL: 'https://ssp.example/decision.js',
interestGroupBuyers: ['https://dsp.example'],
resolveToConfig: true,
});
if (frameConfig) {
// Daten auf Ereignisebene für das Worklet mitgeben
frameConfig.setSharedStorageContext(
JSON.stringify({ campaignId: 'summer-2024', slot: 'sidebar' })
);
document.querySelector('fencedframe').config = frameConfig;
}Worklet im Fenced Frame starten
// Skript innerhalb des Fenced Frames
await window.sharedStorage.worklet.addModule('/reporting-worklet.js');
await window.sharedStorage.run('send-report', {
data: { event: 'impression' },
});Kontext im Worklet auslesen und aggregiert melden
// reporting-worklet.js
class ReportingOperation {
async run(data) {
const raw = sharedStorage.context; // String oder undefined
if (raw === undefined) {
console.log('Kein Kontext übergeben');
return;
}
const { campaignId } = JSON.parse(raw);
console.log(`Kontext: ${campaignId}, Ereignis: ${data.event}`);
// Beispiel: Kampagnen-ID als Bucket für Private Aggregation
const bucket = campaignId === 'summer-2024' ? 1n : 2n;
privateAggregation.contributeToHistogram({ bucket, value: 1 });
}
}
register('send-report', ReportingOperation);// Wichtig · Fallstricke
Experimentell und nur in Chromium verfügbar: Die Eigenschaft gehört zur Privacy Sandbox (Shared Storage, Fenced Frames). Firefox und Safari unterstützen sie nicht. Google hat angekündigt, mehrere Privacy-Sandbox-APIs einzustellen. Prüfe daher vor dem Einsatz den aktuellen Stand und setze die API höchstens als fortschreitende Verbesserung (progressive enhancement) ein.
- Die Eigenschaft gibt es nur im Worklet-Kontext (
SharedStorageWorkletGlobalScope). Aufwindow.sharedStorageist sie nicht vorhanden. - Der Wert ist immer ein String. Strukturierte Daten musst du selbst serialisieren (etwa mit
JSON.stringify()) und im Worklet absichern: UmschließeJSON.parse()mittry/catch. - Ohne Aufruf von
setSharedStorageContext()oder wenn das Worklet nicht aus dem Fenced Frame gestartet wurde, ist der Wertundefined. Prüfe das immer vorher. - Rufe
setSharedStorageContext()vor der Zuweisung anfencedframe.configauf. Spätere Änderungen wirken nicht mehr. - Die Länge ist begrenzt: Chromium kürzt sehr lange Strings (derzeit auf 2048 Codeeinheiten). Übergib deshalb nur kompakte Kennungen.
- Datenschutz: Die Kontextdaten verlassen das Worklet nur über datenschutzfreundliche Ausgabewege wie Private Aggregation oder
selectURL(). Aus dem Worklet heraus kann man sie weder direkt senden noch in das DOM schreiben. - Ob du die API nutzen darfst, hängt von der Privacy-Sandbox-Registrierung (Enrollment) und den Einstellungen der Nutzer ab.