This post is a technical reference to the current iteration of the experimental Protected Audience API.
The Protected Audience API is a less technical overview of the proposal, and also has a glossary.
The Protected Audience demo provides a walkthrough of a basic FLEDGE deployment.
The Protected Audience demo video explains how the demo code works, and shows how to use Chrome DevTools for Protected Audience debugging.
The Protected Audience API is a Privacy Sandbox proposal to serve remarketing and custom audience use cases, designed so that it cannot be used by third parties to track user browsing behavior across sites. The API enables on-device auctions by the browser, to choose relevant ads for websites the user has previously visited.
Protected Audience is the first experiment to be implemented in Chromium within the TURTLEDOVE family of proposals.
The diagram below provides an overview of the FLEDGE lifecycle:
FLEDGE lifecycle. How can I try Protected Audience? Protected Audience demoA walkthrough of a basic Protected Audience deployment across advertiser and publisher sites is available at protected-audience-demo.web.app.
The demo video explains how the demo code works, and shows how to use Chrome DevTools for Protected Audience debugging.
Take part in a Protected Audience origin trialA Privacy Sandbox Relevance and Measurement origin trial has been made available in Chrome Beta 101.0.4951.26 and above on desktop for the Protected Audience, Topics, and Attribution Reporting APIs.
To take part, register for an origin trial token.
Once you have successfully enrolled in the trial, you can try out the Protected Audience JavaScript API on pages that provide a valid trial token: for example, to ask the browser to join one or more interest groups, and then to run an ad auction to select and display an ad.
The Protected Audience demo provides a basic example of an end-to-end Protected Audience deployment.
Provide a trial token for every page on which you would like to run Protected Audience API code:
As a meta tag in the <head>:
<meta http-equiv="origin-trial" content="TOKEN_GOES_HERE">
As an HTTP header:
Origin-Trial: TOKEN_GOES_HERE
By providing a token programmatically:
const otMeta = document.createElement('meta');
otMeta.httpEquiv = 'origin-trial';
otMeta.content = 'TOKEN_GOES_HERE';
document.head.append(otMeta);
An iframe running Protected Audience code—such as a navigator.joinAdInterestGroup() call by an interest group owner—will need to provide a token that matches its origin.
Proposed First Protected Audience Origin Trial Details provides more details about the goals of the first trial and explains what features are supported.
Caution: Not all users may be eligible for the Privacy Sandbox Relevance and Measurement origin trial, even on pages that provide a valid trial token. Test this APIYou can test Protected Audience for a single user in Chrome Beta 101.0.4951.26 and above on desktop:
chrome://settings/adPrivacyAds can be rendered in an <iframe> or a <fencedframe>, depending on which flags are set.
To use <fencedframe> to render ads:
--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,FencedFrames
To use <iframe> to render ads:
--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,AllowURNsInIframes --disable-features=FencedFrames
Include the BiddingAndScoringDebugReportingAPI flag to enable the temporary debug loss/win reporting methods.
Run Chromium with flags explains how to set flags when running Chrome and other Chromium-based browsers from the command line. The full list of Protected Audience flags is available from Chromium Code Search.
Note: This is an in-progress version of Protected Audience for early testing. It shouldn't be considered complete or indicative of the final implementation. Protected Audience progress and status are discussed in the regular WICG meetings. The minutes for the 2021-05-12 WICG call provide detail on what is and is not supported in the current implementation. The Privacy Sandbox timeline provides implementation timing information for Protected Audience and other Privacy Sandbox proposals. What features are supported in the latest version of Chrome?Protected Audience is being made available behind feature flags in Chromium as a first experiment to test the following features of the Protected Audience proposal:
The API explainer provides more detail about feature support and constraints.
Interest group permissionsThe default in the current implementation of Protected Audience is to allow calling joinAdInterestGroup() from anywhere in a page, even from cross-domain iframes. In the future, once site owners have had time to adjust their cross-domain iframe permissions policies, the plan is to disallow calls from cross-domain iframes, as the explainer describes.
As part of a Protected Audience ad auction, the browser can access a key/value service that returns simple key-value pairs to provide information to an ad buyer, such as remaining campaign budget. The Protected Audience proposal mandates that this server "performs no event-level logging and has no other side effects based on these requests".
The Protected Audience Key/Value service code is now available in a Privacy Sandbox GitHub repository. This service can be used by Chrome and Android developers. Check out the announcement blog post for the status update. Learn more about the Protected Audience Key/Value service from the API explainer and the trust model explainer.
For initial testing, "Bring Your Own Server" model is used. In the long-term, adtechs will need to use the open-source Protected Audience Key/Value services running in trusted execution environments for retrieving real-time data.
To ensure that the ecosystem has sufficient time to test, we don't expect to require the use of the open-source Key/Value services or TEEs until sometime after third-party cookie deprecation. We will provide substantial notice for developers to begin testing and adoption before this transition takes place.
Detect feature supportBefore using the API, check if it's supported by the browser and available in the document:
'joinAdInterestGroup' in navigator &&
document.featurePolicy.allowsFeature('join-ad-interest-group') &&
document.featurePolicy.allowsFeature('run-ad-auction') ?
console.log('navigator.joinAdInterestGroup() is supported on this page') :
console.log('navigator.joinAdInterestGroup() is not supported on this page');
You can block access to the Protected Audience API either as a site owner, or as an individual user.
How can sites control access?Protected Audience will eventually require sites to set a Permissions Policy to allow Protected Audience functionality to be available. This will help ensure that arbitrary third parties can't use the API without a site's knowledge. However, to facilitate testing during the first origin trial, this requirement is waived by default. Sites that would like to explicitly disable Protected Audience functionality during the testing period can use the relevant Permissions Policy to block access.
There are two Protected Audience permissions policies that can be set independently:
join-ad-interest-group enables/disables functionality to add a browser to interest groupsrun-ad-auction enables/disables functionality to run an on-device auctionAccess to Protected Audience APIs can be disabled completely in first-party contexts by specifying the following permissions policy in an HTTP response header:
Permissions-Policy: join-ad-interest-group=(), run-ad-auction=()
You can disable usage of the APIs in an iframe by adding the following allow attribute to an iframe element:
<iframe src="https://example.com" allow="join-ad-interest-group 'none'; run-ad-auction 'none'"></iframe>
The Proposed First Protected Audience Origin Trial Permissions-Policy section provides more detail.
User opt-outA user can block access to the Protected Audience API and other Privacy Sandbox features by using any of the following mechanisms:
chrome://settings/adPrivacy.chrome://settings/cookies.The Protected Audience explainer provides more detail about API design elements and describes how the API seeks to meet privacy goals.
Debug Protected Audience workletsFrom Chrome Canary 98.0.4718.0, it's possible to debug Protected Audience worklets within Chrome DevTools.
The first step is to set breakpoints via a new category in the Event Listener Breakpoints pane in the Sources panel.
When a breakpoint triggers, execution is paused before the first statement at the top-level of the worklet script. You can use regular breakpoints or step commands to get to the bidding/scoring/reporting function itself.
Live worklet scripts will also show up under the Threads panel.
Since some worklets may run in parallel, multiple threads may end up in the "paused" state there; you can use the thread list to switch between threads, and resume or inspect them more closely as appropriate.
Observe Protected Audience eventsFrom the Application panel in Chrome DevTools, you can observe Protected Audience interest group and auction events.
If you visit the Protected Audience demo shopping site in a browser with Protected Audience enabled, DevTools will display information about the join event.
Now, if you visit the Protected Audience demo publisher site in a browser with Protected Audience enabled, DevTools displays information about the bid and win events.
In this example, a user browses the website of a custom bike maker, then later visits a news website and is shown an ad for a new bike from the bike maker.
Warning: Not all features described in this post have been implemented (or fully implemented) in the version of the Protected Audience API currently being tested in Chrome. Test with feature flags explains what Protected Audience features are currently available for testing in Chrome run from the command line using feature flags. We expect the features of Protected Audience will be added over time as work on implementation continues. Once the API reaches the origin trial stage, we'll provide a regularly-updated list of which parts are already implemented and what's still in progress. 1. A user visits an advertiser siteImagine that a user visits the website of a custom bike maker (the advertiser in this example) and spends some time on the product page for a handmade steel bike. This provides the bike maker with a remarketing opportunity.
Key term: demand-side platform (DSP) is an adtech service used to automate ad purchasing. DSPs are used by advertisers to buy ad impressions across a range of publisher sites. Publishers put their ad inventory up for sale through marketplaces called ad exchanges, and DSPs decide programmatically which available ad impression makes most sense for an advertiser to buy. A supply-side platform (SSP) is an adtech service used to automate selling ad inventory. SSPs allow publishers to offer their inventory (empty rectangles where ads will go) to multiple ad exchanges, DSPs, and networks. This enables a wide range of potential buyers to bid for ad space.⬇︎
2. The user's browser is asked to add an interest groupExplainer section: Browsers Record Interest Groups
The advertiser's demand-side platform (DSP) (or the advertiser itself) calls navigator.joinAdInterestGroup() to ask the browser to add an interest group to the list of groups the browser is a member of. In this example, the group is named custom-bikes, and the owner is dsp.example. The interest group owner (in this case, the DSP) will be a buyer in the ad auction described in step 4. Interest group membership is stored by the browser, on the user's device, and is not shared with the browser vendor or anyone else.
joinAdInterestGroup() must match the interest group owner's origin, so joinAdInterestGroup() will need to be called from an iframe (for example, from a DSP) unless the origin of the interest group owner matches the origin of the current document (for example, a website with its own interest groups). runAdAuction doesn't have the same requirements, so calling runAdAuction() from a <script> tag is probably far more performant than a cross-origin iframe.
joinAdInterestGroup() requires permission from:
For example: it must not be possible for malicious.example to call joinAdInterestGroup() with dsp.example as owner without the permission of dsp.example.
Same origin: By default, permission is implicitly granted for joinAdInterestGroup() calls from the same origin as the site being visited, i.e. from the same origin as the top-level frame of the current page. Sites can use a Protected Audience permissions policy header join-ad-interest-group directive to disable joinAdInterestGroup() calls.
Cross origin: Calling joinAdInterestGroup() from origins that are different from the current page can only succeed if the site being visited has set a permissions policy that allows calls to joinAdInterestGroup() from cross-origin iframes.
joinAdInterestGroup() from anywhere in a page, even from cross-origin iframes. In the future, once site owners have had time to adjust their permissions policies, the plan is by default to disallow calls from cross-origin iframes, as described in the Protected Audience explainer. Permission from the interest group owner
Interest group owner permission is implicitly granted by calling joinAdInterestGroup() from an iframe with the same origin as that of the interest group's owner. For example, a dsp.example iframe can call joinAdInterestGroup() for interest groups owned by dsp.example.
The proposal is that joinAdInterestGroup() can run in a page or iframe in the owner's domain, or be delegated to other domains provided using a list at a .well-known URL.
Here's an example of how the API might be used:
const interestGroup = {
owner: 'https://dsp.example',
name: 'custom-bikes',
biddingLogicUrl: ...,
biddingWasmHelperUrl: ...,
dailyUpdateUrl: ...,
trustedBiddingSignalsUrl: ...,
trustedBiddingSignalsKeys: ['key1', 'key2'],
userBiddingSignals: {...},
ads: [bikeAd1, bikeAd2, bikeAd3],
adComponents: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2],
};
navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);
The interestGroup object passed to the function must be no more than 50 kiB in size, otherwise the call will fail. The second parameter specifies the duration of the interest group, capped at 30 days. Successive calls overwrite previously stored values.
biddingLogicUrl, decisionLogicUrl, and trustedBiddingSignals all require an X-Allow-FLEDGE: true HTTP response header. Interest group properties Property Required Example Role owner Required 'https://dsp.example' Origin of the interest group owner. name Required 'custom-bikes' Name of the interest group. biddingLogicUrl** Optional* 'https://dsp.example/bid/custom-bikes/bid.js' URL for bidding JavaScript run in worklet. biddingWasmHelperUrl** Optional* 'https://dsp.example/bid/custom-bikes/bid.wasm' URL for WebAssembly code driven from biddingLogicUrl. dailyUpdateUrl** Optional 'https://dsp.example/bid/custom-bikes/update' URL that returns JSON to update interest group attributes. (See Update the interest group.) trustedBiddingSignalsUrl** Optional 'https://dsp.example/trusted/bidding-signals' Base URL for key-value requests to bidder's trusted server. trustedBiddingSignalsKeys Optional ['key1', 'key2' ...] Keys for requests to key-value trusted server. userBiddingSignals Optional {...} Additional metadata the owner can use during bidding. ads Optional* [bikeAd1, bikeAd2, bikeAd3] Ads that might be rendered for this interest group. adComponents Optional [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2] Components for ads composed of multiple pieces.
* All properties are optional except for owner and name. The biddingLogicUrl and ads properties are optional, but required to participate in an auction. There may be use cases for creating an interest group without these properties: for example, an interest group owner might want to add a browser to an interest group for a campaign that isn't running yet, or for some other future use, or they may temporarily have run out of advertising budget.
** The biddingLogicUrl, biddingWasmHelperUrl, dailyUpdateUrl and trustedBiddingSignalsUrl URLs must have the same origin as owner. The ads and adComponents URLs have no such constraint.
dailyUpdateUrl specifies a web server that returns JSON defining interest group properties, corresponding to the interest group object passed to navigator.joinAdInterestGroup(). This provides a mechanism for the group's owner to periodically update the attributes of the interest group. In the current implementation, the following attributes can be changed:
biddingLogicUrlbiddingWasmHelperUrltrustedBiddingSignalsUrltrustedBiddingSignalsKeysadspriorityAny field not specified in the JSON will not be overwritten—only fields specified in the JSON get updated—whereas calling navigator.joinAdInterestGroup() overwrites any existing interest group.
Updates are best-effort, and can fail under the following conditions:
Updates can also be canceled if too much contiguous time has been spent updating, though this doesn't impose any rate limiting on canceled (remaining) updates. Updates are rate-limited to a maximum of one per day. Updates that fail due to network errors are retried after an hour, and updates that fail due to disconnection from the internet are retried immediately on reconnection.
Manual updatesUpdates to interest groups owned by the current frame's origin can be triggered manually via navigator.updateAdInterestGroups(). Rate limiting prevents updates from happening too frequently: repeated calls to navigator.updateAdInterestGroups() don't do anything until the rate limit period (currently one day) has passed. The rate limit gets reset if navigator.joinAdInterestGroup() is called again for the same interest group owner and name.
All interest groups loaded for an auction are updated automatically after an auction completes, subject to the same rate limits as manual updates. For each owner with at least one interest group participating in an auction, it's as if navigator.updateAdInterestGroups() is called from an iframe whose origin matches that owner.
ads and adComponents objects include a URL for an ad creative and, optionally, arbitrary metadata that can be used at bidding time. For example:
{
renderUrl: 'https://cdn.example/.../bikeAd1.html',
metadata: bikeAd1metadata // optional
}
The script at biddingLogicUrl provided by an interest group owner must include a generateBid() function. When an ad-space seller calls navigator.runAdAuction(), the generatedBid() function is called once for each of the interest groups the browser is a member of, if the interest group's owner is invited to bid. In other words, generateBid() is called once for each candidate ad. The seller provides a decisionLogicUrl property on the auction configuration parameter passed to navigator.runAdAuction(). The code at this URL must include a scoreAd() function, which is run for each bidder in the auction, to score each of the bids returned by generateBid().
biddingWasmHelperUrl property is optional, but it allows the bidder to provide computationally-expensive subroutines in WebAssembly, rather than JavaScript, to be driven from the JavaScript function provided by biddingLogicUrl. If provided, it must point to a WebAssembly binary, delivered with an application/wasm mimetype. The corresponding WebAssembly.Module is made available by the browser to the generateBid() function.
The script at biddingLogicUrl provided by an ad-space buyer must include a generateBid() function. This function is called once for each candidate ad. runAdAuction() individually checks each ad, along with its associated bid and metadata, then assigns the ad a numerical desirability score.
generateBid(interestGroup, auctionSignals, perBuyerSignals,
trustedBiddingSignals, browserSignals) {
...
return {
ad: adObject,
bid: bidValue,
render: renderUrl,
adComponents: [adComponentRenderUrl1, ...]
};
}
generateBid() takes the following arguments:
interestGroup
The object passed to joinAdInterestGroup() by the ad buyer. (The interest group may be updated via dailyUpdateUrl.)
auctionSignals
A property of the auction config argument passed to navigator.runAdAuction() by the ad-space seller. This provides information about page context (such as the ad size and the publisher ID), the type of auction (first-price or second-price), and other metadata.
perBuyerSignals
As with auctionSignals, a property of the auction configuration argument passed to navigator.runAdAuction() by the seller. This can provide contextual signals from the buyer's server about the page, if the seller is an SSP which performs a real-time bidding call to buyer servers and pipes the response back, or if the publisher page contacts the buyer's server directly. If so, the buyer may wish to check a cryptographic signature of those signals inside generateBid() as protection against tampering.
trustedBiddingSignals
An object whose keys are the trustedBiddingSignalsKeys for the interest group, and whose values are returned in the trustedBiddingSignals request.
browserSignals
An object constructed by the browser, which might include information about page context (such as the hostname of the current page, which the seller could otherwise fake) and data for the interest group itself (such as a record of when the group previously won an auction, to allow on-device frequency capping).
The browserSignals object has the following properties:
{
topWindowHostname: 'publisher.example',
seller: 'https://ssp.example',
joinCount: 3,
bidCount: 17,
prevWins: [[time1,ad1],[time2,ad2],...],
wasmHelper: ... /* WebAssembly.Module object based on interest group's biddingWasmHelperUrl. */
dataVersion: 1, /* Data-Version value from the buyer's Key/Value service response(s). */
}
To calculate a bid value, code in generateBid() can use the properties of the function's parameters. For example:
function generateBid(interestGroup, auctionSignals, perBuyerSignals,
trustedBiddingSignals, browserSignals) {
return {
...
bid: auctionSignals.is_above_the_fold ? perBuyerSignals.atf_value : perBuyerSignals.btf_value,
...
}
}
generateBid() returns an object with four properties:
ad
Arbitrary metadata about the ad, such as information the seller expects to learn about this bid or ad creative. The seller](/resources/glossary#ssp) uses this information in its auction and decision ad creative. The seller uses this information in its auction and decision logic.
bid
A numerical bid that will enter the auction. The seller must be in a position to compare bids from different buyers, therefore bids must be in some seller-chosen unit (e.g. "USD per thousand"). If the bid is zero or negative, then this interest group will not participate in the seller's auction at all. With this mechanism, the buyer can implement any advertiser rules for where their ads may or may not appear.
render
A URL, or a list of URLs, that will be used to render the creative if this bid wins the auction. (See Ads Composed of Multiple Pieces in the API explainer.) The value has to match the renderUrl of one of the ads defined for the interest group.
adComponents
An optional list of up to 20 components for ads composed of multiple pieces, taken from the adComponents property of the interest group argument passed to navigator.joinAdInterestGroup().
The interest group owner can request that a browser be removed from an interest group. In other words, the browser is asked to remove the interest group from the list of those it is a member of.
navigator.leaveAdInterestGroup({
owner: 'https://dsp.example',
name: 'custom-bikes'
});
If a user returns to the site which asked the browser to add an interest group, the interest group owner can call the navigator.leaveAdInterestGroup() function to request the browser remove the interest group. Code for an ad can also call this function for its interest group.
⬇︎
3. The user visits a site that sells ad spaceLater, the user visits a site that sells ads space, in this example a news website. The site has ad inventory, which it sells programmatically using real-time bidding.
Note: There are three main roles described in the Protected Audience proposal explainer: * Advertiser: a site that pays to advertise its products. In the example here, a custom bike maker. * Publisher: sites that sell ad space, such as the online news website referred to in the examples here. Many (but not all) sites selling ad space are content publishers. * Seller: the party running the ad auction (in the next step). Most publishers use an adtech service such as an SSP to optimize selling ad inventory.⬇︎
4. An ad auction is run in the browserExplainer section: Sellers Run On-Device Auctions
The ad auction is likely to be run by the publisher's SSP, or the publisher itself. The purpose of the auction is to select the most appropriate ad for a single available ad slot on the current page. The auction takes into account the interest groups the browser is a member of, along with data from ad-space buyers and the sellers from the Key/Value services.
The ad-space seller makes a request to the user's browser to begin an ad auction by calling navigator.runAdAuction().
For example:
const auctionConfig = {
seller: 'https://ssp.example',
decisionLogicUrl: ...,
trustedScoringSignalsUrl: ...,
interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
auctionSignals: {...},
sellerSignals: {...},
sellerTimeout: 100,
perBuyerSignals: {
'https://dsp.example': {...},
'https://another-buyer.example': {...},
...
},
perBuyerTimeouts: {
'https://dsp.example': 50,
'https://another-buyer.example': 200,
'*': 150,
...
},
componentAuctions: [
{
'seller': 'https://some-other-ssp.example',
'decisionLogicUrl': ...,
...
},
...
]
};
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
runAdAuction() returns a promise that resolves to a URN (urn:uuid:<something>) that represents the ad auction outcome. This can only be decoded by the browser when passed to a fenced frame for rendering: the publisher page cannot inspect the winning ad.
joinAdInterestGroup() must match the interest group owner's origin, so joinAdInterestGroup() will need to be called from an iframe (for example, from a DSP) unless the origin of the interest group owner matches the origin of the current document (for example, a website with its own interest groups). runAdAuction doesn't have the same requirements, so calling runAdAuction() from a <script> tag is probably far more performant than a cross-origin iframe.
The decisionLogicUrl script considers each individual ad, along with its associated bid and metadata, one at a time, and then assigns it a numerical desirability score.
auctionConfig properties Property Required Example Role seller Required 'https://ssp.example' Origin of the seller. decisionLogicUrl Required 'https://ssp.example/auction-decision-logic.js' URL for auction worklet JavaScript. trustedScoringSignalsUrl Optional 'https://ssp.example/scoring-signals' URL of seller's trusted server. interestGroupBuyers* Required ['https://dsp.example', 'https://buyer2.example', ...] Origins of all interest group owners asked to bid in the auction. auctionSignals Optional {...} Seller information about page context, type of auction, etc. sellerSignals Optional {...} Information based on publisher settings, making a contextual ad request, etc. sellerTimeout Optional 100 Maximum runtime (ms) of seller's scoreAd() script. perBuyerSignals Optional {'https://dsp.example': {...},
'https://another-buyer.example': {...},
...} Contextual signals about the page for each specific buyer, from their server. perBuyerTimeouts Optional 50 Maximum runtime (ms) of particular buyer's generateBid() scripts. componentAuctions Optional [{'seller': 'https://www.some-other-ssp.com',
'decisionLogicUrl': ..., ...},
...] Additional configurations for component auctions.
* The seller may specify interestGroupBuyers: '*' to permit all interest groups to bid. Ads are then accepted or rejected based on criteria other than inclusion of the interest group owner. For example, the seller may review ad creatives to confirm compliance with their policies.
** additionalBids is not supported in the current implementation of Protected Audience. Read the Auction Participants section in the Protected Audience explainer for more information.
The code at decisionLogicUrl (a property of the auction configuration object passed to runAdAuction()) must include a scoreAd() function. This is run once for each ad to determine its desirability.
scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
...
return desirabilityScoreForThisAd;
}
scoreAd() takes the following arguments:
adMetadatabidauctionConfignavigator.runAdAuction().trustedScoringSignalsbrowserSignals{
topWindowHostname: 'publisher.example',
interestGroupOwner: 'https://dsp.example',
renderUrl: 'https://cdn.example/render',
adComponents: ['https://cdn.com/ad-component-1', ...],
biddingDurationMsec: 12,
dataVersion: 1 /* Data-Version value from the seller's Key/Value service response. */
}
Before an auction starts, the seller finds the best contextual ad for the available ad slot. Part of its scoreAd() logic is to reject any ad that can't beat the contextual winner.
⬇︎
5. The seller and participating buyers receive realtime data from the Key/Value serviceExplainer section: Fetching Real-Time Data from the Protected Audience Key/Value service.
During an ad auction, the ad-space seller can get realtime data about specific ad creatives by making a request to a Key/Value service using the trustedScoringSignalsUrl property of auction configuration argument passed to navigator.runAdAuction(), along with the keys from the renderUrl properties of all entries in the ads and adComponents fields of all interest groups in the auction.
Likewise, an ad-space buyer can request realtime data from the Key/Value service using the trustedBiddingSignalsUrl and trustedBiddingSignalsKeys properties of the interest group argument passed to navigator.joinAdInterestGroup().
When runAdAuction() is called, the browser makes a request to each ad buyer's trusted server. The URL for the request might look like this:
https://kv-service.example/getvalues?hostname=publisher.example&keys=key1,key2
trustedBiddingSignalsUrl.hostname is provided by the browser.keys value is taken from trustedBiddingSignalsKeys.The response to this request is a JSON object providing values for each of the keys.
Key point: In the current initial experimental phase for testing Protected Audience,trustedBiddingSignalsUrl must have the same origin as the interest group owner: see Interest group properties and Bring Your Own Server.
⬇︎
6. The winning ad is displayedExplainer section: Browsers Render the Winning Ad
As described earlier: the promise returned by runAdAuction() resolves to an URN which is passed to a fenced frame for rendering, and the site displays the winning ad.
⬇︎
7. The auction result is reportedExplainer section: Event-Level Reporting (for now)
Note: The long-term plan is to enable the browser to report auction results for the seller and buyers using aggregate reporting APIs. As a temporary event-level reporting mechanism, the code implementingreportResult() for the seller, and reportWin() for the winning bidder, can call the sendReportTo() function. This takes a single argument: a string representing a URL that is fetched after the auction completes, which encodes event-level information to be reported. Seller reports outcome
Explainer section: Seller Reporting on Render
The seller's JavaScript provided at decisionLogicUrl (which also provided scoreAd()) can include a reportResult() function, to report the auction outcome.
reportResult(auctionConfig, browserSignals) {
...
return signalsForWinner;
}
The arguments passed to this function are:
auctionConfig
The auction configuration object passed to navigator.runAdAuction().
browserSignals
An object constructed by the browser providing information about the auction. For example:
{
'topWindowHostname': 'publisher.example',
'interestGroupOwner': 'https://dsp.example',
'renderUrl': 'https://cdn.example/url-of-winning-creative.wbn',
'bid:' <bidValue>,
'desirability': <winningAdScore>
}
The return value of this function is used as the sellerSignals argument for the winning bidder's reportWin() function.
Explainer section: Buyer Reporting on Render and Ad Events
The winning bidder's JavaScript (which also provided generateBid()) can include a reportWin() function to report the auction outcome.
reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
...
}
reportWin() is not defined.
The arguments passed to this function are:
auctionSignals and perBuyerSignalsgenerateBid() for the winning bidder.sellerSignalsreportResult(), which gives the seller an opportunity to pass information to the buyer.browserSignals
An object constructed by the browser providing information about the auction. For example:
{
'topWindowHostname': 'publisher.example',
'seller': 'https://ssp.example',
'interestGroupOwner': 'https://dsp.example',
'interestGroupName': 'custom-bikes',
'renderUrl': 'https://cdn.example/winning-creative.wbn',
'bid:' <bidValue>
}
There are two methods available temporarily in Chrome for auction reporting:
forDebuggingOnly.reportAdAuctionLoss()forDebuggingOnly.reportAdAuctionWin()These methods each take a single argument: a URL to fetch after the auction is completed. They can be called multiple times, in both scoreAd() and generateBid(), with different URL arguments.
Chrome only sends debug loss/win reports when an auction runs to completion. If an auction is canceled (for example, due to a new navigation) no reports will be generated.
These methods are available by default in Chrome. To be able to test the methods, enable all the Ad privacy APIs under chrome://settings/adPrivacy. If you're running Chrome with command line flags to enable Protected Audience, you'll need to explicitly enable the methods by including the BiddingAndScoringDebugReportingAPI flag. If the flag is not enabled, the methods will still be available but do nothing.
⬇︎
8. An ad click is reportedA click on an ad rendered in a fenced frame is reported. To learn more about how this might work, see Fenced Frames Ads Reporting.
The diagram below outlines each stage of a Protected Audience ad auction:
What is the difference between Protected Audience and TURTLEDOVE?Protected Audience is the first experiment to be implemented in Chromium within the TURTLEDOVE family of proposals.
Protected Audience follows TURTLEDOVE's high-level principles. Some online advertising has been based on showing an ad to a potentially-interested person who has previously interacted with the advertiser or ad network. Historically this has worked by the advertiser recognizing a specific person as they browse across web sites, a core privacy concern with today's web.
The TURTLEDOVE effort is about offering a new API to address this use case while offering some key privacy advances:
Protected Audience grew out of TURTLEDOVE and a collection of related proposals for modifications to better served the developers who would be using the API:
Protected Audience does not yet prevent a website's ad network from learning which ads a person sees. We expect to modify the API to become more private over time.
What browser configuration is available?Users can adjust their participation for Privacy Sandbox trials in Chrome by enabling or disabling the top-level setting in chrome://settings/adPrivacy. During initial testing, people will be able to use this high-level Privacy Sandbox setting to opt out of Protected Audience. Chrome plans to allow users to see and manage the list of interest groups that they have been added to across the web sites they have visited. As with the Privacy Sandbox technologies themselves, user settings may evolve with feedback from users, regulators and others.
We'll continue to update the available settings in Chrome as the Protected Audience proposal progresses, based on tests and feedback. In the future, we plan to offer more granular settings to manage Protected Audience and associated data.
API callers can't access group membership when users browse in Incognito mode, and membership is removed when users clear their site data.
Engage and share feedbackTo ask a question about your implementation, about the demo, or about the documentation:
For bugs and issues with the implementation of the Protected Audience API in Chrome: * View existing issues reported for the API. * Raise a new issue at crbug.com/new.
Get updatesPhoto by Ray Hennessy on Unsplash.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.3