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 an opportunity for developers to evaluate and provide feedback on new web technologies through real-world testing. The Privacy Sandbox Relevance and Measurement origin trial provides a single trial allowing sites to run unified experiments across Attribution Reporting, FLEDGE, Topics, Fenced Frames, and Shared Storage.

Developers can sign up for this single origin trial that allows you to test across the Topics, FLEDGE, and Attribution Reporting APIs. This guide takes you through the configuration steps to access the APIs, tells you how to validate your configuration, and provides further resources for testing against the APIs.

# Check the status of the origin trial

# March 2023

# Timeline update

We initially communicated that we will begin the isolated experiments on Monday, March 13, 2023, but the new experiments will now begin on Thursday, March 16, 2023 due to the additional time needed for setting up the experiments. The 1% FLEDGE ramp back up from 4% to 5% will also occur on Thursday, March 16, 2023.

# FLEDGE 1% ramp back up

Last month, we temporarily reduced FLEDGE origin trial traffic from 5% to 4% of Chrome stable for testing. The initial testing has concluded, and we plan to ramp FLEDGE back up to 5% from 4% for the unified experiment on Thursday, March 16, 2023.

The ramped-up users will be the same set of users that were ramped down. However, their previous interest groups have expired, since more than 30 days have passed since the ramp-down.

# Isolated experiments

To improve our testing process and continue observing the metrics of origin trial APIs, we're creating isolated experiments for each API, in addition to the existing unified experiment. New experiments will be created for Attribution Reporting, Topics, a combination of FLEDGE and Fenced Frames, and a combination of Shared Storage’s URL Selection operation and Fenced Frames. In each isolated experiment, only the assigned APIs will be available for the users in that group.

Starting Thursday, March 16, you will begin to receive an additional 1% of the Chrome Stable traffic for the APIs listed above, on top of the 5% traffic you are receiving from the existing unified experiment. New users will be allocated to each experiment.

# Traffic allocation

The current unified origin trials traffic allocation as of Tuesday, February 28, is as follows:

The traffic allocation will look like the following starting on Thursday, March 16, after FLEDGE is ramped back up, and the new isolated experiments begin:

These changes will not affect your existing origin trial token setup, and you will not have to renew or generate a new origin trial token.

# January 2023

As part of a Chrome regression investigation, we will temporarily reduce FLEDGE origin trial traffic from 5% to 4% of Chrome Stable, from January 26th 2023. We estimate the investigation will take about a month, and we will notify you when the traffic is ramped back up.

This change will happen automatically, and will not impact your existing origin trial tokens. For the users in the 1% traffic that will ramp down, the interest groups will remain in their browsers. The same users will be part of the ramp back up, and their interest groups can be reused. However, the interest groups expire in 30 days, and the regression investigation may take longer than that.

Also, Shared Storage’s URL Selection API origin trial will be increasing to 5% of Chrome Stable traffic from January 26th 2023.

# Sign up for and configure the origin trial

To activate the origin trial on your site, you will need to register and embed the assigned origin trial token (a time-based string for your specific access to the origin trial). Learn more in the Getting started with Chrome's origin trials.

Origin trial tokens are granted immediately, and you can revoke or recreate them at any time.

For every page where you want to use the origin trial, you will need to include a trial token with that specific page's HTML or response.

Use a <meta> tag in the page's <head> section:

<meta http-equiv="origin-trial" content="TOKEN_GOES_HERE">

Alternatively, include the following HTTP header in the page response:

Origin-Trial: TOKEN_GOES_HERE

# Configure with an iframe

If you're using origin trial features within an iframe (such as FLEDGE's joinAdInterestGroup()), then the token needs to be provided within the iframe and match the iframe's origin.

# Configure cross-site with JavaScript

If you are using origin trial features via cross-site JavaScript, as in you are the provider of third-party JavaScript that is included in the top-level page, then you will need to:

• Select the Third-party matching option when registering for the origin trial.
• The Web Origin field should be the origin of your script.
• Inject the <meta> tag into the top-level page (that is, 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);

# Debug the origin trial

You can check the status for an origin trial in DevTools > Applications panel.

1. Scroll down to the Frames pane.
2. Select the frame where you expect to set the token. For example, the top frame for the top-level page or the specific iframe for embedded pages.
3. In the right-hand pane scroll down to the Origin Trials section.
4. You should see an entry for the PrivacySandboxAdsAPIs trial.
5. Expand this entry to see the status for the origin trial and your specific tokens.

