Navigator: deprecatedReplaceInURN() method
Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
The deprecatedReplaceInURN()
method of the Navigator
interface substitutes specified strings inside the mapped URL corresponding to a given opaque URN or FencedFrameConfig
's internal url
property.
A FencedFrameConfig
or opaque URN is returned from a source such as the Protected Audience API runAdAuction()
method, and then set as the value of HTMLFencedFrameElement.config
. The content URL associated with the FencedFrameConfig
or opaque URN is mapped to it internally by the browser, and can't be accessed via JavaScript.
However, you may wish to substitute parts of that internal URL. This is a common approach for passing runtime data into ad creatives to use in rendering. deprecatedReplaceInURN()
has been made available as a temporary measure to enable that substitution for fenced frame URLs, helping ad tech providers to migrate existing implementations across to privacy sandbox APIs.
Syntax
deprecatedReplaceInURN(UrnOrConfig, replacements)
Parameters
UrnOrConfig
-
A
FencedFrameConfig
object or a opaque URN for which you want to substitute parts of the corresponding internal URL. replacements
-
An object containing one or more properties representing the substitutions you wish to make in the internal URL. Each property key is a URL subsection you wish to replace, and each property value is the string to replace it with. Note that:
- The URL subsections to replace must be in one of the following formats:
${string}
%%string%%
- If a URL subsection is in a correct format, but the subsection is not found in the URL, the returned promise still fulfills but no substitution is made.
- The URL subsections to replace must be in one of the following formats:
Return value
Exceptions
TypeError
DOMException
-
Thrown if:
UrnOrConfig
is not a validFencedFrameConfig
object or opaque URN.- Any of the specified replacement keys do not match the allowed formats.
Examples
The following call could be used to return an opaque URN:
const exampleURN = await navigator.runAdAuction({
...auctionConfig,
resolveToConfig: false,
});
You can then substitute URL subsections using a deprecatedReplaceInURN()
call like the following:
await navigator.deprecatedReplaceInURN(exampleURN, {
"${foo}": "1",
"${bar}": "2",
"%%baz%%": "3",
});
If the internal URL associated with the URN is initially:
https://example.com/a=${foo}&b=${bar}&c=%%baz%%
After the substitution it will become:
https://example.com/a=1&b=2&c=3
Specifications
Specification |
---|
Fenced Frame # dom-navigator-deprecatedreplaceinurn |
Browser compatibility
BCD tables only load in the browser