SharedStorageWorklet — Schnittstelle · JavaScript-Referenz

Signatur

interface SharedStorageWorklet extends Worklet

Beschreibung

Das Interface SharedStorageWorklet gehört zur Shared Storage API der Privacy Sandbox. Es erbt von Worklet und stellt eine abgeschottete Ausführungsumgebung bereit, in der Code die Daten aus dem Shared Storage lesen darf. Auf der Seite selbst kann man in den Shared Storage nur schreiben (set(), append(), delete(), clear()). Gelesen wird ausschließlich im Worklet, und die Ergebnisse gelangen nur über datenschutzfreundliche Ausgabekanäle nach außen.

Das Standard-Worklet der aktuellen Herkunft erreicht man über window.sharedStorage.worklet. Ein Worklet für eine andere Herkunft erzeugt man mit window.sharedStorage.createWorklet(url, options). Mit der geerbten Methode addModule() lädt man ein Modul, das per register(name, OperationClass) benannte Operationen anmeldet. Diese startet man dann über:

run(name, options): führt eine Operation ohne Rückgabe an die Seite aus, typischerweise zusammen mit der Private Aggregation API für Reichweitenmessung oder Berichte.
selectURL(name, urls, options): wählt anhand der gespeicherten Daten eine von bis zu 8 URLs aus. Zurück kommt eine opake FencedFrameConfig bzw. eine URN, die man nur in einem <fencedframe> oder <iframe> darstellen kann, etwa für A/B-Tests oder Creative-Rotation.

Typische Einsatzfälle: ursprungsübergreifende A/B-Tests, Frequency Capping, Messung der eindeutigen Reichweite und die Auswahl von Werbemitteln, alles ohne Third-Party-Cookies.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Bei `run()`/`selectURL()`: Name der Operation, die im Worklet-Modul mit `register()` angemeldet wurde.
$urls	Array<{url: string, reportingMetadata?: Object}>		Nur bei `selectURL()`: 1 bis 8 Kandidaten-URLs. Die Operation gibt den Index der gewählten URL zurück.
$options	Object	{}	Optionen wie `data` (wird an `run(data)` im Worklet übergeben), `keepAlive` (Worklet nach dem Aufruf weiter nutzbar halten), `resolveToConfig` (nur `selectURL()`: `FencedFrameConfig` statt URN zurückgeben) und `privateAggregationConfig`.

Rückgabewert

Typ

Promise<void> | Promise<string | FencedFrameConfig>

Beschreibung

addModule() und run() liefern Promise<void>. selectURL() liefert eine opake URN (string) oder eine FencedFrameConfig.

Beispiele

Worklet-Modul: Operationen registrieren (shared-storage-worklet.js)

// Läuft im SharedStorageWorkletGlobalScope
class ExperimentGroup {
  async run(urls, data) {
    // Lesen geht nur hier im Worklet
    const group = await sharedStorage.get('ab-group');
    return group === 'B' ? 1 : 0; // Index in urls
  }
}

class CountVisit {
  async run(data) {
    const count = Number(await sharedStorage.get('visits') ?? 0);
    await sharedStorage.set('visits', String(count + 1));
  }
}

register('experiment-group', ExperimentGroup);
register('count-visit', CountVisit);

Modul laden und Operation mit run() ausführen

const main = async () => {
  if (!('sharedStorage' in window)) {
    console.log('Shared Storage wird nicht unterstützt');
    return;
  }
  // Schreiben geht direkt auf der Seite
  await window.sharedStorage.set('ab-group', Math.random() < 0.5 ? 'A' : 'B', {
    ignoreIfPresent: true
  });

  const worklet = window.sharedStorage.worklet; // SharedStorageWorklet
  await worklet.addModule('/shared-storage-worklet.js');
  await worklet.run('count-visit', { data: { page: location.pathname } });
  console.log(worklet instanceof SharedStorageWorklet);
};

main();

true

A/B-Test mit selectURL() und Fenced Frame

const showCreative = async () => {
  const worklet = await window.sharedStorage.createWorklet(
    'https://ads.example/shared-storage-worklet.js'
  );

  const config = await worklet.selectURL(
    'experiment-group',
    [
      { url: 'https://ads.example/creative-a.html' },
      { url: 'https://ads.example/creative-b.html' }
    ],
    { resolveToConfig: true }
  );

  // Die gewählte URL bleibt für die Seite verborgen
  const frame = document.createElement('fencedframe');
  frame.config = config;
  document.body.append(frame);
};

showCreative().catch(console.error);

// Wichtig · Fallstricke

Experimentell und nur in Chromium: Die API wird nur von Chrome/Edge im Rahmen der Privacy Sandbox unterstützt. Firefox und Safari lehnen sie ab. Google hat inzwischen angekündigt, mehrere Privacy-Sandbox-Technologien einzustellen. Prüfe den aktuellen Stand, bevor du die API produktiv einsetzt, und frage die Unterstützung immer vorher mit 'sharedStorage' in window ab.
Registrierung erforderlich: Die aufrufende Herkunft muss für die Privacy Sandbox registriert und attestiert sein. Sonst schlagen run() und selectURL() fehl. Außerdem darf Permissions-Policy: shared-storage die API nicht blockieren, und der Nutzer darf sie nicht in den Browsereinstellungen deaktiviert haben.
Nur ein Modul pro Worklet: addModule() kann pro Worklet nur einmal aufgerufen werden. Ohne keepAlive: true ist das Worklet nach dem ersten run()/selectURL() nicht mehr nutzbar.
Begrenzte Ausgabe: selectURL() gibt pro Seitenaufruf nur begrenzt viele Bits preis (Budget, höchstens 8 URLs). Das Ergebnis ist absichtlich opak und nur in Fenced Frames verwendbar. Im Worklet gibt es weder Netzwerkzugriff noch DOM.
Bei Worklets, die mit createWorklet() für eine andere Herkunft erzeugt werden, gehört der Speicher standardmäßig der Herkunft des Skripts. Das Laden unterliegt CORS.

Siehe auch

Worklet SharedStorageOperation SharedStorage SharedWorker AudioWorklet