Test the Privacy Sandbox ads relevance and measurement APIs

Published on Thursday, March 31, 2022 • Updated on Thursday, January 5, 2023

Rowan is a Staff Developer Relations Engineer at Chrome.

See updated guidance for the Relevance and measurement unified origin trial.

The Privacy Sandbox includes a selection of proposals to enable advertising use cases without the need for cross-site tracking. Origin trials provide the opportunity for developers to evaluate and provide feedback on new web technologies through real-world testing. In previous origin trials sites have been able to test against individual APIs. For the Topics, FLEDGE and Attribution Reporting APIs we are providing a single origin trial that allows sites to run unified experiments across the APIs making up an initial version of the end-to-end ad lifecycle. The APIs are available for testing in Chrome 101 Beta and above. The Chrome 101 Beta release also sees updates to the user controls as we continue to iterate on configuration options.

As a developer you will be able to sign up for this single origin trial that will allow you to test across the Topics, FLEDGE, and Attribution Reporting APIs. This guide takes you through the configuration steps to access the APIs, explains how to validate your configuration, and provides further resources for testing against the APIs.

What's in the origin trial?

The aim of this origin trial is to allow for meaningful testing across the ad lifecycle over multiple sites. To cover this journey, the origin trial includes:

Topics to observe and access a browser's topics via document.browsingTopics().
FLEDGE to manage a browser's interest groups, along with ad bidding and selection based on those groups and other signals.
- In this origin trial, FLEDGE is available on desktop and includes a specific subset of all the proposed functionality. Read the FLEDGE origin trial details for more information.
Fenced frames to render the opaque URL of the FLEDGE ad auction winner.
Attribution Reporting to measure and report on the performance over the ad lifecycle.
- As part of Attribution Reporting, aggregatable reports must be processed and aggregated by an aggregation service to produce summary reports. We will publish additional tools and guides for local and origin trial testing soon.
- If you have participated in previous origin trials for Attribution Reporting, be aware that you will need to update inline with the latest API changes. Refer to the Migration guide for details.

While this setup allows for unified testing across all these APIs, you can pick and choose which aspects to implement—as much or as little as fits your needs.

Register for the Privacy Sandbox Relevance and Measurement trial. With the following HTML tags, provide a trial token on every page that you would like to run API code:

<meta> tag in the top-level page's <head> section: <meta http-equiv="origin-trial" content="TOKEN_GOES_HERE">
HTTP header in the top-level page response: Origin-Trial: TOKEN_GOES_HERE

Some functionality available in the origin trial is intended for use in cross-site contexts, as in when you are providing a service as a third-party on the top-level site. If you need to enable your origin trial for these additional contexts, ensure that you select the option for "Third-party matching". To enable the origin trial from third-party JavaScript, inject the <meta> tag into the top-level page (i.e. the first-party page, not your own content) from your script. For example:

const otMeta = document.createElement('meta');
otMeta.setAttribute('http-equiv', 'origin-trial');
otMeta.setAttribute('content', 'TOKEN_GOES_HERE');
document.querySelector('head').appendChild(otMeta);

Learn more in the guide to getting started with Chrome's origin trials.

Caution

