WorkletSharedStorage.entries() — Methode · JavaScript-Referenz

Signatur

WorkletSharedStorage.prototype.entries()

Beschreibung

Die Methode entries() der Schnittstelle WorkletSharedStorage ist Teil der Shared Storage API aus der Privacy Sandbox. Sie gibt einen asynchronen Iterator zurück. Mit ihm gehen Sie alle Einträge durch, die der aktuelle Ursprung im Shared Storage gespeichert hat. Jeder Schritt liefert ein Array [key, value], in dem beide Werte Strings sind.

Lesen dürfen Sie den Shared Storage nur innerhalb eines Shared-Storage-Worklets, also im SharedStorageWorkletGlobalScope. Dort steht das globale Objekt sharedStorage zur Verfügung. Auf der Hauptseite (window.sharedStorage) können Sie nur schreiben (set(), append(), delete(), clear()), aber nicht lesen. So gelangen die gespeicherten Daten, die über Websites hinweg gelten, nicht direkt zurück zur einbettenden Seite.

Typischerweise nutzen Sie entries() in den Operationen run() oder selectURL(), die Sie mit register() anmelden. Damit werten Sie alle gespeicherten Werte aus, zum Beispiel für A/B-Tests, Frequency Capping oder aggregierte Reichweitenmessung über die Private Aggregation API. Iterieren Sie den Rückgabewert mit for await...of.

Rückgabewert

Typ

AsyncIterator<[string, string]>

Beschreibung

Ein asynchroner Iterator. Jeder Schritt liefert ein Array [key, value] mit einem gespeicherten Schlüssel und seinem Wert, beide als Strings.

Beispiele

Alle Einträge im Worklet protokollieren

// shared-storage-worklet.js
class LogEntriesOperation {
  async run(data) {
    for await (const [key, value] of sharedStorage.entries()) {
      console.log(`${key}: ${value}`);
    }
  }
}

register('log-entries', LogEntriesOperation);

// main.js (Hauptseite)
const start = async () => {
  await window.sharedStorage.set('experiment-gruppe', 'B');
  await window.sharedStorage.set('besuche', '3');
  await window.sharedStorage.worklet.addModule('shared-storage-worklet.js');
  await window.sharedStorage.run('log-entries');
};

start();

experiment-gruppe: B besuche: 3 (Ausgabe in der DevTools-Konsole des Worklets)

Einträge per Präfix filtern und in selectURL() auswerten

// ab-test-worklet.js
class SelectCreative {
  async run(urls, data) {
    let impressions = 0;
    for await (const [key, value] of sharedStorage.entries()) {
      if (key.startsWith('impression:')) {
        impressions += Number.parseInt(value, 10) || 0;
      }
    }
    // Frequency Capping: ab 5 Einblendungen zweite URL wählen
    return impressions >= 5 ? 1 : 0;
  }
}

register('select-creative', SelectCreative);

// main.js
const showAd = async () => {
  await window.sharedStorage.worklet.addModule('ab-test-worklet.js');
  const config = await window.sharedStorage.selectURL('select-creative', [
    { url: 'https://werbung.example/standard.html' },
    { url: 'https://werbung.example/alternativ.html' }
  ], { resolveToConfig: true });
  document.querySelector('fencedframe').config = config;
};

showAd();

Iterator manuell mit next() abfragen

// worklet.js
class FirstEntry {
  async run() {
    const iterator = sharedStorage.entries();
    const { value, done } = await iterator.next();
    if (!done) {
      const [key, val] = value;
      console.log('Erster Eintrag:', key, '=', val);
    } else {
      console.log('Shared Storage ist leer');
    }
  }
}

register('first-entry', FirstEntry);

Erster Eintrag: experiment-gruppe = B

// Wichtig · Fallstricke

Nur im Worklet verfügbar: entries() gibt es ausschließlich im SharedStorageWorkletGlobalScope. Auf window.sharedStorage existiert die Methode nicht, weil die Hauptseite den Shared Storage nicht lesen darf.
Experimentell und nur in Chromium: Firefox und Safari unterstützen die API nicht. In Chrome braucht der aufrufende Ursprung eine Registrierung (Enrollment) für die Privacy Sandbox. Außerdem kann der Nutzer die API in den Einstellungen deaktivieren. Google hat angekündigt, mehrere Privacy-Sandbox-APIs einzustellen. Prüfen Sie deshalb die Verfügbarkeit, zum Beispiel mit 'sharedStorage' in window, und planen Sie Ausweichlösungen ein.
Nur Strings: Schlüssel und Werte sind immer Strings. Zahlen oder Objekte müssen Sie selbst umwandeln, etwa mit JSON.parse() oder Number.parseInt().
Kein direkter Datenrückfluss: Mit run() gelangen keine Ergebnisse zur Seite. Mit selectURL() kommt nur eine undurchsichtige URL bzw. ein FencedFrameConfig an. console.log im Worklet sehen Sie nur in den DevTools.
Kein fester Stand: Ändern andere Kontexte den Storage während der Iteration, kann das Ergebnis diese Änderungen enthalten oder nicht. Die Reihenfolge der Einträge ist nicht garantiert.
Bei vielen Einträgen dauert die Iteration länger. Brechen Sie mit break ab, sobald Sie genug Daten haben.

Siehe auch

for await...of WorkletSharedStorage.get() WorkletSharedStorage.keys() WorkletSharedStorage.length() WorkletSharedStorage.remainingBudget()