SharedStorageSelectURLOperation.run() — Methode · JavaScript-Referenz

Signatur

SharedStorageSelectURLOperation.prototype.run(urls, data)

Beschreibung

run() ist die Methode, die du in einer eigenen Klasse innerhalb eines Shared-Storage-Worklet-Moduls umsetzt. Du registrierst die Klasse mit register(name, Klasse). Ruft die Seite später window.sharedStorage.selectURL(name, urls, options) auf, erzeugt der Browser eine Instanz dieser Klasse und ruft deren run() auf. Die Methode liest mit sharedStorage.get() seitenübergreifend gespeicherte Daten und entscheidet damit, welche der angebotenen URLs angezeigt wird.

Das Ergebnis ist eine Zahl: der Index der gewählten URL im Array urls. Die Seite, die selectURL() aufruft, bekommt diesen Index nie zu sehen. Sie erhält nur eine undurchsichtige URN oder ein FencedFrameConfig-Objekt. Das lässt sich ausschließlich in einem <fencedframe> oder (vorerst) in einem <iframe> darstellen. So können seitenübergreifende Daten die Anzeige beeinflussen, ohne dass sie an die einbettende Seite gelangen. Dieser Schutzmechanismus heißt „Ausgabe-Gate“ (output gate).

Typische Anwendungsfälle sind A/B-Tests über mehrere Websites, Frequency Capping (wie oft ein Nutzer eine Anzeige schon gesehen hat) und die Auswahl von Creatives für bekannte oder neue Nutzer. Weil die gesamte Logik im abgeschotteten Worklet läuft, hat run() keinen Zugriff auf DOM, Netzwerk oder fetch().

Parameter

Name	Typ	Default	Beschreibung
$urls Pflicht	Array<{url: string, reportingMetadata?: Object}>		Die Liste der URL-Objekte, die an `selectURL()` übergeben wurde. Jedes Objekt enthält `url` und optional `reportingMetadata` (Ereignistyp → Reporting-URL).
$data	any	undefined	Beliebige serialisierbare Daten, die der Aufrufer über `options.data` von `selectURL()` mitgibt, z. B. eine Kampagnen-ID.

Rückgabewert

Typ

Promise<number> | number

Beschreibung

Der Index (ab 0) der gewählten URL in urls. Ist der Index ungültig oder wird das Promise abgelehnt, nimmt der Browser die URL mit Index 0 als Standard.

Beispiele

A/B-Test: Worklet-Modul mit run()

// ab-test-worklet.js – läuft im Shared-Storage-Worklet
class SelectURLOperation {
  async run(urls, data) {
    // Nutzer einmalig einer Testgruppe zuweisen (seitenübergreifend stabil)
    const group = await sharedStorage.get('ab-testing-group');

    if (group === undefined) {
      // Beim ersten Mal: Kontrollgruppe
      return 0;
    }

    const index = Number(group);
    return index < urls.length ? index : 0;
  }
}

register('ab-testing', SelectURLOperation);

Aufruf von der Seite und Anzeige im Fenced Frame

// main.js – auf der einbettenden Seite
const runAbTest = async () => {
  // Gruppe setzen, falls noch nicht vorhanden
  await window.sharedStorage.set('ab-testing-group', String(Math.floor(Math.random() * 3)), {
    ignoreIfPresent: true,
  });

  await window.sharedStorage.worklet.addModule('ab-test-worklet.js');

  const config = await window.sharedStorage.selectURL(
    'ab-testing',
    [
      { url: 'https://cdn.example/banner-default.html' },
      { url: 'https://cdn.example/banner-a.html' },
      { url: 'https://cdn.example/banner-b.html' },
    ],
    { resolveToConfig: true }
  );

  const frame = document.createElement('fencedframe');
  frame.config = config; // Index bleibt für die Seite verborgen
  document.body.append(frame);
};

runAbTest();

Frequency Capping mit data-Parameter

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

    if (views >= maxViews) {
      return 1; // Ersatz-Anzeige
    }

    await sharedStorage.set(`views-${campaignId}`, String(views + 1));
    return 0; // Kampagnen-Anzeige
  }
}

register('frequency-cap', FrequencyCapOperation);

// Aufruf auf der Seite:
// await sharedStorage.selectURL('frequency-cap', [
//   { url: 'https://ads.example/kampagne.html' },
//   { url: 'https://ads.example/fallback.html' },
// ], { data: { campaignId: 'sommer24', maxViews: 3 }, resolveToConfig: true });

// Wichtig · Fallstricke

Nicht standardisiert, nur Chromium: Shared Storage gehört zur Privacy Sandbox. Die API ist nur in Chrome bzw. Edge verfügbar und setzt dort eine Registrierung (Enrollment) sowie eine Attestierung voraus. Firefox und Safari lehnen sie ab. Google hat angekündigt, mehrere Privacy-Sandbox-APIs einzustellen. Vor dem Produktiveinsatz den aktuellen Stand prüfen und immer auf die Verfügbarkeit testen: 'sharedStorage' in window.
Budget-Grenze: Jeder Aufruf von selectURL() verbraucht Entropie-Budget pro Site, nämlich log2(Anzahl der URLs) Bits. Ist das Budget erschöpft, wird run() zwar ausgeführt, aber es wird immer die URL mit Index 0 genutzt. Index 0 sollte deshalb eine sinnvolle Standard-URL sein.
Die Anzahl der URLs pro Aufruf ist begrenzt, derzeit auf maximal 8.
Im Worklet gibt es kein DOM, kein fetch() und keinen Zugriff auf console-Ausgaben der Seite. Zum Testen die Chrome DevTools (Application → Shared Storage) verwenden.
Der Name bei register() muss exakt mit dem ersten Argument von selectURL() übereinstimmen. Sonst wird das Promise abgelehnt.
run() sollte schnell ein Ergebnis liefern. Lange oder hängende Operationen können abgebrochen werden.

Siehe auch

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