An iframe accessing a trial feature (such as FLEDGE's joinAdInterestGroup()) must provide a token that matches its origin.

How do developers test locally?

The individual developer documentation for Topics, FLEDGE, and Attribution Reporting provide specific guidance on local developer testing for each API. The APIs are not on by default and must be enabled with flags for testing.

To enable APIs for testing, you must:

Use Chrome 101 Beta or above.
- FLEDGE requires desktop Chrome.
- APIs are not available on iOS versions of Chrome.
Enable the APIs using the chrome://flags/#privacy-sandbox-ads-apis flag.
- This flag forces the APIs on for easier testing, if you want to replicate an eligible origin trial user where their additional settings can still disable the APIs, then you should launch Chrome using the CLI flags: --enable-features=BrowsingTopics,InterestGroupStorage,AllowURNsInIframes,PrivacySandboxAdsAPIs.
- Individual APIs may have more additional flags for more fine-grained configuration, check the individual guides for details.
- Additional flags may conflict with this one, so consider only setting this one flag if you encounter issues.
Enable the Privacy Sandbox trials in Chrome Settings: Settings > Security and privacy > Privacy Sandbox. This is also accessible at chrome://settings/privacySandbox.
Enable third-party cookies in Chrome Settings: Settings > Security and privacy. Set Cookies and other site data to either "Allow all cookies" or "Block third-party cookies in Incognito". This is also accessible at chrome://settings/cookies.
Be in a standard browsing session. Do not use Incognito mode.

How do developers check if the origin trial is configured correctly?

Troubleshooting Chrome's origin trials provides a detailed checklist to validate your configuration of the origin trial.

DevTools showing origin trial status under Applications > Frames

DevTools shows the status for an origin trial in the Applications tab under Frames.

While the origin trial will only show as active to eligible users as detailed below, you can also use the developer flags to test against your own production site.

What users are eligible for the origin trial?

By design, origin trials are intended to only run on a small portion of overall Chrome traffic and as such you should always assume that even when you have enabled the origin trial on your site, the user may not have the API active. The active experiment group in the origin trial will start with a low proportion of users and likely ramp up as the trial progresses. Be aware that the percentage of Chrome users in the experiment may not match the percentage of enabled users on your site.

However, to allow for unified testing across sites, that set of eligible users should remain mostly consistent. For example, if a user is eligible for the origin trial when they view an ad on a participating publisher site, that same user should still be eligible when they convert on a participating advertiser site.

For a user to be eligible, they must:

be using Chrome 101 Beta or above.
- FLEDGE requires desktop Chrome.
- no origin trials are available on iOS versions of Chrome.
be browsing during the active origin trial period.
have the Privacy Sandbox trials enabled via Settings > Security and privacy > Privacy Sandbox, also accessible via chrome://settings/privacySandbox.
have third-party cookies enabled via Settings > Security and privacy > Cookies and other site data set to either "Allow all cookies" or "Block third-party cookies in incognito", also accessible via chrome://settings/cookies.
be in a standard browsing session and not Incognito mode.
be within the active experiment group in Chrome.

How should developers feature detect API support?

As with any web platform feature, you should detect support for the feature before using it.

Topics

Check for the browsingTopics() function in the document and the Permissions Policy](/docs/privacy-sandbox/permissions-policy/#featurepolicyallowsfeaturefeature) for "browsing-topics".

if ('browsingTopics' in document && document.featurePolicy.allowsFeature('browsing-topics')) {
  // Topics enabled
}

FLEDGE

If you want to join an ad interest group, check for the joinAdInterestGroup function in navigator and the Permissions Policy for "join-ad-interest-group".

if ('joinAdInterestGroup' in navigator && document.featurePolicy.allowsFeature('join-ad-interest-group')) {
  // FLEDGE interest group enabled
}

If you want to run an auction, check for the runAdAuctionfunction in navigator, and the permissions policy for "run-ad-auction".

if ('runAdAuction' in navigator && document.featurePolicy.allowsFeature('run-ad-auction')) {
  // FLEDGE auction enabled
}

Attribution Reporting

Check for the attributionReporting object in the window and the Permissions Policy for "attribution-reporting".

if (document.featurePolicy.allowsFeature('attribution-reporting')) {
  // Attribution Reporting API enabled
}

Where can developers give feedback and get support?

The feedback overview page details the various routes for giving feedback on different aspects of the Privacy Sandbox. There are specific sections for Topics, FLEDGE, and Attribution Reporting which provide the individual links for each API.

We also provide regular updates on the Progress in the Privacy Sandbox series which provides a summary of important news.

Privacy Origin Trials

Updated on Thursday, January 5, 2023 • Improve article

Test the Privacy Sandbox ads relevance and measurement APIs

# What's in the origin trial?

# How do developers sign up for the origin trial?

# How do developers test locally?

# How do developers check if the origin trial is configured correctly?

# What users are eligible for the origin trial?

# How should developers feature detect API support?

# Topics

# FLEDGE

# Attribution Reporting

# Where can developers give feedback and get support?