SharedStorageRunOperation — Schnittstelle · JavaScript-Referenz

Signatur

interface SharedStorageRunOperation extends SharedStorageOperation

Beschreibung

Das Interface SharedStorageRunOperation gehört zur experimentellen Shared Storage API aus der Privacy Sandbox. Es beschreibt eine Operation, die in einem SharedStorageWorklet läuft und dort ohne Einschränkung auf den seitenübergreifenden Shared Storage zugreifen darf. Die gelesenen Daten dürfen den Worklet aber nicht direkt verlassen. Ergebnisse gehen nur über ein Ausgabe-Gate nach außen, bei Run-Operationen meist über die Private Aggregation API, zum Beispiel mit privateAggregation.contributeToHistogram().

SharedStorageRunOperation ist kein Konstruktor, den du selbst aufrufst. Stattdessen schreibst du im Worklet-Modul eine eigene Klasse mit einer asynchronen Methode run(data) und meldest sie mit register(name, Klasse) an. Im Hauptdokument lädst du das Modul mit window.sharedStorage.worklet.addModule() und startest die Operation mit window.sharedStorage.run(name, options).

Typische Anwendungsfälle sind Messungen über mehrere Websites hinweg, etwa Reichweite eindeutiger Nutzer, Frequenzbegrenzung (Frequency Capping) oder Konversionszuordnung, und zwar ohne Drittanbieter-Cookies. Wenn die Operation stattdessen eine URL aus einer Liste auswählen soll, ist SharedStorageSelectURLOperation das Gegenstück.

Parameter

Name	Typ	Default	Beschreibung
$data	any	undefined	Beliebige serialisierbare Daten, die als Option `data` an `window.sharedStorage.run()` übergeben und an die `run()`-Methode der registrierten Klasse weitergereicht werden.

Beispiele

Run-Operation im Worklet-Modul registrieren (reach-worklet.js)

// reach-worklet.js – läuft im SharedStorageWorklet
const SCALE_FACTOR = 65536;

// Wandelt eine Inhalts-ID in einen BigInt-Bucket um
const convertContentIdToBucket = (contentId) => BigInt(contentId);

class ReachMeasurementOperation {
  async run(data) {
    const { contentId } = data;
    const key = `has-reported-content-${contentId}`;

    // Pro Browser nur einmal melden
    if (await sharedStorage.get(key) === 'true') {
      console.log('Bereits gemeldet – nichts zu tun.');
      return;
    }

    // Ausgabe-Gate: Private Aggregation
    privateAggregation.contributeToHistogram({
      bucket: convertContentIdToBucket(contentId),
      value: 1 * SCALE_FACTOR,
    });

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

register('reach-measurement', ReachMeasurementOperation);

Operation aus dem Hauptdokument starten

// main.js – im Kontext der Seite (bzw. eines eingebetteten iframes)
const measureReach = async (contentId) => {
  if (!('sharedStorage' in window)) {
    console.warn('Shared Storage wird nicht unterstützt.');
    return;
  }

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

  await window.sharedStorage.run('reach-measurement', {
    data: { contentId: 1234 },
  });

  console.log('Run-Operation gestartet.');
};

measureReach(1234);

Run-Operation gestartet.

Frequenzbegrenzung mit Zähler im Shared Storage

// frequency-worklet.js
class FrequencyCapOperation {
  async run({ campaignId, maxViews }) {
    const key = `views-${campaignId}`;
    const views = Number(await sharedStorage.get(key) ?? 0);

    if (views >= maxViews) return; // Limit erreicht

    await sharedStorage.set(key, String(views + 1));
  }
}

register('frequency-cap', FrequencyCapOperation);

// main.js
// await window.sharedStorage.worklet.addModule('/frequency-worklet.js');
// await window.sharedStorage.run('frequency-cap', {
//   data: { campaignId: 'sommer24', maxViews: 3 },
//   keepAlive: true, // Worklet für weitere Operationen offen halten
// });

// Wichtig · Fallstricke

Kompatibilität: Die Schnittstelle ist experimentell und steht nur in Chromium-Browsern (Chrome, Edge) als Teil der Privacy Sandbox zur Verfügung. Firefox und Safari unterstützen sie nicht. Google hat angekündigt, mehrere Privacy-Sandbox-APIs wieder einzustellen. Prüfe deshalb vor dem Einsatz den aktuellen Status und frage die Funktion mit 'sharedStorage' in window ab.

Für den Einsatz muss die aufrufende Origin für die Privacy Sandbox registriert und attestiert sein. Ohne diese Attestierung schlägt der Aufruf fehl.
Der Rückgabewert von run() erreicht die Seite nicht. Daten gelangen nur über Ausgabe-Gates aus dem Worklet, bei Run-Operationen über Private Aggregation. Damit soll seitenübergreifendes Tracking verhindert werden.
Standardmäßig ist nach einer Operation Schluss: Ohne keepAlive: true wird der Worklet beendet, und weitere Aufrufe von run() oder selectURL() auf demselben Worklet schlagen fehl.
Im Worklet gibt es kein DOM, kein fetch() und keinen Netzwerkzugriff. Verfügbar sind nur sharedStorage, privateAggregation und register().
Der Name bei register() darf pro Worklet nur einmal vergeben werden. Wird er doppelt registriert, wird ein Fehler ausgelöst.

Siehe auch

SharedStorageOperation SharedStorageSelectURLOperation SharedStorageWorklet SharedStorage ScreenOrientation