WorkletSharedStorage.get() — Methode · JavaScript-Referenz

Signatur

WorkletSharedStorage.prototype.get(key)

Beschreibung

Die Methode get() der Schnittstelle WorkletSharedStorage gibt ein Promise zurück, das mit dem gespeicherten Wert zu einem Schlüssel erfüllt wird. Gibt es den Schlüssel nicht, ist der Wert undefined. Die Shared Storage API ist Teil der Privacy Sandbox. Mit ihr lassen sich Daten ursprungsbezogen, aber websiteübergreifend speichern, ohne Drittanbieter-Cookies zu verwenden.

Das Besondere daran: Lesen ist nur im Worklet möglich. Im Hauptkontext (window.sharedStorage, also WindowSharedStorage) kannst du nur schreiben (set(), append(), delete(), clear()). Die gelesenen Daten verlassen das Worklet nur über Ausgabekanäle mit Datenschutzvorkehrungen, zum Beispiel selectURL() (Auswahl einer URL, die in einem Fenced Frame angezeigt wird) oder die Private Aggregation API.

Typische Einsatzfälle sind A/B-Tests über mehrere Websites hinweg, Frequency Capping (Werbung wird nur begrenzt oft angezeigt), Reichweitenmessung ohne Duplikate oder die Personalisierung eingebetteter Inhalte. Du rufst get() meistens in der run()-Methode einer Operationsklasse auf, die du mit register() im Worklet registriert hast. Auf das Objekt greifst du dort über this.sharedStorage oder die globale Variable sharedStorage zu.

Parameter

Name	Typ	Default	Beschreibung
$key Pflicht	string		Schlüssel des Eintrags, der gelesen werden soll. Er muss mindestens 1 und darf höchstens 1024 UTF-16-Codeeinheiten lang sein.

Rückgabewert

Typ

Promise<string | undefined>

Beschreibung

Ein Promise, das mit dem gespeicherten String erfüllt wird. Existiert der Schlüssel nicht, wird es mit undefined erfüllt. Abgelehnt wird es mit einem TypeError, wenn der Schlüssel ungültig ist (leer oder zu lang), wenn Shared Storage deaktiviert ist oder wenn das Worklet-Modul nicht korrekt hinzugefügt wurde.

Beispiele

A/B-Test: Gruppe lesen und URL auswählen (Worklet)

// ab-worklet.js – wird im Shared-Storage-Worklet ausgeführt
class SelectVariantOperation {
  async run(urls, data) {
    // Gespeicherte Testgruppe lesen ("0", "1" oder undefined)
    const group = await this.sharedStorage.get('ab-testing-group');

    // Fallback: Standardvariante, wenn noch keine Gruppe vergeben wurde
    const index = Number.parseInt(group ?? '0', 10);
    return Number.isInteger(index) && index < urls.length ? index : 0;
  }
}

register('select-variant', SelectVariantOperation);

Hauptseite: Gruppe setzen, Worklet laden, Operation ausführen

// main.js – läuft im Dokument (z. B. im Skript eines Drittanbieters)
const runAbTest = async () => {
  if (!('sharedStorage' in window)) {
    console.log('Shared Storage wird nicht unterstützt');
    return;
  }

  // Schreiben geht auch im Hauptkontext; ignoreIfPresent behält eine bestehende Gruppe
  await window.sharedStorage.set(
    'ab-testing-group',
    String(Math.round(Math.random())),
    { ignoreIfPresent: true }
  );

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

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

  // Ergebnis ist nur als opakes FencedFrameConfig nutzbar
  document.querySelector('fencedframe').config = config;
};

runAbTest();

Frequency Capping mit Zähler und Private Aggregation

// reach-worklet.js
class ReachMeasurementOperation {
  async run(data) {
    const key = `seen:${data.campaignId}`;

    // Bereits gezählt? Dann nichts tun.
    const alreadySeen = await sharedStorage.get(key);
    if (alreadySeen !== undefined) return;

    privateAggregation.contributeToHistogram({
      bucket: BigInt(data.campaignId),
      value: 1
    });

    await sharedStorage.set(key, '1');
  }
}

register('reach-measurement', ReachMeasurementOperation);

// Auf der Hauptseite:
// await window.sharedStorage.worklet.addModule('reach-worklet.js');
// await window.sharedStorage.run('reach-measurement', { data: { campaignId: 1234 } });

// Wichtig · Fallstricke

Nur im Worklet verfügbar: Im normalen Dokumentkontext gibt es kein allgemeines window.sharedStorage.get(). Das ist beabsichtigt, damit sich keine websiteübergreifenden Daten direkt auslesen lassen. Eine Ausnahme sind Fenced Frames, deren Netzwerkzugriff widerrufen wurde. Dort erlaubt Chromium den Lesezugriff.
Kompatibilität: Die Funktion ist experimentell und nur in Chromium-Browsern verfügbar, Firefox und Safari unterstützen sie nicht. Sie setzt voraus, dass die Privacy-Sandbox-APIs aktiviert sind und der Ursprung für die Privacy Sandbox registriert ist (Enrollment/Attestierung). Google hat angekündigt, mehrere Privacy-Sandbox-Technologien einzustellen. Prüfe den aktuellen Status, bevor du die Funktion in Produktion einsetzt, und prüfe die Unterstützung vorher mit 'sharedStorage' in window.
Werte sind immer Strings: Zahlen oder Objekte musst du selbst umwandeln, zum Beispiel mit Number.parseInt() oder JSON.parse(). Bei einem fehlenden Schlüssel kommt undefined zurück, nicht null.
Speicherbezug: Die Daten gehören zum Ursprung des Worklet-Moduls, nicht zur Website der obersten Ebene. Einträge laufen standardmäßig 30 Tage nach dem letzten Schreiben ab.
Budgets: Aufrufe von selectURL(), die mehrere URLs berücksichtigen, verbrauchen ein Entropie-Budget. Die Private Aggregation hat ein eigenes Beitragsbudget. Wird ein Budget überschritten, gibt der Browser stillschweigend die Standard-URL zurück.
Den Rückgabewert immer mit await abwarten. Wird ein abgelehntes Promise in run() nicht behandelt, bricht die gesamte Operation ab.

Siehe auch

WorkletSharedStorage.keys() WorkletSharedStorage.length() WorkletSharedStorage.entries() WorkletSharedStorage.remainingBudget() SharedStorage.set()