1. Introduction
This section is non-normative
The FLEDGE API facilitates selecting an advertisement to display to a user based on a previous interaction with the advertiser or advertising network.
When a user’s interactions with an advertiser indicate an interest in something, the advertiser can
ask the browser to record this interest on-device by calling navigator
.joinAdInterestGroup()
. Later, when a website wants to select an
advertisement to show to the user, the website can call navigator
.runAdAuction()
to ask the browser to conduct an auction where
each of these on-device recorded interests are given the chance to calculate a bid to display their
advertisement.
2. Joining Interest Groups
When a user’s interactions with a website indicate that the user may have a particular interest, an
advertiser or someone working on behalf of the advertiser (e.g. a demand side platform, DSP) can ask
the user’s browser to record this interest on-device by calling navigator
.joinAdInterestGroup()
. This indicates an intent to display an
advertisement relevant to this interest to this user in the future. The user agent has an interest group set, a list of interest groups in which owner / name pairs are unique.
[SecureContext ]partial interface Navigator {Promise <undefined >joinAdInterestGroup (AuctionAdInterestGroup ,
group double ); };
durationSeconds enum {
WorkletExecutionMode ,
"compatibility" , };
"groupByOrigin" dictionary {
AuctionAd required USVString ;
renderUrl any ; };
metadata dictionary {
AuctionAdInterestGroup required USVString ;
owner required USVString ;
name double = 0.0;
priority boolean =
enableBiddingSignalsPrioritization false ;record <USVString ,double >;
priorityVector record <USVString ,double >;
prioritySignalsOverrides WorkletExecutionMode = "compatibility";
executionMode USVString ;
biddingLogicUrl USVString ;
biddingWasmHelperUrl USVString ;
dailyUpdateUrl USVString ;
trustedBiddingSignalsUrl sequence <USVString >;
trustedBiddingSignalsKeys any ;
userBiddingSignals sequence <AuctionAd >;
ads sequence <AuctionAd >; };
adComponents
The joinAdInterestGroup(group, durationSeconds)
method steps are:
-
If this's relevant global object's associated Document is not allowed to use the "join-ad-interest-group" policy-controlled feature, then throw a "
NotAllowedError
"DOMException
. -
Let interestGroup be a new interest group.
-
Validate the given group and set interestGroup’s fields accordingly.
-
Set interestGroup’s expiry to now plus durationSeconds.
-
Let ownerUrl be the result of running the URL parser on group["
owner
"]. -
Set interestGroup’s enable bidding signals prioritization to group["
enableBiddingSignalsPrioritization
"]. -
If group["
priorityVector
"] exists, then set interestGroup’s priority vector to group["priorityVector
"]. -
If group["
prioritySignalsOverrides
"] exists, then set interestGroup’s priority signals overrides to group["prioritySignalsOverrides
"]. -
Set interestGroup’s execution mode to group["
executionMode
"]. -
For each groupMember and interestGroupField in the following table
Group member Interest group field " biddingLogicUrl
"bidding url " biddingWasmHelperUrl
"bidding wasm helper url " dailyUpdateUrl
"daily update url " trustedBiddingSignalsUrl
"trusted bidding signals url -
If group contains groupMember:
-
Let parsedUrl be the result of running the URL parser on group[groupMember].
-
-
parsedUrl is an error.
-
parsedUrl is not same origin with interestGroup’s owner.
-
parsedUrl includes credentials.
-
parsedUrl fragment is not null.
-
-
Set interestGroup’s interestGroupField to parsedUrl.
-
-
-
If interestGroup’s trusted bidding signals url's query is not null, then throw a
TypeError
. -
If group["
trustedBiddingSignalsKeys
"] exists, then set interestGroup’s trusted bidding signals keys to group["trustedBiddingSignalsKeys
"]. -
If group["
userBiddingSignals
"] exists:-
Let interestGroup’s user bidding signals be the result of serializing a JavaScript value to a JSON string, given group["
userBiddingSignals
"]. This can throw aTypeError
.
-
-
For each groupMember and interestGroupField in the following table
Group member Interest group field " ads
"ads " adComponents
"ad components -
For each ad of group[groupMember]:
-
Let igAd be a new interest group ad.
-
Let renderUrl be the result of running the URL parser on ad["
renderUrl
"]. -
-
renderUrl is an error.
-
renderUrl scheme is not "
https
". -
renderUrl includes credentials.
-
-
Set igAd’s render url to renderUrl.
-
If ad["
metadata
"] exists, then let igAd’s metadata be the result of serializing a JavaScript value to a JSON string, given ad["metadata
"]. This can throw aTypeError
. -
Append igAd to interestGroup’s interestGroupField.
-
-
-
-
If interestGroup’s estimated size is greater than 50 KB, then throw a
TypeError
. -
Let p be a new promise.
-
Return p and run the following steps in parallel: (TODO: Enqueue the steps to a parallel queue instead.)
-
TODO: document .well-known fetches for cross-origin joins.
-
If the browser is currently storing an interest group with
owner
andname
that matches interestGroup, then remove the currently stored one. -
Store interestGroup in the browser’s interest group set.
-
Queue a task to resolve p with
undefined
.
-
The estimated size of an interest group ig is the sum of:
-
The length of the serialization of ig’s owner.
-
8 bytes, which is the size of ig’s priority.
-
The length of ig’s execution mode.
-
2 bytes, which is the size of ig’s enable bidding signals prioritization.
-
If ig’s priority vector is not null, for each key → value of priority vector:
-
The length of key.
-
8 bytes, which is the size of value.
-
-
If ig’s priority signals overrides is not null, for each key → value of priority signals overrides:
-
The length of key.
-
8 bytes, which is the size of value.
-
-
The size of execution mode.
-
The length of the serialization of ig’s bidding url, if the field is not null.
-
The length of the serialization of ig’s bidding wasm helper url, if the field is not null.
-
The length of the serialization of ig’s daily update url, if the field is not null.
-
The length of the serialization of ig’s trusted bidding signals url, if the field is not null.
-
For each key of ig’s trusted bidding signals keys:
-
The length of key.
-
-
The length of ig’s user bidding signals.
-
If ig’s ads is not null, for each ad of it:
-
The length of the serialization of ad’s render url.
-
-
If ig’s ad components is not null, for each ad of it:
-
The length of the serialization of ad’s render url.
-
3. Running Ad Auctions
When a website or someone working on behalf of the website (e.g. a supply side platform, SSP) wants
to conduct an auction to select an advertisement to display to the user, they can call the navigator
.runAdAuction()
function, providing an auction configuration that
tells the browser how to conduct the auction and which on-device recorded interests are allowed to
bid in the auction for the chance to display their advertisement.
[SecureContext ]partial interface Navigator {Promise <USVString ?>(
runAdAuction AuctionAdConfig ); };
config dictionary {
AuctionAdConfig required USVString ;
seller required USVString ;
decisionLogicUrl USVString ;
trustedScoringSignalsUrl sequence <USVString >;
interestGroupBuyers any ;
auctionSignals any ;
sellerSignals USVString ;
directFromSellerSignals unsigned long long ;
sellerTimeout unsigned short ;
sellerExperimentGroupId record <USVString ,any >;
perBuyerSignals record <USVString ,unsigned long long >;
perBuyerTimeouts record <USVString ,unsigned short >;
perBuyerGroupLimits record <USVString ,unsigned short >;
perBuyerExperimentGroupIds record <USVString ,record <USVString ,double >>;
perBuyerPrioritySignals sequence <AuctionAdConfig >;
componentAuctions AbortSignal ?; };
signal
4. Permissions Policy integration
This specification defines a policy-controlled feature identified by the string
"join-ad-interest-group
". Its default allowlist is 'self'
.
Note: In the Chromium implementation the default allowlist is temporarily set to *
to ease
testing.
5. Structures
5.1. Interest group
An interest group is a struct with the following items:
- expiry
-
A point in time at which the browser will forget about this interest group.
- owner
-
An origin.
- name
-
A string.
- priority
-
A double. Defaulting to 0.0. Used to select which interest groups participate in an auction when the number of interest groups are limited by
perBuyerGroupLimits
. - enable bidding signals prioritization
-
A boolean. Defaulting to false. Being true if the interest group’s priority should be calculated using vectors from bidding signals fetch.
- priority vector
-
Null or an ordered map whose keys are strings and whose values are doubles. Its dot product with the
perBuyerPrioritySignals
will be used in place of priority, if set. - priority signals overrides
-
Null or an ordered map whose keys are strings and whose values are doubles. Overrides the
AuctionAdConfig
's corresponding priority signals. - execution mode
-
An
WorkletExecutionMode
, defaulting to "compatibility". - bidding url
-
Null or a URL. The URL to fetch the buyer’s Javascript from.
- bidding wasm helper url
-
Null or a URL. Lets the bidder provide computationally-expensive subroutines in WebAssembly, rather than JavaScript, to be driven from the JavaScript function provided by bidding url.
- daily update url
-
Null or a URL. Provides a mechanism for the group’s owner to periodically update the attributes of the interest group.
- trusted bidding signals url
-
Null or a URL. Provide a mechanism for making real-time data available for use at bidding time.
- trusted bidding signals keys
- user bidding signals
-
Null or a string. Additional metadata that the owner can use during on-device bidding.
- ads
-
Null or a list of interest group ad. Contains various ads that the interest group might show.
- ad components
-
Null or a list of interest group ad. Contains various ad components (or "products") that can be used to construct ads composed of multiple pieces — a top-level ad template "container" which includes some slots that can be filled in with specific "products".
TODO: Update the short descriptions of some fields above, and add links when runAdAuction() section is ready.
5.2. Interest group ad
An interest group ad is a struct with the following items: