SharedStorage — Schnittstelle · JavaScript-Referenz

Signatur

interface SharedStorage

Beschreibung

Das Interface SharedStorage gehört zur Shared Storage API aus Googles Privacy Sandbox. Es steht für einen Schlüssel-Wert-Speicher, der einem bestimmten Ursprung zugeordnet ist, aber – anders als localStorage – nicht nach der obersten Website partitioniert wird. Ein eingebettetes Drittanbieter-Skript (etwa ein Werbe- oder Analysedienst) kann dadurch websiteübergreifend Daten ablegen, ohne Third-Party-Cookies zu brauchen.

Wichtig ist das Datenschutzmodell: Im normalen Seitenkontext darf nur geschrieben werden. Lesen ist ausschließlich innerhalb eines Shared-Storage-Worklets erlaubt, und die Ergebnisse verlassen das Worklet nur über eingeschränkte Ausgabekanäle wie selectURL() (Auswahl einer URL, dargestellt in einem Fenced Frame) oder die Private Aggregation API.

Direkt instanziert wird SharedStorage nicht. Man greift darauf zu über:

window.sharedStorage – ein WindowSharedStorage, der zusätzlich run(), selectURL() und worklet bereitstellt;
sharedStorage im Worklet-Scope – ein WorkletSharedStorage mit den Lesemethoden get(), length(), keys(), entries() und remainingBudget().

Die gemeinsamen Methoden sind set(key, value, options), append(key, value), delete(key) und clear(). Alle geben ein Promise zurück, das bei Erfolg mit undefined erfüllt wird.

Parameter

Name	Typ	Default	Beschreibung
$key Pflicht	string		Schlüssel des Eintrags (für `set()`, `append()`, `delete()`). Die Länge ist begrenzt (derzeit 1024 UTF-16-Codeeinheiten).
$value Pflicht	string		Wert, der gespeichert (`set()`) oder an einen bestehenden Wert angehängt (`append()`) wird. Nicht-Strings werden in Strings umgewandelt.
$options	{ ignoreIfPresent?: boolean }	{ ignoreIfPresent: false }	Nur bei `set()`: Ist `ignoreIfPresent` gleich `true`, wird ein schon vorhandener Schlüssel nicht überschrieben.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Jede schreibende Methode (set, append, delete, clear) gibt ein Promise zurück. Es wird mit undefined erfüllt, sobald die Operation eingereiht ist, und bei Fehlern (z. B. API deaktiviert, Schlüssel zu lang) abgelehnt.

Beispiele

Feature-Erkennung und Wert schreiben

// Zugriff erfolgt über window.sharedStorage (WindowSharedStorage extends SharedStorage)
const storeExperimentGroup = async () => {
  if (!('sharedStorage' in window)) {
    console.log('Shared Storage wird nicht unterstützt');
    return;
  }
  try {
    // Nur setzen, wenn noch keine Gruppe zugewiesen ist
    await window.sharedStorage.set('ab-gruppe', String(Math.floor(Math.random() * 3)), {
      ignoreIfPresent: true,
    });
    console.log('Gruppe gespeichert');
  } catch (err) {
    console.error('Schreiben fehlgeschlagen:', err);
  }
};

storeExperimentGroup();

Gruppe gespeichert

Werte anhängen, löschen und leeren

const trackVisit = async (seite) => {
  // Hängt an einen bestehenden Wert an bzw. legt ihn neu an
  await window.sharedStorage.append('besuchte-seiten', `${seite};`);
};

const resetUserData = async () => {
  await window.sharedStorage.delete('ab-gruppe'); // einzelnen Schlüssel entfernen
  await window.sharedStorage.clear();             // gesamten Speicher des Ursprungs leeren
  console.log('Shared Storage geleert');
};

await trackVisit('/produkte');
await resetUserData();

Shared Storage geleert

Lesen nur im Worklet: Daten in einer Operation auswerten

// datei: frequency-worklet.js (läuft im SharedStorageWorkletGlobalScope)
class ZaehleBesuche {
  async run(data) {
    const bisher = Number(await sharedStorage.get('besuche')) || 0;
    await sharedStorage.set('besuche', String(bisher + 1));
  }
}
register('zaehle-besuche', ZaehleBesuche);

// datei: main.js (Seitenkontext)
await window.sharedStorage.worklet.addModule('/frequency-worklet.js');
await window.sharedStorage.run('zaehle-besuche');
console.log('Operation ausgeführt');

Operation ausgeführt

// Wichtig · Fallstricke

Kompatibilität: Die API ist experimentell, nicht standardisiert und nur in Chromium-basierten Browsern (ab Chrome 115) verfügbar. Firefox und Safari unterstützen sie nicht. Google hat 2025 angekündigt, mehrere Privacy-Sandbox-APIs einzustellen, darunter auch Teile rund um Shared Storage und selectURL(). Vor dem Einsatz daher den aktuellen Stand prüfen und immer mit 'sharedStorage' in window auf Unterstützung testen.
Kein Lesen im Seitenkontext: get(), keys() usw. gibt es nur in WorkletSharedStorage. Ein Aufruf von window.sharedStorage.get() schlägt fehl – das ist gewollt und dient dem Datenschutz.
Registrierung und Attestierung: Chrome verlangt eine Privacy-Sandbox-Registrierung des aufrufenden Ursprungs. Außerdem kann die API durch Nutzereinstellungen, den Inkognito-Modus oder die Permissions Policy (shared-storage) deaktiviert sein. Dann wird das Promise abgelehnt.
Grenzen: Schlüssel und Werte sind in der Länge begrenzt, und die Anzahl der Einträge pro Ursprung ist gedeckelt. Einträge verfallen etwa 30 Tage nach dem letzten Schreibzugriff.
Schreiben per HTTP: Alternativ lässt sich über den Antwort-Header Shared-Storage-Write schreiben, wenn die Anfrage mit sharedStorageWritable (z. B. fetch(url, { sharedStorageWritable: true })) gestellt wurde. Neuere Chrome-Versionen bieten zusätzlich batchUpdate() für mehrere Operationen am Stück.

Siehe auch

Storage CacheStorage SharedWorker WindowSharedStorage SharedStorageWorklet