WindowSharedStorage: selectURL() method
Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
The selectURL()
method of the
WindowSharedStorage
interface executes a URL Selection operation that is registered in a module added to the current origin's SharedStorageWorklet
.
Note: The URL Selection output gate is used to select a URL from a provided list to display to the user, based on shared storage data.
Syntax
selectURL(name, urls)
selectURL(name, urls, options)
Parameters
name
-
A string representing the registered operation's name within the shared storage worklet module. It must match the name given to the operation when it is registered with
SharedStorageWorkletGlobalScope.register()
. urls
-
An array of objects representing the URLs to be chosen between by the URL Selection operation. Each object contains two properties:
url
-
A string representing the URL.
reportingMetadata
Optional-
An object containing properties where names are event types and values are URLs pointing to reporting destinations, for example
"click" : "my-reports/report1.html"
. The URLs act as destinations for reports submitted with a destination of type"shared-storage-select-url"
, typically submitted via aFence.reportEvent()
orFence.setReportEventDataForAutomaticBeacons()
method call.
options
Optional-
An options object, which can contain the following properties:
data
Optional-
An object representing any data required for executing the operation.
keepAlive
Optional-
A boolean value. If set to
true
, theSharedStorageWorkletGlobalScope
of the associated worklet is kept alive, and the operation can be run again. Therefore, you need to setkeepAlive
totrue
for each operation that is not intended to be the last one. The default value,false
, means that theSharedStorageWorkletGlobalScope
is terminated after the operation is run and cannot be run again. resolveToConfig
Optional-
A boolean value. If set to
true
, the fulfillment value of thePromise
returned byrun()
will be aFencedFrameConfig
object that can be used to load content into a<fencedframe>
via itsconfig
attribute. The default value,false
, means that the fulfillment value will be a URL that can be used to load content into an<iframe>
.
Return value
A Promise
that fulfills with a FencedFrameConfig
object or a string representing a URL, depending on the value of the resolveToConfig
option.
Exceptions
TypeError
-
Thrown if:
- The worklet module has not yet been added with
addModule()
. urls
is empty or exceeds the maximum allowed length (which is browser-specific).- An object's
url
property contains an invalid URL. - Shared storage is disabled (for example, via a browser setting).
- The calling site does not have the Shared Storage API included in a successful privacy sandbox enrollment process.
- The worklet module has not yet been added with
Examples
Basic A/B testing
// Randomly assigns a user to a group 0 or 1
function getExperimentGroup() {
return Math.round(Math.random());
}
async function injectContent() {
// Add the module to the shared storage worklet
await window.sharedStorage.worklet.addModule("ab-testing-worklet.js");
// Assign user to a random group (0 or 1) and store it in shared storage
window.sharedStorage.set("ab-testing-group", getExperimentGroup(), {
ignoreIfPresent: true,
});
// Run the URL selection operation
const fencedFrameConfig = await window.sharedStorage.selectURL(
"ab-testing",
[
{ url: `https://your-server.example/content/default-content.html` },
{ url: `https://your-server.example/content/experiment-content-a.html` },
],
{
resolveToConfig: true,
},
);
// Render the chosen URL into a fenced frame
document.getElementById("content-slot").config = fencedFrameConfig;
}
injectContent();
See the Shared Storage API landing page for a walkthrough of this example and links to other examples.
Specifications
Specification |
---|
Shared Storage API # dom-windowsharedstorage-selecturl |
Browser compatibility
BCD tables only load in the browser