WorkletSharedStorage.length() — Methode · JavaScript-Referenz

Signatur

WorkletSharedStorage.prototype.length()

Beschreibung

Die Methode length() des Interfaces WorkletSharedStorage ermittelt, wie viele Schlüssel-Wert-Paare derzeit im gemeinsamen Speicher (Shared Storage) des aktuellen Ursprungs abgelegt sind. Sie gehört zur Shared Storage API der Privacy Sandbox, mit der Daten ursprungsübergreifend (auch in Drittanbieter-Kontexten) gespeichert, aber nur in einer abgeschotteten Umgebung gelesen werden können.

Wichtig ist der Ausführungskontext: length() gibt es nur im Worklet, also in dem Skript, das Sie mit window.sharedStorage.worklet.addModule() laden. Dort steht das globale Objekt sharedStorage (eine WorkletSharedStorage-Instanz) bereit. Im Hauptdokument hat window.sharedStorage (Typ WindowSharedStorage) nur Schreibmethoden wie set(), append(), delete() und clear(). Lesen ist dort absichtlich nicht möglich.

Typische Einsatzzwecke sind z. B. zu prüfen, ob schon Daten vorhanden sind, bevor eine Operation weiterläuft, Frequenzbegrenzungen (Frequency Capping) umzusetzen oder Einträge in einer selectURL-Operation als Entscheidungsgrundlage zu nutzen. Das Ergebnis selbst kann das Worklet nicht verlassen. Es wirkt sich nur indirekt aus: über den zurückgegebenen URL-Index bei selectURL() oder über Private-Aggregation-Berichte.

Rückgabewert

Typ

Promise<number>

Beschreibung

Ein Promise, das mit der Anzahl der aktuell gespeicherten Einträge (ganze Zahl ≥ 0) für den Ursprung des Worklets erfüllt wird. Das Promise wird abgelehnt, wenn das Worklet-Modul noch nicht hinzugefügt wurde, der Aufruf außerhalb einer registrierten Operation stattfindet oder der Aufrufer keinen Zugriff auf Shared Storage hat (z. B. fehlende Registrierung oder vom Nutzer deaktiviert).

Beispiele

Anzahl der Einträge in einer run()-Operation ermitteln

// shared-storage-worklet.js – läuft im Worklet
class CountEntriesOperation {
  async run(data) {
    const anzahl = await sharedStorage.length();
    // console.log aus Worklets erscheint in den DevTools
    console.log(`Shared Storage enthält ${anzahl} Einträge`);
  }
}

register('count-entries', CountEntriesOperation);

// main.js – im Hauptdokument
const zaehleEintraege = async () => {
  await window.sharedStorage.set('besuch', Date.now().toString());
  await window.sharedStorage.worklet.addModule('shared-storage-worklet.js');
  await window.sharedStorage.run('count-entries');
};

zaehleEintraege();

Shared Storage enthält 1 Einträge

URL-Auswahl abhängig vom Füllstand (selectURL)

// select-worklet.js
class SelectByLengthOperation {
  async run(urls, data) {
    const anzahl = await sharedStorage.length();
    // Neue Nutzer (leerer Speicher) sehen Variante 0, bekannte Variante 1
    return anzahl === 0 ? 0 : 1;
  }
}

register('select-by-length', SelectByLengthOperation);

// main.js
const zeigeAnzeige = async () => {
  await window.sharedStorage.worklet.addModule('select-worklet.js');
  const config = await window.sharedStorage.selectURL(
    'select-by-length',
    [
      { url: 'https://werbung.example/neukunde.html' },
      { url: 'https://werbung.example/stammkunde.html' }
    ],
    { resolveToConfig: true }
  );
  document.querySelector('fencedframe').config = config;
};

zeigeAnzeige();

Speicher aufräumen, wenn zu viele Einträge vorhanden sind

// cleanup-worklet.js
const MAX_EINTRAEGE = 50;

class CleanupOperation {
  async run() {
    const anzahl = await sharedStorage.length();
    if (anzahl > MAX_EINTRAEGE) {
      await sharedStorage.clear();
      console.log(`${anzahl} Einträge gelöscht`);
    }
  }
}

register('cleanup', CleanupOperation);

// main.js
await window.sharedStorage.worklet.addModule('cleanup-worklet.js');
await window.sharedStorage.run('cleanup', { keepAlive: false });

(nur bei mehr als 50 Einträgen) z. B.: 63 Einträge gelöscht

// Wichtig · Fallstricke

Nur im Worklet: window.sharedStorage.length gibt es im Hauptdokument nicht. Ein Aufruf dort löst einen TypeError aus. Lesezugriffe (get(), length(), keys(), entries(), remainingBudget()) sind nur im SharedStorageWorklet möglich.
Asynchron: Die Methode liefert ein Promise zurück. Ohne await erhalten Sie kein number, sondern ein Promise-Objekt.
Kein Datenabfluss: Den Rückgabewert von run() bekommt das Hauptdokument nicht zu sehen. Ergebnisse wirken sich nur über selectURL() (Fenced Frames) oder die Private Aggregation API aus.
Kompatibilität: Die Funktion ist experimentell und nur in Chromium-Browsern verfügbar. Voraussetzung sind eine Privacy-Sandbox-Registrierung (Attestation) des Ursprungs und ein sicherer Kontext (HTTPS). Firefox und Safari unterstützen die API nicht. Google hat angekündigt, mehrere Privacy-Sandbox-APIs einzustellen. Prüfen Sie deshalb den aktuellen Stand, bevor Sie die Methode produktiv einsetzen, und fragen Sie die Unterstützung vorab ab, z. B. mit 'sharedStorage' in window.
Die Zählung gilt nur für den Ursprung, der das Worklet geladen hat (bzw. für den Ursprung aus der Option dataOrigin), und nicht für alle Ursprünge im Browser.

Siehe auch

WorkletSharedStorage.get() WorkletSharedStorage.keys() WorkletSharedStorage.entries() WorkletSharedStorage.remainingBudget() SharedStorage.delete()