SharedStorage.set() — Methode · JavaScript-Referenz

Signatur

SharedStorage.prototype.set(key, value, options)

Beschreibung

Mit set() schreibst du einen Wert in den Shared Storage, einen Speicher der Privacy Sandbox. Er ist an den Ursprung gebunden, kann aber websiteübergreifend genutzt werden. Anders als localStorage ist er nicht nach Top-Level-Website getrennt. Deshalb darf er zwar beliebig beschrieben, aber nur innerhalb eines Shared-Storage-Worklets gelesen werden. Die Ergebnisse gelangen nur über datenschutzfreundliche Ausgabewege nach außen, etwa selectURL() oder Private Aggregation.

Die Methode gibt es in zwei Kontexten: im Fensterkontext über window.sharedStorage.set() und im Worklet über sharedStorage.set() (dort als WorkletSharedStorage). Typische Einsätze sind A/B-Test-Gruppen, Frequency Capping bei Werbung (wie oft wurde eine Anzeige gezeigt?) und die websiteübergreifende Reichweitenmessung.

Ist der Schlüssel schon vorhanden, wird sein Wert standardmäßig überschrieben. Mit der Option ignoreIfPresent: true bleibt ein vorhandener Wert erhalten. So lässt sich zum Beispiel eine einmal zugeteilte Testgruppe dauerhaft festhalten. Wenn du an einen Wert etwas anhängen statt ihn ersetzen willst, nimm append().

Parameter

Name	Typ	Default	Beschreibung
$key Pflicht	string		Schlüssel des Eintrags. Er darf nicht leer sein und höchstens 1024 UTF-16-Codeeinheiten lang sein.
$value Pflicht	string		Zu speichernder Wert, höchstens 1024 UTF-16-Codeeinheiten. Andere Typen werden in Strings umgewandelt. Für Objekte nimm deshalb `JSON.stringify()`.
$options	object	{}	Optionales Objekt mit Einstellungen: `ignoreIfPresent` (`boolean`, Standard `false`): Bei `true` wird ein vorhandener Eintrag nicht überschrieben. `withLock` (`string`, neuere Chromium-Versionen): Name einer Web Lock, die während des Schreibens gehalten wird.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald der Schreibvorgang angenommen wurde. Bei ungültigen Argumenten oder wenn Shared Storage nicht verfügbar ist, wird es mit einem TypeError abgelehnt.

Beispiele

A/B-Testgruppe einmalig festlegen

// Gruppe nur zuweisen, wenn noch keine gespeichert ist
const assignExperimentGroup = async () => {
  if (!('sharedStorage' in window)) {
    console.log('Shared Storage wird nicht unterstützt');
    return;
  }
  const group = Math.random() < 0.5 ? 'A' : 'B';
  try {
    await window.sharedStorage.set('ab-test-group', group, {
      ignoreIfPresent: true
    });
    console.log('Gruppe gespeichert (sofern noch nicht vorhanden)');
  } catch (err) {
    console.error('Schreiben fehlgeschlagen:', err);
  }
};

assignExperimentGroup();

Gruppe gespeichert (sofern noch nicht vorhanden)

Frequency Capping im Worklet

// frequency-worklet.js – läuft im Shared-Storage-Worklet
class IncrementImpression {
  async run({ campaignId }) {
    const key = `impressions:${campaignId}`;
    const current = Number(await sharedStorage.get(key)) || 0;
    await sharedStorage.set(key, String(current + 1));
  }
}
register('increment-impression', IncrementImpression);

// Hauptskript der Seite:
await window.sharedStorage.worklet.addModule('/frequency-worklet.js');
await window.sharedStorage.run('increment-impression', {
  data: { campaignId: 'sommer-2024' }
});

Strukturierte Daten als JSON speichern

const prefs = { theme: 'dark', lang: 'de' };
const serialized = JSON.stringify(prefs);

// Längenlimit vorab prüfen (max. 1024 Codeeinheiten)
if (serialized.length <= 1024) {
  await window.sharedStorage.set('user-prefs', serialized);
  console.log('Gespeichert:', serialized);
} else {
  console.warn('Wert zu lang für Shared Storage');
}

Gespeichert: {"theme":"dark","lang":"de"}

// Wichtig · Fallstricke

Experimentell und eingestellt: Shared Storage gehört zur Privacy Sandbox von Chrome, deren Technologien Google 2025 größtenteils eingestellt hat. Firefox und Safari unterstützen die API nicht. Frage die Verfügbarkeit immer mit 'sharedStorage' in window ab und setze die API nicht für produktionskritische Funktionen ein.
Anmeldung nötig: In Chrome muss der aufrufende Ursprung für die Privacy Sandbox angemeldet und bestätigt sein (Enrollment und Attestation). Außerdem können Nutzer die API in den Datenschutzeinstellungen abschalten. Beides führt zu einem abgelehnten Promise.
Kein Lesen im Fenster: get() gibt es nur im Worklet. Werte, die du mit set() schreibst, kannst du also im Hauptskript nicht direkt wieder auslesen.
Grenzen: Schlüssel und Werte dürfen jeweils höchstens 1024 Codeeinheiten lang sein. Auch pro Ursprung ist der Speicher begrenzt. Ist ein Limit überschritten, gibt es einen TypeError.
Wettlaufsituationen: Das Muster „lesen, dann schreiben“ (siehe Beispiel „Frequency Capping“) ist nicht atomar. Für nebenläufige Zugriffe nutze die Option withLock oder batchUpdate(), sofern verfügbar.
Alternative per HTTP: Auch der Server kann schreiben, mit dem Antwort-Header Shared-Storage-Write: set;key=\"k\";value=\"v\". Voraussetzung ist ein Request mit fetch(url, { sharedStorageWritable: true }).

Siehe auch

new MediaStreamEvent() SharedStorage.clear() SharedStorage.delete() SharedStorage.append() CacheStorage.has()