Developer guide for on-device ad auctions to serve remarketing and custom audiences, without cross-site third-party tracking.
For those new to the Protected Audience API, read the Protected Audience API overview for a high-level explanation of the API.
This post is written for developers as a technical reference for the most recent iteration of the experimental Protected Audience API. A demo of a basic Protected Audience API deployment is available, as are API references for ad buyers and sellers.
Implementation status
- The Protected Audience API proposal is now moving to general availability. Raise questions and follow discussion.
- Protected Audience API status of pending capabilities details changes and enhancements to the Protected Audience API API and features.
- Blink status
- Protected Audience API Chrome platform status: Specific to the Protected Audience API on Chrome.
- Ads API Chrome platform status: A collection of APIs to facilitate advertising: Protected Audience API, Topics, Fenced Frames and Attribution Reporting.
To be notified of status changes in the API, join the mailing list for developers.
What is the Protected Audience API?
The Protected Audience API is a Privacy Sandbox API designed 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.
The Protected Audience API is the first experiment to be implemented in Chromium within the TURTLEDOVE family of proposals.
Try the Protected Audience API
Available API reference
This document serves as an overview of the Protected Audience API. If you're looking for specific API methods and parameters:
- Buyers guide for
joinAdInterestGroup()
andgenerateBid()
. - Seller's guide for the Protected Audience API
runAdAuction()
- Buyers guide to
reportWin()
and sellers guide toreportResult()
- Troubleshoot the Protected Audience API
You can also read Protected Audience API ad auction latency best practices.
Protected Audience API demo
A walk-through of a basic Protected Audience API deployment across advertiser and publisher sites is available at protected-audience-demo.web.app/.
Test this API
You can test the Protected Audience API for a single user in Chrome Beta 101.0.4951.26 and above on desktop:
- Enable all the Ad privacy APIs under
chrome://settings/adPrivacy
. - Set flags from the command line. The full list of available Protected Audience API flags can be found in Chromium Code Search.
Render ads in iframes or fenced frames
Ads 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
temporary debug loss/win reporting methods.
Supported features
Protected Audience API behind feature flags in Chromium is a first experiment to test the following features of the Protected Audience API:
- Interest groups: stored by the browser, with associated metadata to configure ad bidding and rendering.
- On-device bidding by buyers (DSP or advertiser): based on stored interest groups and signals from the seller.
- On-device ad selection by the seller (SSP or publisher): based on auction bids and metadata from buyers.
- Ad rendering in a temporarily relaxed version of Fenced Frames: with network access and logging allowed for ad rendering.
Read more about feature support and constraints in the Protected Audience API explainer.
Interest group permissions
The default for the current implementation of the Protected Audience API 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 update their cross-domain iframe permissions policies, the plan is to disallow calls from cross-domain iframes.
Key/Value service
To support the Protected Audience API ad auction, the browser can access a key/value service to retrieve real-time information which supports the Protected Audience API ad auction. This information could be used in a number ways:
- Buyers may want to calculate the remaining budget in an ad campaign.
- Sellers may be required to check ad creatives against publisher policies.
The Protected Audience API key/value service code is now available. Check out the announcement blog post for the status update.
For initial testing, a "Bring Your Own Server" model was introduced. In the long-term, ad techs will need to use the open-source Protected Audience API Key/Value services running in trusted execution environments.
Refer to the Protected Audience API services blog post for timeline updates. We'll provide substantial notice for developers to begin testing and adoption before this transition takes place.
Detect feature support
Before 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');
How does the Protected Audience API work?
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.
Features of the Protected Audience API will be added over time as work on implementation progresses.
1. A user visits an advertiser site
![A person visiting a custom bike manufacturer site in a browser on their laptop.](https://developers.google.cn/static/privacy-sandbox/assets/images/a-person-visiting-custom-2ca7094e57259.png?authuser=7)
Imagine 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.
2. The user's browser is asked to add an interest group
![A user opens a browser on their laptop and visits a site. JavaScript
code for joining ad interest groups is running in the browser.](https://developers.google.cn/static/privacy-sandbox/assets/images/a-user-opens-browser-th-6c2a4e6d97af7.png?authuser=7)
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 Protected Audience API ad auction. Interest group membership is stored by the browser,
on the user's device, and is not shared with the browser vendor or anyone else.
- Read the Protected Audience API explainer: Browsers Record Interest Groups.
- Read the API guide: buyers and DSPs, learn how to
joinAdInterestGroup()
and generate bids.
Specify ads for an interest group
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
}
How do buyers make bids?
generateBid()
is called for each interest group that the browser is a member
of—if the interest group's owner is invited to bid.
Read the generatedBid()
developer documentation.
3. The user visits a site that sells ad space
![A person visits a news website in a browser on their laptop. The site
has an empty ad slot.](https://developers.google.cn/static/privacy-sandbox/assets/images/a-person-visits-news-web-3209fc4021a42.png?authuser=7)
Later, the user visits a site that sells ads space, in this example a news website. The site has ad inventory, which it sells programmatically with real-time bidding.
4. A ad auction is run in the browser
![A person views a news website in a browser on their laptop. A Protected Audience API ad auction is run to pick an ad for the available ad space.](https://developers.google.cn/static/privacy-sandbox/assets/images/a-person-views-news-webs-32cbfd93dc442.png?authuser=7)
The ad auction is likely to be run by the publisher's supply-side provider (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.
- Read the Protected Audience API explainer: Sellers Run On-Device Auctions
- Read the API guide: sellers can learn more about
runAdAuction()
and the ad auction latency best practices.
5. The seller and participating buyers request real-time data from the Key/Value service
![The user views a news website in a browser on their laptop. An ad
auction using the Protected Audience API is taking place, with a participant getting data from the Key/Value service.](https://developers.google.cn/static/privacy-sandbox/assets/images/the-user-views-news-webs-6969c01094b4.png?authuser=7)
During an ad auction, the seller can request real-time data about specific ad
creatives by making a request to their Key/Value service.
The seller can request this information during
runAdAuction()
by the trustedScoringSignalsUrl
property,
along with the keys from the renderUrl
properties of all entries in the ads
and adComponents
fields of all interest groups in the auction.
A buyer can request real-time data from their 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
- The base URL comes from
trustedBiddingSignalsUrl
. - The
hostname
is provided by the browser. - The
keys
value is taken fromtrustedBiddingSignalsKeys
.
The response to this request is a JSON object providing values for each of the keys.
- Read the Protected Audience API explainer: Fetching Real-Time Data from the Protected Audience API Key/Value service.
- Read open sourcing the Protected Audience API Key/Value service.
6. The winning ad is displayed
![A person views a news website in a browser on their laptop. An ad
for 20% off a bike is displayed in a secure fenced frame.](https://developers.google.cn/static/privacy-sandbox/assets/images/a-person-views-news-webs-2dc1236041c17.png?authuser=7)
The promise returned by runAdAuction() resolves to a fenced frame config object (FencedFrameConfig
) when theresolveToConfig
flag is set to true
in the auction config. The frame config is used by a fenced frame to navigate the frame to the winning ad, but the URL of the ad is not visible to the frame embedder.
Fenced frame config object is available starting from M114. For more on the FencedFrameConfig
object, see the Chrome blog article.
- Read the Protected Audience API explainer: browsers render the winning ad
7. The auction result is reported
The long-term plan is to allow the browser to report auction results for the seller and buyers using the Private Aggregation APIs.
As a temporary event-level reporting mechanism, the code implementing
reportResult()
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.
- Read the API guide: learn about seller and buyer reporting
8. An ad click is reported
![A person clicks on an ad for a bike, embedded with a fenced frame, on a news website. The report data is sent to seller and buyers.](https://developers.google.cn/static/privacy-sandbox/assets/images/a-person-clicks-an-ad-a-be2111724646f.png?authuser=7)
A click on an ad rendered in a fenced frame is reported. To learn more about how this might work, see Fenced Frames Ads Reporting.
![An overview of each stage of a Protected Audience API ad auction](https://developers.google.cn/static/privacy-sandbox/assets/images/an-overview-each-stage-c8bac3c2c070f.png?authuser=7)
What is the difference between the Protected Audience API and TURTLEDOVE?
The Protected Audience API is the first experiment to be implemented in Chromium within the TURTLEDOVE family of proposals.
The Protected Audience API 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:
- The browser, not the advertiser, holds the information about what the advertiser thinks a person is interested in.
- Advertisers can serve ads based on an interest, but cannot combine that interest with other information about a person—in particular, who they are or what page they are visiting.
The Protected Audience API grew out of TURTLEDOVE and a collection of related proposals for modifications to better served the developers who would be using the API:
- In SPARROW: Criteo proposed the addition of a ("Gatekeeper") service model running in a trusted execution environment (TEE). The Protected Audience API includes a more limited use of TEEs, for real-time data lookup and aggregated reporting.
- NextRoll's TERN and Magnite's PARRROT proposals described the different roles that buyers and sellers had in the on-device auction. The Protected Audience API's ad bidding/scoring flow is based on this work.
- RTB House's Outcome-based and Product-level TURTLEDOVE modifications improved the anonymity model and personalization capabilities of the on-device auction
- PARAKEET is Microsoft's proposal for a TURTLEDOVE-like ad service that relies on a proxy server running in a TEE between the browser and the ad tech providers, to anonymize ad requests and enforce privacy properties. The Protected Audience API has not adopted this proxying model. We are bringing the JavaScript APIs for PARAKEET and the Protected Audience API into alignment, in support of future work to further combine the best features of both proposals.
The Protected Audience API 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.
Can the Topics API be used with the Protected Audience API?
Yes. An observed topic for the current user, provided by the Topics API, could be used as contextual information by a seller or bidder. A topic could be included in the following properties:
auctionSignals
, a property of the auction configuration object passed tonavigator.runAdAuction()
userBiddingSignals
, a property of the interest group configuration object passed tonavigator.joinAdInterestGroup()
Available browser configuration
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 the Protected Audience API. 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 based on tests and feedback. In the future, we plan to offer more granular settings to manage the Protected Audience API 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.
Are the Protected Audience worklets cached by the browser?
The resources that contain the Protected Audience worklets—the buyer's bid generation and reporting worklets, and seller's ad scoring and reporting worklets—are cached by the browser. You can use the Cache-Control
header to control the caching behavior.
Engage and share feedback
Get support
To ask a questions and get support with your implementation, the demo, or the documentation:
- GitHub: Read the explainer, raise questions, and follow discussion.
- Demo: Raise an issue on the demo code repository.
- Developer support: Ask questions and join discussions on the Privacy Sandbox Developer Support repo. Select the issue template for the Protected Audience API.
- Chrome implementation: for bugs or issues with Chrome's implementation of the Protected Audience API, you can view existing issues or raise a new issue.
For more general questions about meeting your needs with the Protected Audience API, file an issue on the API repository. You can also discuss industry use cases in the W3C's Improving Web Advertising Business Group.
Use the Privacy Sandbox feedback form to share feedback privately with the Chrome team outside of public forums.
Opt-out
Want to opt-out of the Protected Audience API? Learn how to block access to the Protected Audience API, as a site owner or an individual user.
Get updates
- For notifications of API status changes, join the mailing list for developers.
- To closely follow all ongoing discussions on the API, click the Watch button on the API page on GitHub. This requires you have or create a GitHub account.
- To get overall updates on the Privacy Sandbox, subscribe to the RSS feed [Progress in the Privacy Sandbox].
- Join the scheduled calls for the Protected Audience API (every second week). Everyone is welcome to join—to participate, first make sure to join the WICG. You can actively participate or just listen in!