SharedStorageWorkletGlobalScope — Schnittstelle · JavaScript-Referenz

Signatur

interface SharedStorageWorkletGlobalScope extends WorkletGlobalScope

Beschreibung

SharedStorageWorkletGlobalScope ist das globale Objekt (globalThis) in einem Modul, das über window.sharedStorage.worklet.addModule() geladen wird. Es gehört zur Shared Storage API der Privacy Sandbox. Die API bietet einen seitenübergreifenden, nach Ursprung getrennten Speicher, der ohne Drittanbieter-Cookies auskommt. Lesen kann man die gespeicherten Daten nur innerhalb dieses Worklets. Nach außen gelangen Ergebnisse ausschließlich über datenschutzfreundliche Ausgabewege, also über eine URL-Auswahl für einen Fenced Frame oder über Private-Aggregation-Berichte.

Die wichtigsten Mitglieder des Geltungsbereichs:

register(name, operationCtor): Registriert eine Klasse unter einem Namen als Operation. Die Klasse muss eine run()-Methode haben. Von der Hauptseite aus startet man die Operation mit sharedStorage.run(name, options) oder sharedStorage.selectURL(name, urls, options).
sharedStorage: Eine Instanz von WorkletSharedStorage. Neben set(), append(), delete() und clear() bietet sie hier auch Lesemethoden wie get(), length(), keys(), entries() und remainingBudget().
privateAggregation: Eine Instanz von PrivateAggregation. Mit contributeToHistogram() fließen Messwerte in verrauschte, zusammengefasste Berichte ein.

Typische Einsatzfälle sind A/B-Tests über mehrere Websites hinweg, die Begrenzung der Anzeigehäufigkeit (Frequency Capping), das Messen der Reichweite einzelner Nutzer und die Auswahl von Creatives nach bekannten Eigenschaften. Weil das Worklet streng abgeschottet läuft, stehen dort weder fetch() noch DOM-Zugriffe noch setTimeout zur Verfügung.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Parameter von `register()`: Eindeutiger Name der Operation. Unter diesem Namen ruft die Hauptseite die Operation mit `run()` oder `selectURL()` auf.
$operationCtor Pflicht	class (Konstruktor mit run()-Methode)		Parameter von `register()`: Eine Klasse mit asynchroner `run(data)`-Methode. Bei `selectURL`-Operationen hat sie die Form `run(urls, data)` und muss den Index der gewählten URL zurückgeben.

Rückgabewert

Typ

void

Beschreibung

register() gibt undefined zurück. Ist der Name schon vergeben oder fehlt der Klasse eine run()-Methode, wird ein TypeError geworfen.

Beispiele

Worklet-Modul: A/B-Test-Operation für selectURL registrieren

// ab-test-worklet.js – läuft im SharedStorageWorkletGlobalScope
class SelectExperimentGroup {
  async run(urls, data) {
    // Gruppe aus dem Shared Storage lesen (nur im Worklet möglich)
    const group = await sharedStorage.get('ab-gruppe');
    const index = Number(group ?? 0);
    // Index der anzuzeigenden URL zurückgeben
    return index < urls.length ? index : 0;
  }
}

register('ab-test', SelectExperimentGroup);

Hauptseite: Worklet laden und Ergebnis in einen Fenced Frame geben

// main.js – auf der einbettenden Seite
const startExperiment = async () => {
  if (!window.sharedStorage) {
    console.log('Shared Storage wird nicht unterstützt');
    return;
  }
  // Gruppe einmalig festlegen, falls noch nicht vorhanden
  await window.sharedStorage.set('ab-gruppe', String(Math.round(Math.random())), {
    ignoreIfPresent: true,
  });

  await window.sharedStorage.worklet.addModule('ab-test-worklet.js');

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

  document.querySelector('fencedframe').config = config;
};

startExperiment();

Reichweitenmessung mit Private Aggregation über run()

// reach-worklet.js
class ReachMeasurement {
  async run(data) {
    const key = `gesehen-${data.contentId}`;
    // Jede Person nur einmal zählen
    if (await sharedStorage.get(key)) return;

    privateAggregation.contributeToHistogram({
      bucket: BigInt(data.contentId),
      value: 1,
    });
    await sharedStorage.set(key, '1');
  }
}

register('reach', ReachMeasurement);

// Hauptseite:
// await window.sharedStorage.worklet.addModule('reach-worklet.js');
// await window.sharedStorage.run('reach', { data: { contentId: 42 } });

// Wichtig · Fallstricke

Kompatibilität: Die API ist experimentell und nur in Chromium-Browsern verfügbar. Firefox und Safari unterstützen sie nicht. Zusätzlich muss die Privacy Sandbox im Browser aktiv sein, und die aufrufende Website muss dafür registriert und bestätigt (attestiert) sein. Google hat angekündigt, mehrere Privacy-Sandbox-Techniken wieder einzustellen. Prüfen Sie deshalb vor jedem Einsatz den aktuellen Stand und fragen Sie die Unterstützung immer vorher ab, zum Beispiel mit if (window.sharedStorage).
Kein Datenabfluss: Aus run() zurückgegebene Werte kommen auf der Hauptseite nicht an. Das Promise von sharedStorage.run() erfüllt sich ohne Ergebniswert. Daten verlassen das Worklet nur über selectURL (Fenced Frame) oder über privateAggregation.
Budget: Jede Seite hat für selectURL() nur ein begrenztes Budget an Informationsbits. Bei Aufrufen mit vielen URLs ist es schnell verbraucht. Den Restbestand zeigt sharedStorage.remainingBudget().
Eingeschränkte Umgebung: Im Worklet gibt es kein fetch, kein DOM, keine Timer und keinen Netzwerkzugriff. Eine Operation mit demselben Namen zweimal zu registrieren, wirft einen TypeError.
Seit neueren Chrome-Versionen kann man ein Worklet auch mit sharedStorage.createWorklet(url) anlegen, und zwar ursprungsübergreifend. Ein Worklet, das mit addModule() geladen wird, nutzt dagegen immer den Speicher des einbettenden Ursprungs.

Siehe auch

SharedWorkerGlobalScope AudioWorkletGlobalScope PaintWorkletGlobalScope SharedStorageWorklet DedicatedWorkerGlobalScope SharedStorageRunOperation SharedStorageSelectURLOperation