SharedStorageRunOperation.run() — Methode · JavaScript-Referenz

Signatur

SharedStorageRunOperation.prototype.run(data)

Beschreibung

SharedStorageRunOperation ist keine Klasse, die man direkt instanziiert. Es ist eine Vorgabe für die Struktur: Wer im Shared-Storage-Worklet eine Operation für das Run-Output-Gate schreibt, legt eine eigene Klasse an. Diese braucht eine (meist asynchrone) Methode run(data) und wird mit register(name, Klasse) angemeldet. Die Seite ruft sie danach über window.sharedStorage.run(name, options) auf.

Im Worklet hat run() Lesezugriff auf die seitenübergreifenden Shared-Storage-Daten (sharedStorage.get(), keys(), entries() usw.). Die Methode kann aber keine Daten an die aufrufende Seite zurückgeben, das ist gerade der Sinn des „Output Gate“. Ergebnisse verlassen das Worklet nur auf datenschutzfreundlichen Wegen, vor allem über die Private Aggregation API (privateAggregation.contributeToHistogram()). Diese liefert zusammengefasste, verrauschte Berichte.

Typische Einsatzfälle sind Messungen über mehrere Websites hinweg, ohne Drittanbieter-Cookies: Reichweite eindeutiger Nutzer, Frequenz-Begrenzung, demografische Auswertungen oder Berichte zur Interaktion mit Inhalten. Wenn stattdessen eine URL aus mehreren Kandidaten ausgewählt werden soll, nimmt man eine SharedStorageSelectURLOperation mit selectURL().

Parameter

Name	Typ	Default	Beschreibung
$data	any	undefined	Beliebige Daten, die der Aufrufer über die Option `data` von `sharedStorage.run(name, { data })` mitgibt. Sie werden strukturiert geklont, wie bei `structuredClone`.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das erfüllt wird, wenn die Operation fertig ist. Ein Rückgabewert wird ignoriert und kommt nicht beim Aufrufer an. Auch window.sharedStorage.run() erfüllt sein Promise nur mit undefined.

Beispiele

Run-Operation im Worklet definieren und registrieren

// reach-worklet.js – läuft im SharedStorageWorkletGlobalScope
class ReachMeasurementOperation {
  async run(data) {
    const { contentId } = data;

    // Pro Browser nur einmal zählen
    const key = `reach-reported-${contentId}`;
    const alreadyReported = await sharedStorage.get(key);
    if (alreadyReported) return;

    // Aggregierten, verrauschten Bericht erzeugen
    privateAggregation.contributeToHistogram({
      bucket: BigInt(contentId),
      value: 1
    });

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

register('reach-measurement', ReachMeasurementOperation);

Operation von der Seite aus aufrufen

// main.js – im Dokument (z. B. im Skript eines Drittanbieters)
const measureReach = async (contentId) => {
  if (!('sharedStorage' in window)) {
    console.log('Shared Storage wird nicht unterstützt');
    return;
  }

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

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

  console.log('Ergebnis:', result);
};

measureReach(1234);

Ergebnis: undefined

Frequenz zählen mit keepAlive für mehrere Aufrufe

// frequency-worklet.js
class FrequencyCountOperation {
  async run({ campaignId }) {
    const key = `views-${campaignId}`;
    const count = Number(await sharedStorage.get(key) ?? 0) + 1;

    privateAggregation.contributeToHistogram({
      bucket: BigInt(Math.min(count, 10)), // Frequenz-Bucket 1–10
      value: 1
    });
  }
}
register('frequency-count', FrequencyCountOperation);

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

// Wichtig · Fallstricke

Experimentell und nur in Chromium: Firefox und Safari unterstützen Shared Storage nicht. Google hat angekündigt, mehrere Privacy-Sandbox-APIs wieder einzustellen. Vor dem Einsatz sollte man den aktuellen Status prüfen und immer eine Merkmalserkennung ('sharedStorage' in window) einbauen.
Anmeldung nötig: In Chrome müssen Aufrufer für die Privacy Sandbox registriert und bestätigt sein (Enrollment/Attestation), sonst schlagen die Aufrufe fehl. Nutzer können die API außerdem in den Einstellungen abschalten.
Kein Rückgabewert: Was run() zurückgibt, wird verworfen. Daten gelangen nur über die Private Aggregation API nach außen, und dort nur als zusammengefasste, verrauschte Werte mit Beitragsgrenzen (Budget).
Der Name aus register() muss je Worklet eindeutig sein. Ein doppelter Name löst einen Fehler aus.
Ohne keepAlive: true wird das Worklet nach der ersten Operation beendet. Weitere run()- oder selectURL()-Aufrufe schlagen dann fehl.
Das Worklet hat keinen Zugriff auf DOM, fetch oder die Seite. sharedStorage.set() ist in der Seite und im Worklet verfügbar. Lesen geht nur im Worklet.

Siehe auch

SharedStorageSelectURLOperation.run() SharedStorage.append() SharedStorage.clear() SharedStorage.delete() SharedStorage.set()