Navigator.deprecatedReplaceInURN() — Methode · JavaScript-Referenz

Signatur

Navigator.prototype.deprecatedReplaceInURN(urnOrConfig, replacements)

Beschreibung

Die Methode deprecatedReplaceInURN() gehört zur Protected Audience API (früher FLEDGE) der Privacy Sandbox. Eine Werbeauktion mit navigator.runAdAuction() liefert als Ergebnis keine lesbare Anzeigen-URL. Stattdessen gibt sie eine undurchsichtige URN (z. B. urn:uuid:…) oder ein FencedFrameConfig-Objekt zurück. So kann die einbettende Seite nicht erkennen, welche Anzeige gewonnen hat.

Viele Werbe-Server erwarten aber zusätzliche Angaben in der Anzeigen-URL, etwa die Größe der Werbefläche oder eine Kampagnen-ID. Genau dafür ist deprecatedReplaceInURN() da: Die Seite übergibt ein Objekt mit Ersetzungen, und der Browser setzt die Werte intern in die verborgene URL ein. Die eigentliche URL bleibt dabei weiterhin unsichtbar. Als Platzhalter gelten nur Schlüssel im Format ${…} oder %%…%%.

Rufen Sie die Methode nach der Auktion und vor dem Laden der URN bzw. Konfiguration in einem <fencedframe> oder <iframe> auf. Das deprecated im Namen bedeutet: Die Methode ist von vornherein als Übergangslösung gedacht. Sie soll wegfallen, sobald es datenschutzfreundlichere Mechanismen gibt.

Parameter

Name	Typ	Default	Beschreibung
$urnOrConfig Pflicht	string \| FencedFrameConfig		Die undurchsichtige URN (z. B. `urn:uuid:…`) oder das `FencedFrameConfig`-Objekt aus `navigator.runAdAuction()` bzw. `sharedStorage.selectURL()`.
$replacements Pflicht	Record<string, string>		Objekt mit Paaren aus Platzhalter und Ersatzwert. Jeder Schlüssel muss die Form `${NAME}` oder `%%NAME%%` haben. Jeder Wert ist die Zeichenkette, die an dieser Stelle in die URL eingesetzt wird.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald die Ersetzung intern abgeschlossen ist.

Beispiele

Anzeigengröße in die Gewinner-URL einsetzen (URN + iframe)

// Render-URL in der Interessengruppe (beim Bieter hinterlegt):
// https://ads.example/ad.html?size=${SIZE}&campaign=%%CAMPAIGN%%

const showAd = async (auctionConfig) => {
  // resolveToConfig: false → Ergebnis ist eine URN-Zeichenkette
  const urn = await navigator.runAdAuction({
    ...auctionConfig,
    resolveToConfig: false,
  });
  if (!urn) {
    console.log('Keine Anzeige gewonnen');
    return;
  }

  await navigator.deprecatedReplaceInURN(urn, {
    '${SIZE}': '300x250',
    '%%CAMPAIGN%%': 'sommer-2024',
  });

  const frame = document.createElement('iframe');
  frame.width = '300';
  frame.height = '250';
  frame.src = urn; // lädt intern ...?size=300x250&campaign=sommer-2024
  document.querySelector('#ad-slot').append(frame);
};

Mit FencedFrameConfig und <fencedframe>

const renderInFencedFrame = async (auctionConfig) => {
  const config = await navigator.runAdAuction({
    ...auctionConfig,
    resolveToConfig: true,
  });
  if (!config) return;

  await navigator.deprecatedReplaceInURN(config, {
    '${SLOT_ID}': 'sidebar-top',
  });

  const ff = document.createElement('fencedframe');
  ff.config = config;
  document.body.append(ff);
};

Funktionserkennung und Fehlerbehandlung

const safeReplace = async (urnOrConfig, replacements) => {
  if (!('deprecatedReplaceInURN' in navigator)) {
    console.warn('deprecatedReplaceInURN wird nicht unterstützt');
    return false;
  }
  try {
    await navigator.deprecatedReplaceInURN(urnOrConfig, replacements);
    return true;
  } catch (err) {
    // z. B. TypeError bei falschem Platzhalterformat wie 'SIZE'
    console.error(err.name, err.message);
    return false;
  }
};

// Ungültig: Schlüssel ohne ${} oder %%
await safeReplace('urn:uuid:1234', { SIZE: '300x250' });

TypeError ...

// Wichtig · Fallstricke

Experimentell und nicht standardisiert: Die Methode gibt es nur in Chromium-Browsern mit aktivierter Privacy Sandbox. Firefox und Safari unterstützen sie nicht. Prüfen Sie deshalb immer vorher mit 'deprecatedReplaceInURN' in navigator.
Absichtlich als veraltet benannt: Die Methode ist eine Übergangslösung und kann in künftigen Versionen ohne lange Vorwarnung entfallen. Verlassen Sie sich langfristig nicht darauf.
Platzhalterformat: Schlüssel müssen mit ${ beginnen und mit } enden oder von %% eingerahmt sein. Andere Schlüssel führen zu einem TypeError.
Nur gültige URNs: Es funktionieren nur URNs bzw. Konfigurationen, die der Browser selbst erzeugt hat, etwa durch runAdAuction() oder sharedStorage.selectURL(). Unbekannte URNs führen zu einem Fehler.
Reihenfolge: Die Ersetzung muss vor dem Laden im Frame abgeschlossen sein. Warten Sie also mit await auf das Promise, bevor Sie src bzw. config setzen.
Datenschutz: Die eingesetzten Werte landen in der Anzeigen-URL und damit beim Werbe-Server. Setzen Sie keine nutzerbezogenen Daten ein. Das würde dem Zweck der Privacy Sandbox widersprechen.
Die Methode ist nur in sicheren Kontexten (HTTPS) verfügbar. Zusätzlich kann sie durch die Permissions-Policy run-ad-auction eingeschränkt sein.

Siehe auch

Navigator Navigator.unregisterProtocolHandler() Navigator.getInstalledRelatedApps() Navigator.sendBeacon() Navigator.getAutoplayPolicy()