WorkletSharedStorage — Schnittstelle · JavaScript-Referenz

Signatur

interface WorkletSharedStorage extends SharedStorage

Beschreibung

Die Schnittstelle WorkletSharedStorage gehört zur Shared Storage API der Privacy Sandbox. Sie steht für den gemeinsamen Speicher eines Ursprungs innerhalb eines Shared-Storage-Worklets. Im Worklet erreichst du die Instanz über die globale Eigenschaft sharedStorage des SharedStorageWorkletGlobalScope.

Der Speicher ist nicht nach Top-Level-Site partitioniert. Ein Drittanbieter-Ursprung kann darin also Daten über mehrere Websites hinweg ablegen. Damit so kein Tracking möglich ist, gilt: Schreiben (set(), append(), delete(), clear()) geht überall, auch über window.sharedStorage. Lesen geht dagegen nur hier im Worklet, mit get(), length(), keys(), values(), entries() und asynchroner Iteration. Die gelesenen Daten verlassen das Worklet nur über Ausgabe-Gates mit begrenztem Informationsfluss. Das sind selectURL(), das eine von bis zu 8 URLs für einen Fenced Frame auswählt, und die Private Aggregation API mit verrauschten, aggregierten Berichten.

Zusätzlich zu den geerbten Methoden von SharedStorage bietet die Schnittstelle:

get(key): liefert ein Promise<string | undefined> mit dem Wert zum Schlüssel.
length(): liefert ein Promise<number> mit der Anzahl der Einträge.
remainingBudget(): liefert das verbleibende Navigationsbudget in Bits für selectURL().
keys(), values(), entries() und [Symbol.asyncIterator](): asynchrone Iteratoren über den Speicher.
context: eine Zeichenkette mit Kontextdaten, die über FencedFrameConfig.setSharedStorageContext() eingebettet wurden. Nur in bestimmten Fenced-Frame-Szenarien verfügbar.

Typische Einsatzfälle sind A/B-Tests über Websites hinweg, Frequency Capping bei Werbung, das Zählen eindeutiger Reichweite (Unique Reach) und die Auswahl von Creatives, ohne dass Cookies von Drittanbietern nötig sind.

Parameter

Name	Typ	Default	Beschreibung
$key Pflicht	string		Für `get(key)` und die geerbten Methoden `set()`, `append()` und `delete()`: Schlüssel des Eintrags. Schlüssel und Wert sind jeweils auf 1024 UTF-16-Codeeinheiten begrenzt.
$value Pflicht	string		Für `set(key, value, options)` und `append(key, value)`: der Wert, der gespeichert bzw. angehängt wird.
$options.ignoreIfPresent	boolean	false	Für `set()`: Ist der Wert `true`, bleibt ein vorhandener Eintrag unverändert.

Rückgabewert

Typ

WorkletSharedStorage

Beschreibung

Die Instanz erreichst du im Worklet über die globale Eigenschaft sharedStorage. Alle Methoden arbeiten asynchron und liefern ein Promise bzw. einen asynchronen Iterator.

Beispiele

Worklet laden und Operation ausführen (Hauptseite)

// main.js: läuft im Dokument, z. B. in einem Werbe-Iframe
const init = async () => {
  if (!window.sharedStorage) {
    console.log('Shared Storage wird nicht unterstützt');
    return;
  }
  // Schreiben geht auch außerhalb des Worklets
  await window.sharedStorage.set('besuche', '0', { ignoreIfPresent: true });

  await window.sharedStorage.worklet.addModule('/shared-storage-worklet.js');
  await window.sharedStorage.run('besuche-zaehlen', {
    data: { seite: location.hostname }
  });
};

init();

Lesen und Schreiben im Worklet mit get() und set()

// shared-storage-worklet.js: hier ist 'sharedStorage' ein WorkletSharedStorage
class BesucheZaehlen {
  async run(data) {
    const aktuell = Number(await sharedStorage.get('besuche')) || 0;
    await sharedStorage.set('besuche', String(aktuell + 1));
    await sharedStorage.set(`zuletzt:${data.seite}`, String(Date.now()));
    console.log('Besuche gesamt:', aktuell + 1);
  }
}

register('besuche-zaehlen', BesucheZaehlen);

Besuche gesamt: 1

A/B-Test mit selectURL() über Websites hinweg

// ab-worklet.js
class AbTest {
  async run(urls, data) {
    let gruppe = await sharedStorage.get('ab-gruppe');
    if (gruppe === undefined) {
      gruppe = String(Math.floor(Math.random() * urls.length));
      await sharedStorage.set('ab-gruppe', gruppe);
    }
    // Rückgabewert = Index der URL, die der Fenced Frame zeigt
    return Number(gruppe);
  }
}
register('ab-test', AbTest);

// main.js
// await window.sharedStorage.worklet.addModule('/ab-worklet.js');
// const config = await window.sharedStorage.selectURL('ab-test', [
//   { url: '/creative-a.html' },
//   { url: '/creative-b.html' }
// ], { resolveToConfig: true });
// document.querySelector('fencedframe').config = config;

Alle Einträge asynchron durchlaufen

// report-worklet.js
class Bericht {
  async run() {
    console.log('Anzahl Einträge:', await sharedStorage.length());
    for await (const [key, value] of sharedStorage.entries()) {
      console.log(key, '=>', value);
    }
    // Kurzform über Symbol.asyncIterator:
    // for await (const [key, value] of sharedStorage) { ... }
  }
}
register('bericht', Bericht);

Anzahl Einträge: 2 besuche => 3 ab-gruppe => 1

Siehe auch

WindowSharedStorage SharedStorage WorkletGlobalScope CacheStorage WorkerNavigator