The origin trial is limited to a fraction of Chrome users and your browser may not be in the experiment group. As a result, you may see a red TrialNotAllowed message against PrivacySandboxAdsAPIs. When you expand the entry to check Token Status, if it shows a green Success message, your origin trial configuration is correct. Eligible users will see the message set to Enabled.

If you see different messages, refer to Troubleshooting Chrome's origin trials for a detailed checklist to validate your configuration of the origin trial.

# Detect features

As with all web features, you should check they are reporting as available in the browser before attempting to use them. You can do this by checking for the existence of the relevant API in the right location:

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

if ('runAdAuction' in navigator) {
  // FLEDGE enabled
}

if ('browsingTopics' in document) {
  // Topics enabled
}

if ('HTMLFencedFrameElement' in window) {
  // Fenced Frames enabled
}

if ('sharedStorage' in window) {
  // Shared Storage enabled
}

if (window?.sharedStorage?.selectURL instanceof Function) {
  // optionally check specifically for the selectURL function in Shared Storage
}

# Determine user eligibility

The origin trial is running for a fraction of Chrome users. They must also have the relevant functionality enabled in their settings to be eligible for the trial:

# Browser settings

For a user to be eligible for the trial, they must:

• Be using a version and channel of Chrome where the origin trial is running.

  • See Origin Trial Status for current configurations.

• Be within the active experiment group in Chrome.

# User settings

For a user to be eligible for the trial, they must also:

• have the Privacy Sandbox trial 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.

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

# Control your participation in the origin trial

The mechanics of the origin trial remain the same: you obtain origin trial tokens for the contexts where you want to experiment with the APIs. With the expanded testing population, you should ensure that you are actively monitoring and controlling the level of traffic where you choose to enable the trial.

A good approach here is to:

1. Include the origin trial tokens by default in all contexts where you wish to experiment.
2. Use feature detection to check for active APIs.
3. If the APIs are active (and therefore, the browser is eligible for this experiment), choose whether or not to use them based on your own experiment criteria. For example, if you already have A/B testing infrastructure to experiment on a percentage of traffic, sampling, or some other attribute, then at this point you can decide which features you will actively use.

You can prevent participation in the origin trial entirely for any browser instance by not including the token in the response. For instance, if you have met your own quota for an experiment or need to address an issue during the trial, then not including the token ensures no experimental functionality will be available or active in the page.

# Origin trial control by geographic region

You cannot opt-out of an origin trial for specific regions. Origin trials are active on pages that contain the token, included via HTTP headers (server-side) or HTML meta tags (client-side).

If you can determine the user's location, then you could write code to include the origin trial token based on that location information. For example, you could attempt to use IP addresses to determine a user's location. IP addresses can be spoofed, so this is not a guaranteed solution.

However, a geographic-specific origin can set a Permissions Policy to control what features are usable. For example, us.example.com and uk.example.com are geographic-specific origins which can be controlled. This does not mean that a region has opted-out of the origin trial.

With a Permissions Policy, a site adds a little snippet of code to their pages that provides instructions to the browser. When the page loads, the browser reads the Permission Policy instructions and will allow or block features (or APIs) as outlined in the Permissions Policy. If a site wants to restrict an API in a specific region, the developer could set a policy for all pages requested from that region.

# Renew your token

Origin trial tokens expire six weeks from their issue date (or at the end of the trial if that's sooner).

It’s critical that you renew and deploy your new tokens within that window for uninterrupted use of the origin trial features.

Renewing tokens only takes a few minutes, and you can deploy multiple tokens for the same trial within the same page. You can deploy a renewed token before your existing token expires, so there's no break in service for users.

# Test locally

For specific guidance on local developer testing, see:

• Topics
• FLEDGE
• Attribution Reporting

The APIs are not on by default and must be enabled with flags for testing. You should ensure that you have the same configuration settings enabled above and then:

• Use a version and channel of Chrome where the features are available.
• Enable the chrome://flags/#privacy-sandbox-ads-apis flag.
  • Additional flags may conflict with this one, so consider only setting this one flag if you experience issues.

Check the developer guides for availability of specific APIs and features and additional flags for more fine-grained configuration.