SharedStorageWorkletGlobalScope.register() — Methode · JavaScript-Referenz

Signatur

SharedStorageWorkletGlobalScope.register(name, operationCtor)

Beschreibung

register() steht nur im globalen Gültigkeitsbereich eines Shared-Storage-Worklets zur Verfügung, also in dem Modul, das die Seite über window.sharedStorage.worklet.addModule() lädt. Die Methode verknüpft einen frei wählbaren Operationsnamen mit einer Klasse. Diese Klasse muss eine Methode run() haben, die der Browser beim Aufruf der Operation ausführt.

Es gibt zwei Arten von Operationen:

Run-Operationen werden aus der Seite mit window.sharedStorage.run(name, { data }) gestartet. Ihre Methode run(data) liest oder schreibt den Shared Storage, zum Beispiel für Reichweitenmessung oder das Weiterleiten an die Private Aggregation API.
URL-Auswahl-Operationen werden mit window.sharedStorage.selectURL(name, urls, { data }) gestartet. Ihre Methode run(urls, data) gibt den Index der gewählten URL zurück. Der Browser zeigt diese URL dann in einem Fenced Frame an, ohne dass die Seite erfährt, welche URL gewählt wurde.

Man verwendet register() meist direkt am Ende des Worklet-Moduls, einmal pro Operation. Das Worklet kann Daten aus dem Shared Storage lesen (sharedStorage.get()). Die Ergebnisse gelangen aber nur über streng begrenzte Kanäle nach außen, nämlich über Fenced Frames und Private Aggregation. Das ist der Kern des Datenschutzmodells.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Name der Operation. Unter diesem Namen ruft die Seite sie mit `sharedStorage.run()` bzw. `sharedStorage.selectURL()` auf. Der Name darf nicht leer sein und muss innerhalb des Worklets eindeutig sein.
$operationCtor Pflicht	class (Function)		Klasse (Konstruktor), die die Operation umsetzt. Ihr Prototyp muss eine Methode `run()` haben, meist als `async`. Bei Run-Operationen hat sie die Form `run(data)`, bei URL-Auswahl-Operationen die Form `run(urls, data)` mit einer Indexzahl als Rückgabewert.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Stimmt eine Bedingung nicht, wird ein TypeError ausgelöst: leerer Name, bereits vergebener Name, kein Konstruktor übergeben oder keine Methode run() vorhanden.

Beispiele

Run-Operation registrieren (Worklet-Modul)

// reach-worklet.js – läuft im SharedStorageWorkletGlobalScope
class ReachMeasurement {
  async run(data) {
    const key = `seen:${data.campaignId}`;
    // Nur beim ersten Kontakt zählen
    const alreadySeen = await sharedStorage.get(key);
    if (alreadySeen) return;

    await sharedStorage.set(key, '1');
    privateAggregation.contributeToHistogram({
      bucket: BigInt(data.campaignId),
      value: 1,
    });
  }
}

register('reach-measurement', ReachMeasurement);

Registrierte Operation von der Seite aus aufrufen

// Hauptseite (z. B. im eingebetteten Werbe-Skript)
const measureReach = async () => {
  if (!('sharedStorage' in window)) {
    console.log('Shared Storage wird nicht unterstützt');
    return;
  }
  await window.sharedStorage.worklet.addModule('/reach-worklet.js');
  await window.sharedStorage.run('reach-measurement', {
    data: { campaignId: 1234 },
  });
  console.log('Messung angestoßen');
};

measureReach();

Messung angestoßen

URL-Auswahl-Operation für A/B-Tests

// ab-worklet.js
class SelectExperimentGroup {
  async run(urls, data) {
    // Gruppe wird einmalig pro Browser festgelegt und gespeichert
    let group = await sharedStorage.get('ab-group');
    if (group === undefined) {
      group = String(Math.floor(Math.random() * urls.length));
      await sharedStorage.set('ab-group', group);
    }
    return Number(group); // Index in das urls-Array
  }
}
register('ab-testing', SelectExperimentGroup);

// --- Hauptseite ---
// await window.sharedStorage.worklet.addModule('/ab-worklet.js');
// const config = await window.sharedStorage.selectURL(
//   'ab-testing',
//   [{ url: '/banner-a.html' }, { url: '/banner-b.html' }],
//   { resolveToConfig: true }
// );
// document.querySelector('fencedframe').config = config;

Fehler bei doppelter Registrierung

// Im Worklet-Modul
class Op { async run() {} }

register('my-op', Op);
try {
  register('my-op', Op); // Name bereits vergeben
} catch (err) {
  console.log(err.name);
}

TypeError

// Wichtig · Fallstricke

Experimentell und nur in Chromium: Die Methode gehört zur Shared Storage API der Privacy Sandbox. Firefox und Safari unterstützen sie nicht. Google hat angekündigt, mehrere Privacy-Sandbox-Technologien einzustellen. Prüfe daher vor dem Einsatz den aktuellen Stand und frage die API immer mit 'sharedStorage' in window ab.
Nur im Worklet verfügbar: register() ist eine globale Funktion im SharedStorageWorkletGlobalScope. Im normalen Seitenkontext oder in einem Web Worker gibt es sie nicht.
Anmeldung nötig: In Chrome muss der Aufrufer-Origin für die Privacy Sandbox angemeldet und bestätigt sein (Enrollment/Attestation). Sonst schlagen addModule(), run() und selectURL() fehl.
Die Klasse muss eine Methode run() auf dem Prototyp haben. Eine reine Funktion oder ein Objekt ohne run() löst einen TypeError aus. Auch ein Name darf nur einmal registriert werden.
Bei selectURL()-Operationen muss run() einen gültigen Index in das urls-Array zurückgeben. Ungültige Werte führen dazu, dass die Standard-URL (Index 0) verwendet wird. Die Anzahl der URLs ist begrenzt (derzeit 8). Außerdem verbraucht jeder Aufruf Datenschutzbudget.
Werte aus dem Shared Storage lassen sich aus dem Worklet nicht direkt an die Seite zurückgeben. run()-Operationen liefern der Seite kein Ergebnis.

Siehe auch

SharedStorageSelectURLOperation.run() SharedWorkerGlobalScope.close() PaintWorkletGlobalScope.registerPaint() DedicatedWorkerGlobalScope.close() AudioWorkletGlobalScope.registerProcessor()