WindowSharedStorage.selectURL() — Methode · JavaScript-Referenz

Signatur

WindowSharedStorage.prototype.selectURL(name, urls, options)

Beschreibung

selectURL() gehört zur Shared Storage API der Privacy Sandbox und wird über window.sharedStorage.selectURL() aufgerufen. Die Methode startet eine Operation, die vorher in einem Worklet-Modul mit register(name, Klasse) registriert wurde. Die Methode run(urls, data) dieser Klasse hat Lesezugriff auf den ursprungsübergreifend gespeicherten Shared Storage (sharedStorage.get()) und gibt den Index einer URL aus der übergebenen Liste zurück.

Das Besondere: Die ausgewählte URL wird der aufrufenden Seite nicht verraten. Stattdessen bekommst du eine undurchsichtige URN (urn:uuid:…) oder mit resolveToConfig: true ein FencedFrameConfig-Objekt zurück. Beides kannst du nur in einem <fencedframe> (URN übergangsweise auch als src eines <iframe>) anzeigen. So lassen sich ursprungsübergreifende Daten für Entscheidungen nutzen, ohne dass Nutzer seitenübergreifend verfolgt werden können.

Typische Einsatzfälle:

A/B-Tests über mehrere Websites hinweg
Rotation von Werbemitteln (Creative Rotation)
Frequency Capping, also die Begrenzung, wie oft jemand eine Anzeige sieht
die Unterscheidung zwischen bekannten und neuen Nutzern

Vorher muss das Worklet-Modul mit window.sharedStorage.worklet.addModule() geladen sein. Jede Auswahl verbraucht bei der Navigation des Fenced Frames ein Entropie-Budget von log2(Anzahl URLs) Bits. Dieses Budget ist pro Website und Zeitfenster begrenzt. Ist es aufgebraucht, wird immer die erste URL (Index 0) geliefert.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Name der Operation, der im Worklet mit `register(name, Klasse)` registriert wurde.
$urls Pflicht	Array<{url: string, reportingMetadata?: Object<string, string>}>		Liste mit 1 bis 8 Kandidaten-Objekten. `url` ist die mögliche Ziel-URL. Das optionale `reportingMetadata` ordnet Ereignistypen Reporting-URLs zu, die später aus dem Fenced Frame mit `window.fence.reportEvent()` ausgelöst werden.
$options	Object	{}	Optionale Einstellungen: `data`: beliebige serialisierbare Daten, die als zweites Argument an `run()` gehen. `resolveToConfig` (`boolean`, Standard `false`): Bei `true` wird ein `FencedFrameConfig` statt einer URN geliefert. `keepAlive` (`boolean`, Standard `false`): Bei `true` bleibt das Worklet nach der Operation für weitere Aufrufe bestehen. `privateAggregationConfig`: Einstellungen für die Private Aggregation API, z. B. `contextId` oder `aggregationCoordinatorOrigin`. `savedQuery` (`string`, neuere Chromium-Versionen): Name, unter dem das Ergebnis pro Seitenaufruf zwischengespeichert und wiederverwendet wird.

Rückgabewert

Typ

Promise<string | FencedFrameConfig>

Beschreibung

Ein Promise, das sich mit einer undurchsichtigen URN (urn:uuid:…) oder, bei resolveToConfig: true, mit einem FencedFrameConfig erfüllt. Welche URL gewählt wurde, erfährt die aufrufende Seite nicht. Das Promise wird zurückgewiesen, wenn die API nicht verfügbar ist, das Worklet fehlt, die Operation unbekannt ist oder die URL-Liste ungültig ist.

Beispiele

Worklet-Modul: A/B-Test-Operation registrieren

// ab-worklet.js – läuft im SharedStorageWorkletGlobalScope
class SelectABGroup {
  async run(urls, data) {
    // Gruppe wurde zuvor per sharedStorage.set() ursprungsübergreifend gespeichert
    const group = await sharedStorage.get('ab-group');
    if (group === 'B') return 1;
    return 0; // Standard: Gruppe A
  }
}

register('ab-testing', SelectABGroup);

Hauptseite: Variante wählen und im Fenced Frame anzeigen

const showExperiment = async () => {
  if (!('sharedStorage' in window)) {
    console.log('Shared Storage nicht verfügbar');
    return;
  }

  // Gruppe einmalig zufällig festlegen (ignoreIfPresent behält eine vorhandene Gruppe)
  await window.sharedStorage.set('ab-group', Math.random() < 0.5 ? 'A' : 'B', {
    ignoreIfPresent: true,
  });

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

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

  const frame = document.createElement('fencedframe');
  frame.config = config;
  document.body.append(frame);
  console.log(config instanceof FencedFrameConfig);
};

showExperiment();

true

Creative Rotation mit Daten, Reporting und URN im iframe

// Im Worklet (rotation-worklet.js):
// class Rotate {
//   async run(urls, { campaignId }) {
//     const count = Number(await sharedStorage.get(`seen-${campaignId}`) ?? 0);
//     return count % urls.length;
//   }
// }
// register('creative-rotation', Rotate);

const loadAd = async () => {
  await window.sharedStorage.worklet.addModule('/rotation-worklet.js');

  const urn = await window.sharedStorage.selectURL(
    'creative-rotation',
    [
      { url: 'https://ads.example/creative-1.html',
        reportingMetadata: { click: 'https://ads.example/report?c=1' } },
      { url: 'https://ads.example/creative-2.html',
        reportingMetadata: { click: 'https://ads.example/report?c=2' } },
      { url: 'https://ads.example/creative-3.html' },
    ],
    { data: { campaignId: 'summer24' } }
  );

  console.log(urn.startsWith('urn:uuid:'));
  // Übergangsweise auch im iframe darstellbar
  document.querySelector('#ad-slot').src = urn;
};

loadAd();

true

Siehe auch

WindowSharedStorage.run() SharedStorage.delete() SharedStorage.clear() SharedStorage.set() WorkletSharedStorage.get() SharedStorageRunOperation.run() Window.requestResize()