JavaScript Navigator deprecatedReplaceInURN() Method

What You’ll Learn

navigator.deprecatedReplaceInURN() substitutes placeholders inside a browser-mapped fenced-frame URL for an opaque URN or FencedFrameConfig. Learn the purpose, allowed ${string} / %%string%% key formats, MDN examples, five labs, and why everyday sites can skip this API.

Introduction

Fenced frames load privacy-sensitive content (often ads) without letting the embedder read the destination URL. A source such as Protected Audience runAdAuction() can return an opaque URN or a FencedFrameConfig, which you assign to a <fencedframe>. The real URL stays inside the browser.

Older ad systems still inject runtime values into creative URLs (campaign ids, sizes, and so on). deprecatedReplaceInURN() is a temporary bridge: it replaces allowed placeholders in that hidden URL so creatives keep working while teams migrate.

Understanding the deprecatedReplaceInURN() Method

• Input 1 — a FencedFrameConfig or opaque URN from an auction / similar source.
• Input 2 — a replacements object whose keys are placeholders and values are substitute strings.
• Allowed keys — ${string} or %%string%% only.
• Missing placeholders — correctly formatted keys that are not in the URL are skipped; the Promise still fulfills.
• Invalid keys / URN — can throw TypeError.
• Temporary — named for migration; plan to leave it behind in new designs.

📝 Syntax

General form of the method:

navigator.deprecatedReplaceInURN(UrnOrConfig, replacements)

Parameters

• UrnOrConfig — a FencedFrameConfig or opaque URN whose internal URL should be updated.
• replacements — object of placeholder → replacement string pairs.

Return value

• A Promise that fulfills with undefined.

Common patterns

// MDN-style flow (requires a real auction URN / config)
const exampleURN = await navigator.runAdAuction({
  ...auctionConfig,
  resolveToConfig: false
});

await navigator.deprecatedReplaceInURN(exampleURN, {
  "${foo}": "1",
  "${bar}": "2",
  "%%baz%%": "3"
});

// Before (internal URL, not readable from JS):
// https://example.com/a=${foo}&b=${bar}&c=%%baz%%
// After:
// https://example.com/a=1&b=2&c=3

Examples Gallery

Examples follow MDN patterns. Prefer Try It Yourself — a real auction URN / FencedFrameConfig is rare outside Privacy Sandbox demos, so labs focus on detection, placeholder rules, and safe calling patterns.

const lines = [
  "deprecatedReplaceInURN: " +
    (typeof navigator.deprecatedReplaceInURN === "function"
      ? "available"
      : "missing"),
  "isSecureContext: " + window.isSecureContext
];
console.log(lines.join("\n"));

deprecatedReplaceInURN: missing
isSecureContext: true
(or "available" in supporting Privacy Sandbox browsers)

function isAllowedReplacementKey(key) {
  return /^\$\{.+\}$/.test(key) || /^%%.+%%$/.test(key);
}

const samples = ["${foo}", "%%baz%%", "foo", "{bar}"];
console.log(
  samples
    .map((k) => k + ": " + (isAllowedReplacementKey(k) ? "allowed" : "invalid"))
    .join("\n")
);

${foo}: allowed
%%baz%%: allowed
foo: invalid
{bar}: invalid

async function tryMdnStyleReplace(exampleURN) {
  if (typeof navigator.deprecatedReplaceInURN !== "function") {
    return "API missing — cannot substitute fenced URN URLs here";
  }
  if (!exampleURN) {
    return "No URN / FencedFrameConfig — obtain one from runAdAuction (or similar) first";
  }
  await navigator.deprecatedReplaceInURN(exampleURN, {
    "${foo}": "1",
    "${bar}": "2",
    "%%baz%%": "3"
  });
  return "Substitution requested (internal URL updated by the browser)";
}

tryMdnStyleReplace(null).then(console.log);

API missing — cannot substitute fenced URN URLs here
(or the no-URN / success messages in supporting environments)

async function replaceWithGuardedKeys(urn, replacements) {
  if (typeof navigator.deprecatedReplaceInURN !== "function") {
    return "API missing";
  }
  const bad = Object.keys(replacements).filter(
    (k) => !(/^\$\{.+\}$/.test(k) || /^%%.+%%$/.test(k))
  );
  if (bad.length) {
    return "Blocked invalid keys: " + bad.join(", ");
  }
  try {
    await navigator.deprecatedReplaceInURN(urn, replacements);
    return "OK";
  } catch (err) {
    return "Error: " + err.name;
  }
}

replaceWithGuardedKeys("urn:example", { foo: "1", "${bar}": "2" }).then(console.log);

API missing
(or "Blocked invalid keys: foo" when the API exists)

function shouldUseDeprecatedReplaceInURN(options) {
  if (!options || !options.migratingFencedFrameCreatives) {
    return "Skip — not migrating fenced-frame ad creatives";
  }
  if (typeof navigator.deprecatedReplaceInURN !== "function") {
    return "Skip — API unavailable in this browser";
  }
  return "OK to feature-detect and call for temporary migration only";
}

console.log(shouldUseDeprecatedReplaceInURN({ migratingFencedFrameCreatives: false }));
console.log(shouldUseDeprecatedReplaceInURN({ migratingFencedFrameCreatives: true }));

Skip — not migrating fenced-frame ad creatives
Skip — API unavailable in this browser
(or the OK message when both conditions pass)

🚀 Common Use Cases

• Ad creative migration — keep placeholder substitution while moving to fenced frames.
• Protected Audience flows — after runAdAuction returns an opaque URN.
• FencedFrameConfig setups — substitute values before assigning config.
• Runtime creative params — inject size / slot / campaign tokens without exposing the URL.
• Learning Privacy Sandbox — recognize the API when reading advanced docs.

📝 Notes

• Experimental & Limited availability — not Baseline; feature-detect always.
• Not MDN-Deprecated or Non-standard — Experimental banner only (name signals temporary migration).
• Niche Privacy Sandbox / ad-tech API — skip for typical beginner projects.
• Returns a Promise; invalid keys or URN/config can throw TypeError.
• Related: getAutoplayPolicy(), canShare(), xr, Window.

💡 Best Practices