WorkletSharedStorage.remainingBudget() — Methode · JavaScript-Referenz

Signatur

WorkletSharedStorage.prototype.remainingBudget()

Beschreibung

Die Methode remainingBudget() gehört zur Schnittstelle WorkletSharedStorage der Shared Storage API und ist nur innerhalb eines Shared-Storage-Worklets über das globale Objekt sharedStorage verfügbar. Sie gibt an, wie viel Navigationsbudget dem aktuellen Ursprung noch zur Verfügung steht.

Das Navigationsbudget begrenzt, wie viele Informationen über selectURL() aus dem Shared Storage nach außen gelangen können. Jede Auswahl einer URL, die später in einem Fenced Frame zu einer Navigation auf oberster Ebene führt, verbraucht Bits. Die Menge richtet sich nach der Anzahl der angebotenen URLs: Bei 8 Kandidaten sind das log2(8) = 3 Bits, bei 2 Kandidaten 1 Bit. Das Budget gilt pro Ursprung und wird über ein gleitendes Zeitfenster von 24 Stunden abgerechnet. In Chrome liegt es standardmäßig bei 12 Bits.

Typischerweise fragt man das Budget in einer selectURL-Operation ab. Ist es fast aufgebraucht, gibt man den Index einer neutralen Standard-URL zurück, statt eine personalisierte Auswahl zu treffen. Ist das Budget tatsächlich erschöpft, zeigt der Browser ohnehin die Standard-URL (Index 0) an. Mit einer eigenen Prüfung bleibt das Verhalten aber vorhersagbar.

Rückgabewert

Typ

Promise<number>

Beschreibung

Ein Promise, das mit der verbleibenden Budgetmenge als Zahl (Entropie-Bits, auch Nachkommawerte möglich) für den aktuellen Ursprung erfüllt wird.

Beispiele

Budget in einer selectURL-Operation prüfen (Worklet-Modul)

// ab-test-worklet.js – läuft im Shared-Storage-Worklet
class ABTestOperation {
  async run(urls, data) {
    const budget = await sharedStorage.remainingBudget();
    console.log(`Verbleibendes Budget: ${budget} Bits`);

    // Für 2 URLs wird 1 Bit benötigt – sonst Standard-URL (Index 0)
    if (budget < 1) {
      return 0;
    }

    const group = await sharedStorage.get('ab-gruppe');
    return group === 'B' ? 1 : 0;
  }
}

register('ab-test', ABTestOperation);

Verbleibendes Budget: 12 Bits

Worklet laden und selectURL() von der Seite aus aufrufen

// main.js – im Dokument der Seite
const runAbTest = async () => {
  if (!window.sharedStorage) {
    console.warn('Shared Storage wird nicht unterstützt');
    return;
  }

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

  // Gruppe einmalig festlegen, falls noch nicht vorhanden
  await window.sharedStorage.set('ab-gruppe', Math.random() < 0.5 ? 'A' : 'B', {
    ignoreIfPresent: true
  });

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

  document.querySelector('fencedframe').config = config;
};

runAbTest();

Auswahl abhängig vom Budget abstufen

// creative-worklet.js
class CreativeSelection {
  async run(urls) {
    const budget = await sharedStorage.remainingBudget();
    const neededBits = Math.log2(urls.length);

    if (budget < neededBits) {
      // Nicht genug Budget für diese Anzahl von URLs
      return 0;
    }

    const views = Number(await sharedStorage.get('views')) || 0;
    await sharedStorage.set('views', String(views + 1));
    return Math.min(views, urls.length - 1);
  }
}

register('creative-selection', CreativeSelection);

// Wichtig · Fallstricke

Nur im Worklet: remainingBudget() gibt es ausschließlich auf WorkletSharedStorage (dem globalen sharedStorage im Worklet), nicht auf window.sharedStorage.
Kompatibilität: Die Methode ist experimentell und nur in Chromium-Browsern verfügbar, die die Privacy Sandbox unterstützen. Voraussetzungen sind eine Anmeldung (Enrollment) bei der Privacy Sandbox und ein sicherer Kontext (HTTPS). Firefox und Safari unterstützen die API nicht. Google hat angekündigt, mehrere Privacy-Sandbox-APIs zurückzuziehen. Vor dem Einsatz im Produktivbetrieb sollten Sie daher den aktuellen Status prüfen.
Budget ist nicht exakt vorhersehbar: Es wird erst verbraucht, wenn der Fenced Frame tatsächlich eine Navigation auf oberster Ebene auslöst, etwa durch einen Klick. Außerdem erholt es sich schrittweise über das 24-Stunden-Fenster. Der Wert ist deshalb eine Momentaufnahme.
Pro Seitenaufruf gibt es zusätzlich eigene Budgets (Aufrufe von selectURL() und Bits pro Seite), die remainingBudget() nicht abbildet.
Im Worklet ist console.log nur in den DevTools des Worklets sichtbar. Daten lassen sich aus dem Worklet nicht direkt an die Seite zurückgeben.

Siehe auch

WorkletSharedStorage.entries() WorkletSharedStorage.get() WorkletSharedStorage.length() WorkletSharedStorage.keys() SharedStorage.append()