Protected Audience API overview

On-device ad auctions to serve remarketing and custom audiences, without cross-site third-party tracking.

Who is this article for?

This article covers the basics of the Protected Audience API and explains some underlying concepts, but doesn't go into much technical detail.

Refer to the glossary for terms used across Protected Audience documentation. At the end of this article, you can learn how to engage and share feedback.

What is the Protected Audience API?

The Protected Audience API is a Privacy Sandbox technology to serve remarketing and custom audience use cases, designed so third parties cannot track user browsing behavior across sites.

The Protected Audience API enables on-device auctions by the browser, to choose relevant ads from 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. The difference between Protected Audience and TURTLEDOVE primarily pertain to separation of the on-device role of the ad buyer and seller. The following sections explain how the Protected Audience API works.

Protected Audience API in one minute

For a more in-depth overview of the Protected Audience API, read the Protected Audience API developer guide.

An overview of each stage of the Protected Audience API lifecycle
The Protected Audience API lifecycle.

The Protected Audience API uses interest groups to enable sites to display ads that are relevant to their users.

For example, when a user visits a site that wants to advertise its products, an interest group owner (such as a demand-side platform (DSP)) can ask the user's browser to add membership for the interest group. If the request is successful, the browser records:

  • The name of the interest group: for example, 'custom-bikes'.
  • The owner of the interest group: for example, 'https://dsp.example'.
  • Interest group configuration information to allow the browser to access bidding code, ad code, and real-time data, if the group's owner is invited to bid in an ad auction.

Later, when the user visits a site with available ad space, the ad space seller (a sell-side provider (SSP), or the site itself) can use Protected Audience to run an ad auction to select the most appropriate ads to display to the user. The seller calls the navigator.runAdAuction() function, which provides a list of interest group owners who are invited to bid.

Bids can only be provided by interest groups that the browser is a member of, whose owners have been invited to bid.

Bidding code is retrieved from a URL provided in the interest group's configuration. This code provides data about the interest group and information from the seller, along with contextual data about the page and from the browser.

Each interest group providing a bid is known as a buyer.

When the browser calls the function to run the ad auction, each buyer's code generates a bid with the help of real-time data provided by their Protected Audience Key/Value service. Then, the seller receives these bids as well as seller-owned real-time data and scores each bid. The bid with the highest score wins the auction.

The winning ad is displayed in a fenced frame. The ad creative's URL is specified in the bid, and the origin must match one in the list provided by the interest group's configuration.

The seller can report the auction outcome (reportResult()), and buyers can report their wins (reportWin()).

Learn about Protected Audience auction reports.

Why do we need the Protected Audience API?

Understanding user interests can enable more relevant ads than just choosing ads based on site content (contextual targeting) or by using information provided by a user to the site on which the ad appears (first-party data targeting).

Traditionally, ad platforms have learned about user interests by tracking their behavior across sites. Browsers need a way to enable ad platforms to select relevant ads, so content publishers can get ad revenue without cross-site tracking.

The Protected Audience API aims to move the web platform closer to a state where the user's browser on their device—not the advertiser or ad tech platforms—holds information about what that person is interested in.

How can I try the Protected Audience API?

  • The Protected Audience API developer guide describes how to use the API and how to test locally.

  • protected-audience-demo.web.app provides a walkthrough of a basic Protected Audience deployment across advertiser and publisher sites. The Protected Audience demo video explains how this code works and previews how to use Chrome DevTools for debugging.

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, users can opt out of the Protected Audience API using the Privacy Sandbox settings.

Chrome plans to allow users to see and manage the list of interest groups they've been added to across the sites they've visited. As with the Privacy Sandbox technologies, user settings may evolve with feedback from users, regulators, and others.

We'll update the available settings in Chrome as the Protected Audience API progresses, based on tests and feedback. In the future, we'll 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.

Can I opt out of the Protected Audience API?

Learn how you can block access to the Protected Audience API, either as a site owner or as an individual user.

Key concepts

Looking for more information on Protected Audience terminology? Refer to the Privacy Sandbox glossary.

What is an interest group?

A Protected Audience API interest group represents a group of people with a common interest, corresponding to a remarketing list.

Every Protected Audience API interest group has an owner. Different types of owners will create different types of interest groups with different use cases.

The owner asks the user's browser to add membership of their interest group by calling the JavaScript function navigator.joinAdInterestGroup(), providing information such as data about ads relevant to the interest group, and a URL for JavaScript used in bidding. Interest group data (such as the ads) can be updated, and an interest group can be enabled for up to 30 days.

