WindowSharedStorage.run() — Methode · JavaScript-Referenz

Signatur

WindowSharedStorage.prototype.run(name, options)

Beschreibung

run() gehört zur Shared Storage API aus Googles Privacy Sandbox. Die Methode ruft eine Operation auf, die vorher in einem Worklet-Modul mit register(name, OperationClass) registriert wurde. Das Modul lädt man mit window.sharedStorage.worklet.addModule(). Die Operation läuft abgeschottet im SharedStorageWorklet. Dort kann sie den Shared Storage des aktuellen Ursprungs lesen und schreiben, und zwar über alle Websites hinweg, in die dieser Ursprung eingebettet ist.

Anders als bei selectURL() gibt es bei run() kein Ergebnis, das an die Seite zurückgeht. Die Methode ist für Aufgaben gedacht, bei denen Daten nur im Worklet verarbeitet werden und die Seite nie erreichen, zum Beispiel:

Reichweitenmessung (Unique Reach) mit der Private Aggregation API,
Frequenzbegrenzung oder A/B-Zuordnung, deren Zustand im Shared Storage gespeichert wird,
Pflege und Bereinigung gespeicherter Einträge (set, append, delete).

Das zurückgegebene Promise erfüllt sich, sobald die Operation zur Ausführung angenommen wurde. Ob die Operation im Worklet erfolgreich war, meldet es nicht. So soll verhindert werden, dass über Fehlermeldungen Informationen aus dem Speicher nach außen gelangen.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Name der Operation, wie er im Worklet mit `register(name, Klasse)` registriert wurde.
$options	object	{}	Optionales Konfigurationsobjekt.
$options.data	any (strukturiert klonbar)	undefined	Daten, die an `run(data)` der Operationsklasse übergeben werden. Sie müssen strukturiert klonbar sein.
$options.keepAlive	boolean	false	Bei `true` bleibt das Worklet nach der Operation bestehen und kann weitere `run()`- oder `selectURL()`-Aufrufe annehmen. Standardmäßig wird es nach einer Operation beendet.
$options.privateAggregationConfig	object		Einstellungen für die Private Aggregation API, z. B. `contextId`, `aggregationCoordinatorOrigin` oder `filteringIdMaxBytes`.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das sich mit undefined erfüllt, sobald die Operation angenommen wurde. Es wird abgelehnt (z. B. mit TypeError oder DOMException), wenn kein Modul geladen ist, das Worklet schon beendet wurde, der Ursprung nicht für die Privacy Sandbox registriert ist oder die Daten nicht klonbar sind.

Beispiele

Worklet-Modul: Operation registrieren (reach-worklet.js)

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

    // Nur beim ersten Kontakt zählen (Unique Reach)
    if (await sharedStorage.get(key) === 'true') return;

    privateAggregation.contributeToHistogram({
      bucket: BigInt(data.contentId),
      value: 1,
    });

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

register('reach-measurement', ReachMeasurementOperation);

Operation aus der Seite starten

const measureReach = async (contentId) => {
  if (!window.sharedStorage) {
    console.log('Shared Storage wird nicht unterstützt');
    return;
  }
  try {
    await window.sharedStorage.worklet.addModule('/reach-worklet.js');
    await window.sharedStorage.run('reach-measurement', {
      data: { contentId },
    });
    console.log('Messung angestoßen');
  } catch (err) {
    console.error('run() fehlgeschlagen:', err.name, err.message);
  }
};

measureReach(1234);

Messung angestoßen

Mehrere Operationen mit keepAlive

// worklet.js: register('increment', …) und register('cleanup', …)
await window.sharedStorage.worklet.addModule('/worklet.js');

// Worklet bleibt nach dieser Operation bestehen
await window.sharedStorage.run('increment', {
  data: { counter: 'views' },
  keepAlive: true,
});

// Letzte Operation ohne keepAlive – danach wird das Worklet beendet
await window.sharedStorage.run('cleanup');
console.log('Beide Operationen angestoßen');

Beide Operationen angestoßen

Mit Private-Aggregation-Konfiguration

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

await window.sharedStorage.run('reach-measurement', {
  data: { contentId: 42 },
  privateAggregationConfig: {
    contextId: 'kampagne-2024-q3',
  },
});

// Wichtig · Fallstricke

Experimentell und nur in Chromium: Die API gibt es nur in Chrome und Edge ab etwa Version 115. Firefox und Safari unterstützen sie nicht und wollen das auch nicht. Prüfen Sie vorher mit if (window.sharedStorage). Google hat angekündigt, mehrere Privacy-Sandbox-Technologien auslaufen zu lassen. Prüfen Sie daher vor dem Einsatz in Produktion den aktuellen Stand.
Registrierung erforderlich: Aufrufe werden abgelehnt, wenn der Ursprung nicht für die Privacy Sandbox registriert ist (Enrollment und Attestierung). Für lokale Tests gibt es entsprechende Flags in chrome://flags.
Kein Rückgabewert und keine Fehlermeldung aus dem Worklet: Das Promise sagt nichts darüber, ob die Operation erfolgreich war. Zur Fehlersuche nutzen Sie die DevTools (Application → Shared Storage).
Worklet nur einmal nutzbar: Ohne keepAlive: true wird das Worklet nach der ersten Operation beendet. Weitere run()-Aufrufe schlagen dann fehl. addModule() lässt sich pro Worklet nur einmal aufrufen.
Ursprung: Das Worklet arbeitet mit dem Shared Storage des Ursprungs, von dem das Modul stammt. Bei eingebetteten Drittanbieter-Skripten ist das oft nicht der Ursprung der aufrufenden Seite. Mit sharedStorage.createWorklet(url) lässt sich ein Worklet für einen anderen Ursprung erzeugen.
Nutzer können Shared Storage über die Datenschutz-Einstellungen abschalten. Planen Sie deshalb immer einen Ersatzweg ein.

Siehe auch

WindowSharedStorage.selectURL() SharedStorage.set() WorkletSharedStorage.get() WorkletSharedStorage.keys() SharedStorage.append() FencedFrameConfig.setSharedStorageContext() new SharedWorker()