SharedStorageWorkletGlobalScope.sharedStorage — Eigenschaft · JavaScript-Referenz

Signatur

SharedStorageWorkletGlobalScope.sharedStorage

Beschreibung

Die schreibgeschützte Eigenschaft sharedStorage des globalen Worklet-Kontexts SharedStorageWorkletGlobalScope gibt ein WorkletSharedStorage-Objekt zurück. Darüber greift der Code innerhalb eines Shared-Storage-Worklets auf den Schlüssel-Wert-Speicher des Ursprungs zu, der das Worklet geladen hat. Weil es eine globale Eigenschaft ist, schreibt man im Worklet-Modul einfach sharedStorage.get(...) ohne vorangestelltes Objekt.

Anders als window.sharedStorage im Hauptdokument, das nur schreiben kann (set(), append(), delete(), clear()), erlaubt die Worklet-Variante auch das Lesen der Daten: get(), keys(), entries(), length() und remainingBudget(). Zusätzlich gibt es die Eigenschaft context mit eingebetteten Kontextdaten. Dieses Lesen ist absichtlich nur im abgeschotteten Worklet möglich. Die Ergebnisse gelangen nur über datenschutzfreundliche Ausgabekanäle nach außen: selectURL() (URL-Auswahl für einen Fenced Frame) oder run() in Verbindung mit der Private Aggregation API.

Typische Einsätze sind A/B-Tests über Websites hinweg, Frequenzbegrenzung von Werbung, Rotation von Werbemitteln oder das Zählen von Reichweiten, ohne Cookies von Drittanbietern. Du verwendest die Eigenschaft in den run()-Methoden der Operationsklassen, die du mit register() anmeldest.

Rückgabewert

Typ

WorkletSharedStorage

Beschreibung

Ein WorkletSharedStorage-Objekt mit asynchronen Lese- und Schreibmethoden (get, set, append, delete, clear, keys, entries, length, remainingBudget) für den gemeinsamen Speicher des Ursprungs.

Beispiele

A/B-Test-Gruppe im Worklet lesen und per selectURL ausspielen

// ab-worklet.js – läuft im SharedStorageWorkletGlobalScope
class ABTestOperation {
  async run(urls, data) {
    // sharedStorage ist hier global verfügbar
    const group = await sharedStorage.get('ab-gruppe');
    // Index der URL zurückgeben, die angezeigt werden soll
    return group === 'B' ? 1 : 0;
  }
}

register('ab-test', ABTestOperation);

// main.js – im Hauptdokument
await window.sharedStorage.set('ab-gruppe', Math.random() < 0.5 ? 'A' : 'B', {
  ignoreIfPresent: true
});
await window.sharedStorage.worklet.addModule('/ab-worklet.js');

const config = await window.sharedStorage.selectURL(
  'ab-test',
  [{ url: '/variante-a.html' }, { url: '/variante-b.html' }],
  { resolveToConfig: true }
);
document.querySelector('fencedframe').config = config;

Frequenzbegrenzung: Zähler im Worklet lesen und erhöhen

// frequency-worklet.js
class FrequencyCapOperation {
  async run(urls, data) {
    const key = `impressions:${data.campaignId}`;
    const count = Number(await sharedStorage.get(key)) || 0;

    if (count >= 3) {
      return 1; // Ersatzwerbung
    }

    await sharedStorage.set(key, String(count + 1));
    return 0; // Kampagnenwerbung
  }
}

register('frequency-cap', FrequencyCapOperation);

Alle Einträge durchlaufen und über Private Aggregation melden

// report-worklet.js
class ReportOperation {
  async run(data) {
    const total = await sharedStorage.length();
    console.log(`Einträge im Speicher: ${total}`);

    for await (const [key, value] of sharedStorage.entries()) {
      if (key.startsWith('besuch:')) {
        privateAggregation.contributeToHistogram({
          bucket: BigInt(data.bucket),
          value: Number(value)
        });
      }
    }
  }
}

register('report', ReportOperation);

// main.js
await window.sharedStorage.worklet.addModule('/report-worklet.js');
await window.sharedStorage.run('report', { data: { bucket: 42 } });

Einträge im Speicher: 5

// Wichtig · Fallstricke

Kompatibilität: Die Shared Storage API ist experimentell und gehört zur Privacy Sandbox von Google. Sie gibt es nur in Chromium-Browsern, Firefox und Safari unterstützen sie nicht. Google hat angekündigt, mehrere Privacy-Sandbox-Techniken einzustellen. Prüfe den aktuellen Stand, bevor du sie in Produktion nutzt, und frage die Unterstützung ab, z. B. mit 'sharedStorage' in window.
Registrierung erforderlich: Die API funktioniert nur für Ursprünge, die bei der Privacy Sandbox registriert und bestätigt sind (Enrollment). Sonst schlagen die Aufrufe fehl.
Nur im Worklet lesbar: get(), keys() und entries() gibt es ausschließlich in sharedStorage im Worklet. Im Hauptdokument kann man den Speicher nur beschreiben.
Kein direkter Datenabfluss: Das Worklet hat keinen Netzwerkzugriff (fetch fehlt) und keinen DOM-Zugriff. Ergebnisse verlassen das Worklet nur über selectURL() oder Private Aggregation. selectURL() verbraucht ein Entropie-Budget, das du mit remainingBudget() abfragen kannst.
Nur Zeichenketten: Schlüssel und Werte werden als Strings gespeichert, und ihre Länge ist begrenzt. Zahlen musst du daher selbst umwandeln (Number()/String()).
Alle Methoden sind asynchron. Vergisst du await, verarbeitest du ein Promise statt des Werts.

Siehe auch

AudioWorkletGlobalScope.currentFrame AudioWorkletGlobalScope.sampleRate AudioWorkletGlobalScope.currentTime ServiceWorkerGlobalScope.cookieStore SharedWorkerGlobalScope.name