WindowSharedStorage — Schnittstelle · JavaScript-Referenz

Signatur

interface WindowSharedStorage extends SharedStorage

Beschreibung

WindowSharedStorage ist die Schnittstelle, die du im normalen Browser-Kontext (Dokument, Fenster) über window.sharedStorage erreichst. Sie gehört zur Shared Storage API aus Googles Privacy Sandbox. Damit kannst du Daten für einen Ursprung (Origin) speichern, die unabhängig von der einbettenden Website gelten, also websiteübergreifend, ohne Drittanbieter-Cookies.

Das Besondere: Im Fenster-Kontext kannst du Daten nur schreiben. Dafür gibt es die von SharedStorage geerbten Methoden set(), append(), delete() und clear(). Lesen ist nur in einem Shared-Storage-Worklet möglich. So bleibt sichergestellt, dass websiteübergreifende Daten nicht direkt in die Seite gelangen. Dazu kommen diese Mitglieder:

worklet: Das SharedStorageWorklet des aktuellen Ursprungs, geladen über worklet.addModule(url).
createWorklet(url, options): Erzeugt ein Worklet, das auch für einen anderen Ursprung arbeiten kann (neuere Chromium-Versionen).
run(name, options): Führt eine im Worklet registrierte Operation aus, z. B. um Berichte über die Private Aggregation API zu senden.
selectURL(name, urls, options): Lässt das Worklet anhand gespeicherter Daten eine URL aus einer Liste auswählen. Das Ergebnis ist eine undurchsichtige URL bzw. eine FencedFrameConfig, die sich nur in einem <fencedframe> oder <iframe> darstellen lässt.

Typische Einsätze sind A/B-Tests über mehrere Websites hinweg, Frequenzbegrenzung (Frequency Capping) von Werbung, Reichweitenmessung ohne Mehrfachzählung und die Auswahl von Inhalten nach Kohorten. Alle diese Fälle setzen darauf, dass die Rohdaten die Seite nie direkt erreichen.

Rückgabewert

Typ

WindowSharedStorage

Beschreibung

Die Instanz holst du über window.sharedStorage. Ist die API nicht verfügbar, ist die Eigenschaft undefined.

Beispiele

Werte schreiben (Fenster-Kontext)

if (!window.sharedStorage) {
  console.log('Shared Storage wird nicht unterstützt');
} else {
  // Gruppe nur setzen, wenn noch keine existiert
  await window.sharedStorage.set('ab-gruppe', String(Math.floor(Math.random() * 3)), {
    ignoreIfPresent: true,
  });

  // Wert anhängen und einzelnen Schlüssel löschen
  await window.sharedStorage.append('besuchte-kategorien', 'schuhe;');
  await window.sharedStorage.delete('veralteter-schluessel');
  console.log('Daten geschrieben');
}

Daten geschrieben

Worklet laden und Operation mit run() ausführen

// ---- datei: reach-worklet.js ----
// class ReachOperation {
//   async run(data) {
//     const gezaehlt = await sharedStorage.get(`gemeldet-${data.contentId}`);
//     if (gezaehlt) return;
//     privateAggregation.contributeToHistogram({ bucket: BigInt(data.contentId), value: 1 });
//     await sharedStorage.set(`gemeldet-${data.contentId}`, '1');
//   }
// }
// register('reach-messung', ReachOperation);

// ---- im Dokument ----
await window.sharedStorage.worklet.addModule('/reach-worklet.js');
await window.sharedStorage.run('reach-messung', {
  data: { contentId: 1234 },
  keepAlive: false,
});
console.log('Messung angestoßen');

Messung angestoßen

URL-Auswahl per selectURL() im Fenced Frame anzeigen

// Im Worklet (ab-worklet.js):
// class SelectVariant {
//   async run(urls, data) {
//     const gruppe = await sharedStorage.get('ab-gruppe');
//     return Number(gruppe ?? 0); // Index in die URL-Liste
//   }
// }
// register('ab-auswahl', SelectVariant);

await window.sharedStorage.worklet.addModule('/ab-worklet.js');

const config = await window.sharedStorage.selectURL(
  'ab-auswahl',
  [
    { url: 'https://cdn.example/variante-a.html' },
    { url: 'https://cdn.example/variante-b.html' },
    { url: 'https://cdn.example/variante-c.html' },
  ],
  { resolveToConfig: true }
);

const frame = document.createElement('fencedframe');
frame.config = config; // Inhalt bleibt für die Seite undurchsichtig
document.body.append(frame);

// Wichtig · Fallstricke

Experimentell und nur in Chromium: Die API gibt es nur in Chrome/Edge (ab etwa Version 115). Firefox und Safari unterstützen sie nicht. Aufrufer müssen sich für die Privacy Sandbox registrieren und bestätigen (Enrollment/Attestation), sonst werden die Aufrufe abgelehnt. Google hat angekündigt, mehrere Privacy-Sandbox-Techniken zurückzubauen. Prüfe den aktuellen Stand, bevor du produktiv darauf setzt.
Kein get() im Fenster: Lesen geht nur im Worklet über das globale sharedStorage. window.sharedStorage.get gibt es nicht.
Feature-Erkennung: Prüfe immer vorher mit if (window.sharedStorage). Die Methoden werfen Fehler bzw. weisen Promises zurück, wenn der Nutzer die Privacy-Sandbox-Einstellungen deaktiviert hat.
Grenzen: Schlüssel und Werte sind in der Länge begrenzt, der Speicher pro Ursprung ist begrenzt, und selectURL() unterliegt einem Budget (Entropie-Bits) pro Seite und Website. Bei selectURL() sind höchstens 8 URLs erlaubt.
keepAlive: Nach run() oder selectURL() wird das Worklet standardmäßig beendet. Für mehrere Aufrufe musst du keepAlive: true setzen.
Die API funktioniert nur in sicheren Kontexten (HTTPS).

Siehe auch

WorkletSharedStorage SharedStorage CacheStorage SharedWorker WindowClient