Window.sharedStorage — Eigenschaft · JavaScript-Referenz

Signatur

Window.sharedStorage

Beschreibung

window.sharedStorage ist der Einstiegspunkt der Shared Storage API, die im Rahmen der Privacy Sandbox entstanden ist. Die Eigenschaft liefert ein WindowSharedStorage-Objekt. Darüber kann eine Origin Daten speichern, die nicht nach Top-Level-Website getrennt sind. Anders als bei localStorage sieht ein eingebettetes Drittanbieter-Skript also dieselben Daten, egal auf welcher Website es läuft.

Die gespeicherten Daten kann das Fenster aber nicht direkt zurücklesen. Nur ein Shared-Storage-Worklet kann sie lesen, und zwar in einer abgeschotteten Umgebung. Das Ergebnis verlässt das Worklet nur über datenschutzfreundliche Ausgabekanäle:

selectURL() wählt eine von mehreren URLs aus. Das Ergebnis ist nicht auslesbar, sondern wird nur in einem <fencedframe> dargestellt. Typische Einsätze sind A/B-Tests oder Werbemotive, die sich nach der Häufigkeit richten.
run() führt eine Operation aus, die ihre Ergebnisse zum Beispiel über die Private Aggregation API meldet, etwa für Reichweitenmessung über Websites hinweg.

Direkt im Fenster stehen die schreibenden Methoden set(), append(), delete() und clear() zur Verfügung. Dazu kommen die Eigenschaft worklet (ein SharedStorageWorklet, geladen mit addModule()) sowie createWorklet() für Worklets anderer Origins. Alle Methoden geben Promises zurück.

Rückgabewert

Typ

WindowSharedStorage

Beschreibung

Das WindowSharedStorage-Objekt der aktuellen Origin. In Browsern ohne Unterstützung ist die Eigenschaft undefined.

Beispiele

Unterstützung prüfen und Werte schreiben

// Unterstützung prüfen und Werte in den Shared Storage schreiben
const saveVisit = async () => {
  if (!('sharedStorage' in window)) {
    console.log('Shared Storage wird nicht unterstützt');
    return;
  }
  // Nur setzen, wenn der Schlüssel noch nicht existiert
  await window.sharedStorage.set('first-visit', Date.now().toString(), {
    ignoreIfPresent: true,
  });
  // Wert an einen bestehenden Eintrag anhängen
  await window.sharedStorage.append('visited-sites', `${location.hostname};`);
  console.log('Daten gespeichert');
};

saveVisit();

Daten gespeichert

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

// Datei ab-worklet.js (läuft im Shared-Storage-Worklet)
class SelectVariant {
  async run(urls) {
    // Im Worklet ist das Lesen erlaubt
    const group = await sharedStorage.get('ab-group');
    return group === 'B' ? 1 : 0; // Index der gewählten URL
  }
}
register('ab-test', SelectVariant);

// Datei main.js (Fensterkontext)
const runExperiment = async () => {
  await window.sharedStorage.set('ab-group', Math.random() &lt; 0.5 ? 'A' : 'B', {
    ignoreIfPresent: true,
  });
  await window.sharedStorage.worklet.addModule('/ab-worklet.js');

  const config = await window.sharedStorage.selectURL(
    'ab-test',
    [{ url: '/banner-a.html' }, { url: '/banner-b.html' }],
    { resolveToConfig: true }
  );
  // Das Ergebnis ist undurchsichtig und nur im Fenced Frame darstellbar
  document.querySelector('fencedframe').config = config;
};

runExperiment();

Operation mit run() ausführen und Daten löschen

// Datei reach-worklet.js
class CountReach {
  async run(data) {
    const seen = await sharedStorage.get(`seen-${data.campaignId}`);
    if (!seen) {
      await sharedStorage.set(`seen-${data.campaignId}`, '1');
      // Meldung z. B. über privateAggregation.contributeToHistogram(...)
    }
  }
}
register('count-reach', CountReach);

// Fensterkontext
const measure = async () => {
  await window.sharedStorage.worklet.addModule('/reach-worklet.js');
  await window.sharedStorage.run('count-reach', { data: { campaignId: 42 } });

  // Später: einzelnen Schlüssel oder alles löschen
  await window.sharedStorage.delete('first-visit');
  // await window.sharedStorage.clear();
};

measure();

// Wichtig · Fallstricke

Experimentell und nur in Chromium verfügbar: Firefox und Safari unterstützen die API nicht. Prüfen Sie deshalb immer vorher mit 'sharedStorage' in window. Google hat angekündigt, Teile der Privacy Sandbox einzustellen. Die Zukunft der API ist ungewiss, deshalb sollte kein zentraler Anwendungsfall allein darauf aufbauen.
Registrierung erforderlich: Chrome verlangt eine Privacy-Sandbox-Registrierung mit Attestierung der aufrufenden Origin. Ohne sie schlagen die Aufrufe fehl. Außerdem kann der Nutzer die API in den Datenschutzeinstellungen abschalten. Dann werden die Promises abgelehnt.
Kein Lesezugriff im Fenster: get() ist nur im Worklet verfügbar (und in bestimmten Fenced-Frame-Kontexten). Wer Werte zurücklesen will, muss den Umweg über selectURL() oder run() gehen.
Grenzen und Budgets: Schlüssel und Werte sind in ihrer Länge begrenzt, und der Speicher pro Origin ist beschränkt. Für selectURL() gilt ein Entropie-Budget: Jeder Aufruf mit n URLs verbraucht log2(n) Bit. Ist das Budget erschöpft, wird immer die Standard-URL (Index 0) gewählt.
Nur in sicheren Kontexten (HTTPS): Die API steht außerdem nicht in allen Iframe-Kontexten zur Verfügung. Die Permissions-Policy shared-storage bzw. shared-storage-select-url kann sie sperren.
Ein Worklet kann pro Kontext nur einmal mit addModule() geladen werden. Für mehrere Module oder fremde Origins nutzen Sie createWorklet().

Siehe auch

SharedStorageWorkletGlobalScope.sharedStorage Window.localStorage Window.sessionStorage Window.cookieStore Window.history