FLEDGE API: developer guide

Developer guide for on-device ad auctions to serve remarketing and custom audiences, without cross-site third-party tracking.

Published on Updated on

For those new to FLEDGE, read the FLEDGE overview for a high-level explanation of the proposal.

This post is written for developers as a technical reference for the most recent iteration of the experimental FLEDGE API. A demo of a basic FLEDGE deployment is available, as are API references for ad buyers and sellers.

What is FLEDGE?

FLEDGE 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.

FLEDGE is the first experiment to be implemented in Chromium within the TURTLEDOVE family of proposals.

Try FLEDGE

Available API reference

This document serves as an overview of the FLEDGE API. If you're looking for specific API methods and parameters:

You can also read FLEDGE ad auction latency best practices.

FLEDGE demo

A walk-through of a basic FLEDGE deployment across advertiser and publisher sites is available at fledge-demo.glitch.me.

Watch this end-to-end deployment to learn how the FLEDGE demo code works and how to use Chrome DevTools for debugging.

Take part in the origin trial

The Privacy Sandbox Relevance and Measurement origin trial has been made available in Chrome Beta 101.0.4951.26 and above on desktop for the FLEDGE, 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 FLEDGE 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.

Provide a trial token for every page on which you would like to run FLEDGE 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 FLEDGE code—such as a navigator.joinAdInterestGroup() call by an interest group owner—will need to provide a token that matches its origin.

Proposed First FLEDGE Origin Trial Details provides more details about the goals of the first trial and explains what features are supported.

Caution

Not all users are eligible for the Privacy Sandbox Relevance and Measurement origin trial, even on pages that provide a valid trial token.

The Relevance and measurement unified origin trial overview explains why this is so, and shows how you can (and should) detect if an origin trial feature is available before attempting to use it.

Test with chrome://flags or feature flags

You can test FLEDGE for a single user in Chrome Beta 101.0.4951.26 and above on desktop:

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.

This is an in-progress version of FLEDGE for early testing. It shouldn't be considered complete or indicative of the final implementation. FLEDGE progress and status are discussed in the regular WICG meetings.

The Privacy Sandbox timeline provides implementation timing for FLEDGE and other Privacy Sandbox proposals.

Supported features

FLEDGE behind feature flags in Chromium is a first experiment to test the following features of the FLEDGE proposal:

  • 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 FLEDGE API explainer.

Interest group permissions

The default for the current implementation of FLEDGE 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 FLEDGE ad auction, the browser can access a key/value service to retrieve real-time information which supports the FLEDGE 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 FLEDGE 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, adtechs will need to use the open-source FLEDGE Key/Value services running in trusted execution environments.

Refer to the FLEDGE 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');
Caution

Feature support on the current page isn't a guarantee that an API is usable. The user may have disabled the API via browser settings, or they may have other settings that prevent the API from being used. In order to protect user privacy, there is no way to check for this programmatically.

How does the FLEDGE 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.

Warning

Not all features described in this post have been implemented (or fully implemented) in the version of the FLEDGE API currently being tested in Chrome. Test with feature flags explains what FLEDGE features are currently available for testing in Chrome run from the command line.

Features of FLEDGE 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.

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.

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 FLEDGE 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.

The origin of the calling context for joinAdInterestGroup() must match the interest group owner's origin.

joinAdInterestGroup() must be called from an iframe owned by the interest group owner (for example, from a DSP). If the origin of the current document is the same as the interest group owner (for example, a website with its own interest groups), no iframe is needed.

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.

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 FLEDGE ad auction is run to pick an ad for the available ad space.

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.

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 FLEDGE API is taking place, with a participant getting data from the Key/Value service.

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 from trustedBiddingSignalsKeys.

The response to this request is a JSON object providing values for each of the keys.

Gotchas

While in the initial experimental phase of testing FLEDGE, trustedBiddingSignalsUrl must have the same origin as the interest group owner. Learn more in Bring Your Own Server.

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.

The promise returned by runAdAuction() resolves to a Uniform Resource Identifier (URN). This URN is embedded on the site in a fenced frame and renders 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 API 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.

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.

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 FLEDGE ad auction
This diagram outlines each stage of a FLEDGE auction. View a larger version.

What is the difference between FLEDGE and TURTLEDOVE?

FLEDGE is the first experiment to be implemented in Chromium within the TURTLEDOVE family of proposals.

FLEDGE 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.

FLEDGE 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). FLEDGE 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. FLEDGE'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 adtech providers, to anonymize ad requests and enforce privacy properties. FLEDGE has not adopted this proxying model. We are bringing the JavaScript APIs for PARAKEET and FLEDGE into alignment, in support of future work to further combine the best features of both proposals.

FLEDGE 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.

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/privacySandbox.

During initial testing, people will be able to use this high-level Privacy Sandbox setting to opt-out of FLEDGE. 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 FLEDGE proposal progresses, based on tests and feedback. In the future, we plan to offer more granular settings to manage FLEDGE 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 feedback

Get support

To ask a questions and get support with your implementation, the demo, or the documentation:

For more general questions about meeting your needs with FLEDGE, file an issue on the proposal 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 FLEDGE? Learn how to block access to the FLEDGE API, as a site owner or an individual user.

Get updates

Updated on Improve article

We serve cookies on this site to analyze traffic, remember your preferences, and optimize your experience.