Interest group types

The followng table provides examples of different types of Protected Audience API interest groups and owners.

Owner Example Interest Example Use cases
Advertiser Bike maker Products People who viewed product pages for a particular category of bike. Remarketing to people who have previously interacted with the brand.
Publisher News website Content People who read about cycling. Publishers can use first-party data to enable advertisers to buy ads that are relevant to readers on their site. A publisher-owned interest group could let publishers do the same even when those people are browsing other sites. Publishers may be able to charge for the ability to show ads to specific segments of their audience.
Ad tech DSP Category of products People who showed an interest in cycling gear. An ad tech company might create and manage an interest group of people they believe are in the market for some category of item. This interest group could then be used to advertise products on sites that sell things in that category (and who work with the ad tech company).

Chrome allows up to 1000 interest groups per owner, and up to 1000 interest group owners. These limits are meant as guard rails, not to be hit in regular operation.

What is a buyer?

In the Protected Audience API, a buyer is a party that owns an interest group and bids in an ad auction.

For example:

Buyers have three jobs:

  • Choose whether to participate in an auction.
  • Choose ads and calculate a bid.
  • Report the auction outcome.

These jobs are done programmatically, in code provided by the buyer that is run during a Protected Audience API ad auction.

When a buyer asks a user's browser to add an interest group to the groups it is a member of (by calling the JavaScript function navigator.joinAdInterestGroup()) the buyer provides the browser with:

  • A URL for bidding code, that will be used when the seller runs an ad auction.
  • Potentially, URLs for ad creatives for the interest group. (Ad URLs may be added later with an update.)
  • A list of data keys to be queried, and the URL of the buyer's Key/Value service, to enable bidding code to get real-time data during an auction.

The buyer's code can also include a reportWin() function to report the auction outcome.

Who runs an ad auction?

There are multiple parties that might run an auction to sell ad space.

For example:

  • Content publisher: acting for itself to host ad content on its website.
  • Supply-side platform (SSP): working with the publisher and providing other services.
  • Third-party script: acting for a publisher, to enable participation in ad auctions.

With the Protected Audience API, an ad space seller has three jobs:

  • Enforce publisher rules: stating which buyers and which bids are eligible.
  • Run auction logic: JavaScript run in worklets to calculate a desirability score for each bid.
  • Report the auction outcome.

These jobs are done programmatically, in code provided by the seller when it initiates an ad auction by calling the JavaScript function navigator.runAdAuction().

How does a Protected Audience API ad auction work?

The following diagram outlines each stage of a Protected Audience API ad auction:

Six stages in a Protected Audience API ad auction
Protected Audience ad auction stages.

In the Protected Audience API, an ad auction is a collection of small JavaScript programs the browser runs on the user's device to choose an ad. To preserve privacy, all ad auction code from the seller and buyers is run in isolated JavaScript worklets that can't talk to the outside world.

A seller (a publisher or a supply-side platform) initiates a Protected Audience ad auction on a site that sells ad space (such as a news site). The seller chooses buyers to participate in the auction, indicates what space is for sale, and provides additional criteria for the ad. Each buyer is the owner of an interest group.

The seller provides the browser with code to score bids, which includes each bid's value, the ad creative URL, and other data returned from each buyer. During the auction, bidding code from buyers and bid-scoring code from the seller can receive data from their Key/Value services. Once an ad is chosen and displayed (in a fenced frame to preserve privacy) the seller and the winning buyer can report the auction result.

  1. A user visits a site which displays ads.
  2. The seller's code starts an auction. The seller specifies which ad space is for sale and who can bid, as well as a method to score those bids.
  3. The invited buyer's code executes to generate a bid, URL for a relevant ad creative, and other data. The bidding script can query for real-time data, such as the remaining ad campaign budget, from the buyer's Key/Value service.
  4. The seller's code scores each bid and selects a winner. This logic uses the bid value and other data to return a bid's desirability and reject an ad that can't beat the contextual ad winner. The seller can use their own Key/Value service for real-time data. Before an auction starts, the seller finds the best contextual ad for the available ad slot.
  5. The winning ad is returned as a fenced frame config object when the resolveToConfig flag is set in the auction config. The config is used to navigate the fenced frame to the ad creative, and the URL of the creative is hidden from both the seller and the publisher. If the resolveToConfig flag is set to false or not passed in, the winning ad is returned as an opaque URN that can be used to render the ad in an iframe. The fenced frame config object is available starting from M114.
  6. The auction is reported to the seller and winning buyers.

