SharedStorageOperation — Schnittstelle · JavaScript-Referenz

Signatur

interface SharedStorageOperation

Beschreibung

SharedStorageOperation ist die gemeinsame Basis für alle Operationen, die in einem Shared-Storage-Worklet laufen. Die API ist darauf ausgelegt, websiteübergreifende Daten ohne Drittanbieter-Cookies zu speichern. Diese Daten lassen sich nur innerhalb des abgeschotteten Worklets lesen. Nach außen gelangen Ergebnisse nur über sogenannte Output Gates, also kontrollierte Ausgabekanäle wie die Private Aggregation API oder eine URL-Auswahl, die in einem Fenced Frame angezeigt wird.

Konkret gibt es zwei abgeleitete Operationstypen:

SharedStorageRunOperation: Eine Klasse mit einer asynchronen Methode run(data). Sie wird von der Seite über window.sharedStorage.run() gestartet, zum Beispiel für Reichweitenmessung mit der Private Aggregation API.
SharedStorageSelectURLOperation: Eine Klasse mit einer asynchronen Methode run(urls, data), die den Index einer URL zurückgibt. Sie wird über window.sharedStorage.selectURL() gestartet, zum Beispiel für A/B-Tests oder Creative-Rotation.

Das Interface hat keinen öffentlichen Konstruktor, den man auf der Seite aufrufen könnte. Stattdessen schreibt man im Worklet-Modul eine eigene Klasse, die die passende run()-Methode bereitstellt. Diese Klasse registriert man mit register(name, operationClass) im SharedStorageWorkletGlobalScope. Der Browser erzeugt die Instanzen selbst, sobald die Seite die Operation über ihren Namen aufruft.

Parameter

Name	Typ	Default	Beschreibung
$data	any	undefined	Beliebige serialisierbare Daten, die die Seite über die Option `data` von `sharedStorage.run()` bzw. `selectURL()` an die `run()`-Methode der Operation übergibt.
$urls	Array<string>		Nur bei `SharedStorageSelectURLOperation`: die URLs aus dem `urlConfigs`-Array von `selectURL()`. Es sind höchstens 8 Einträge erlaubt. Die Operation muss einen gültigen Index aus diesem Array zurückgeben.

Rückgabewert

Typ

Promise<void> | Promise<number>

Beschreibung

run() einer Run-Operation liefert ein Promise<void>. Die Ergebnisse gehen nur über Output Gates wie privateAggregation nach außen. Eine Select-URL-Operation liefert ein Promise<number> mit dem Index der gewählten URL.

Beispiele

Run-Operation im Worklet registrieren (Reichweitenmessung)

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

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 – keine Aktion');
      return;
    }

    // Ausgabe nur über das Output Gate Private Aggregation
    privateAggregation.contributeToHistogram({
      bucket: convertContentIdToBucket(contentId),
      value: 1 * SCALE_FACTOR,
    });

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

register('reach-measurement', ReachMeasurementOperation);

Run-Operation von der Seite aus starten

// main.js – im Dokument der einbettenden Seite
const measureReach = async () => {
  if (!window.sharedStorage) {
    console.warn('Shared Storage wird nicht unterstützt');
    return;
  }
  await window.sharedStorage.worklet.addModule('reach-measurement-worklet.js');
  await window.sharedStorage.run('reach-measurement', {
    data: { contentId: '1234' },
  });
  console.log('Messung angestoßen');
};

measureReach();

Messung angestoßen

Select-URL-Operation für einen A/B-Test mit Fenced Frame

// ab-testing-worklet.js
class SelectURLOperation {
  async run(urls, data) {
    const group = await sharedStorage.get('ab-testing-group');
    const index = Number.parseInt(group ?? '0', 10);
    // Index muss innerhalb von urls liegen
    return index >= 0 && index < urls.length ? index : 0;
  }
}

register('ab-testing', SelectURLOperation);

// main.js
const runAbTest = async () => {
  // Gruppe nur setzen, falls noch nicht vorhanden
  await window.sharedStorage.set('ab-testing-group', String(Math.round(Math.random())), {
    ignoreIfPresent: true,
  });
  await window.sharedStorage.worklet.addModule('ab-testing-worklet.js');

  const fencedFrameConfig = await window.sharedStorage.selectURL(
    'ab-testing',
    [{ url: 'https://example.com/variante-a' }, { url: 'https://example.com/variante-b' }],
    { resolveToConfig: true }
  );

  document.getElementById('content-slot').config = fencedFrameConfig;
};

runAbTest();

// Wichtig · Fallstricke

Kompatibilität und Status: Die API ist experimentell und nur in Chromium-Browsern im Rahmen der Privacy Sandbox verfügbar. Firefox und Safari unterstützen sie nicht. Google hat angekündigt, mehrere Privacy-Sandbox-APIs einzustellen. Deshalb vor der Nutzung immer mit 'sharedStorage' in window prüfen, ob die API vorhanden ist, und die aktuelle Chrome-Dokumentation beachten.
Registrierung und Attestierung: Aufrufende Ursprünge müssen für die Privacy Sandbox registriert und attestiert sein. Sonst schlagen run() und selectURL() fehl.
Keine direkte Rückgabe an die Seite: Aus einer Run-Operation können keine Daten an die aufrufende Seite zurückfließen. console.log im Worklet dient nur der Fehlersuche. Ergebnisse gehen ausschließlich über Output Gates nach außen.
Grenzen bei selectURL: Es sind höchstens 8 URLs erlaubt. Pro Aufruf wird ein Budget an Informationsbits verbraucht, und dieses Budget ist pro Website und Zeitraum begrenzt. Das Ergebnis ist ein undurchsichtiges URN bzw. eine FencedFrameConfig, die sich nur in einem <fencedframe> (oder übergangsweise einem <iframe>) anzeigen lässt.
Namen eindeutig halten: Wird derselbe Operationsname zweimal mit register() vergeben, löst das einen Fehler aus. Die registrierte Klasse muss eine run()-Methode besitzen.

Siehe auch

SharedStorageRunOperation SharedStorageWorklet SharedStorage SharedStorageSelectURLOperation ScreenOrientation