A reporting mechanism for losing buyers is under discussion.

What is a Protected Audience API Key/Value service?

The Protected Audience API Key/Value service allows ad techs to query for real-time data when a bid is made by the buyer, and for sellers to score ads while preserving privacy. You can read about the Protected Audience API Key/Value service and others in Protected Audience API services.

The Key/Value service is deployed to the ad tech's own cloud infrastructure, and the service runs in a trusted execution environment. A request to a Key/Value service cannot result in event-level logging or have other side effects. The Key/Value service will also support user-defined functions (UDFs) that allow ad techs to execute their own custom logic within the Key/Value service.

A buyer or seller provides a list of 'keys' to specify the data they require from a Protected Audience API Key/Value service. The Key/Value service responds with a value for each key.

The Protected Audience API Key/Value service code is now available in a Privacy Sandbox GitHub repository. This service can be used by Chrome and Android developers.

Learn more about the Protected Audience API Key/Value service from the API explainer and the trust model explainer.

How is real-time data incorporated into auctions?

The buyers or seller in an ad auction may need access to realtime data. For example, buyers may want to calculate the remaining budget in an ad campaign, or the seller may be required to check ad creatives against publisher policies.

To meet the privacy requirements of the Protected Audience API, real-time data required during an ad auction is provided by the Key/Value service. When each buyer calls navigator.joinAdInterestGroup(), the buyer specifies a Key/Value service URL and specifies the keys to be queried to the service during an auction. Likewise, when the seller runs an ad auction by calling navigator.runAdAuction(), the seller provides a URL for its Key/Value service. The seller's Key/Value service will be queried with the render URL of the creative.

For initial testing, the "Bring Your Own Server" model is used. In the long term, ad techs will need to use the open-source Protected Audience API 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 trusted execution environments until sometime after third-party cookie deprecation. We will provide substantial notice for developers to begin testing and adoption before this transition takes place.

How is first-party data used in a Protected Audience auction?

First-party data is data owned by the site on their users. For example, if a user has specified their favorite color on the advertiser's or publisher's site, that color is considered first-party data.

In a Protected Audience auction, the advertiser can use their first-party data to determine the ad interest group membership, and can also pass data into the interest group as userBiddingSignals. The first-party data from the advertiser will be available only for the buyers during the bid generation step, and is not available for the sellers.

For example, if the advertiser knows the user's favorite color, the value can be set in the interest group config as userBiddingSignals when the user is added to an interest group:

const interestGroup = {
  owner: 'https://example-buyer.com',
  name: 'running-shoes',
  userBiddingSignals: {
    favoriteColor: 'blue' // First-party data
  },
  // ...other interest group settings
};

navigator.joinAdInterestGroup(interestGroup, 3600);

The publisher can also pass in their first-party data by setting the signals in the auction config when initiating the auction, and can control who receives the first-party data. When a publisher passes the first-party data in as auctionSignals, it is available to both buyers and sellers. When the data is passed in as sellerSignals, it is available only to the seller, and when passed in as perBuyerSignals, it is available only to the specified buyers. The publisher can also pass in first-party data to component auctions. The publisher and the auction participants should agree before on what first-party data needs to be shared, and how the data needs to be formatted.

The following example describes how the first-party data can be passed in by the publisher to various auction participants:

const auctionConfig = {
  seller: 'https://example-seller.com',
  auctionSignals: {
    favoriteColor: 'blue', // Both buyer and seller will receive this signal
  },
  sellerSignals: {
    favoriteIceCreamFlavor: 'chocolate', // Only the seller will receive this signal
  },
  perBuyerSignals: {
    'https://example-buyer.com': {
      favoriteDrink: 'tea', // Only a specific buyer will receive this signal
    },
  },
  // The same pattern applies to the component auction
  componentAuctions: [{
    seller: 'https://example-component-seller.com',
    auctionSignals: { ... },
    sellerSignals: { ... },
    perBuyerSignals { ... }
  }],
  // ...other auction settings
};

navigator.runAdAuction(auctionConfig);

Find out more

For a more in-depth overview of the Protected Audience API, read the Protected Audience API developer guide.

Developers

If you're ready to start working with the Protected Audience API, read experiment and participate.

We've written an API developer guide and built a Protected Audience API demo, which offers a walkthrough of a basic Protected Audience API deployment. The Protected Audience API demo video explains how the demo code works, and shows how to use Chrome DevTools for Protected Audience API debugging.

Engage and share feedback