Topics API demos

# Implementation status

• The Topics API proposal has completed the public discussion phase and is currently available in an origin trial. The API is now approaching launch for scaled adoption.
• To provide your feedback on the Topics API, create an Issue on the Topics explainer or participate in discussions in the Improving Web Advertising Business Group. The explainer has a number of open questions that still require further definition.
• The Privacy Sandbox timeline provides implementation timelines for the Topics API and other Privacy Sandbox proposals.
• Topics API: latest updates details changes and enhancements to the Topics API and implementations.

The Topics API demo provides a look at how topics are inferred from hostnames. You can preview what topics are observed when you visit a demo site, which requires very little setup.

If you want to test the API with your users, sign up for the Relevance and Measurement origin trial.

Our demo is a preview that demonstrates most features of the Topics API, for you to gain familiarity with how the API is implemented.

You can also run the Topics colab to try out the Topics classifier model.

The following video shows how the demo works.

# Test with chrome://flags or feature flags

There are two ways to try the Topics API as a single user; you'll need to be running Chrome 101 or above:

• Enable the API in the chrome://flags/#privacy-sandbox-ads-apis Chrome page:

  

• Run Chrome from the command line with the following flags:

  --enable-features=BrowsingTopics,PrivacySandboxAdsAPIsOverride,OverridePrivacySandboxSettingsLocalTesting

# The Topics API demo

The Topics demo shows how to use additional flags to adjust settings, such as epoch length. If you access the Topics API by running Chrome with command-line flags, don't set chrome://flags, as these can override command-line settings.

Run Chromium with flags explains how to set flags when running Chrome and other Chromium-based browsers from the command line, although this demo is specific to Google Chrome.

# The Topics API headers demo

The demo at topics-fetch-demo.glitch.me shows how to use fetch() request and response headers to access topics and mark them as observed.

# Access the Sec-Browsing-Topics request header

Instead of using document.browsingTopics() from an iframe to view topics for a user, API callers can access observed topics from the Sec-Browsing-Topics request header of a fetch() request that includes {browsingTopics: true} in its options parameter—or from the same header of an XHR request that sets the deprecatedBrowsingTopics attribute to true.

For example:

fetch('https://topics-server.glitch.me', {browsingTopics: true})
    .then((response) => {
        // Process the response
 })

In browsers that support the API, the fetch() request will include a Sec-Browsing-Topics header that lists topics observed for the request URL hostname: in this example, topics-server.glitch.me.

If no topics have been observed for this hostname and this user, the header is included but the value is empty. In other words, the Sec-Browsing-Topics header on a fetch() request only includes topics that have been observed for the current user's browser by a caller whose origin matches the hostname of the request URL. This is the same as if you were calling document.browsingTopics() from an iframe to view observed topics for the current user.

The request header is sent on a request as long as it has the appropriate permission policy is in play, the context is secure, and user settings permit it. Topics are not provided in headers for navigation requests.

The Topics request header looks like this:

Sec-Browsing-Topics: 186;version="chrome.1:1:2206021246";config_version="chrome.1";model_version="2206021246";taxonomy_version="1", 265;version="chrome.1:1:2206021246";config_version="chrome.1";model_version="2206021246";taxonomy_version="1"

This example includes two topics from the Topics taxonomy, 186 and 265, along with each topic's version information.

Inclusion of the topics header in XHR requests is only available temporarily, and support will be removed in the future.

# Mark topics as observed with Observe-Browsing-Topics

If a request includes a Sec-Browsing-Topics header and the response to that request includes an Observe-Browsing-Topics: ?1 header, then topics from the request header will be marked by the browser as observed. Observed topics are eligible for calculation by the Topics API. This mechanism is designed to match the functionality provided by using the JavaScript API from an iframe.

The screenshot below shows the topics recorded from visiting the sites on the API demo page.

This list shows the sites you can visit from the demo to record topics of interest. As you can see, the Arts & Entertainment/Humor category in the screenshot is not the topic of one of these websites, so this recorded topic is one that was added as the possible 5 percent random topics.

• pets-animals-pets-cats.glitch.me
• cats-cats-cats-cats.glitch.me
• cats-pets-animals-pets.glitch.me
• cats-feline-meow-purr-whiskers-pet.glitch.

You can check to see which topics are real and which are random on the Topics State tab of the chrome://topics-internals page. This screenshot shows an example from different browsing sessions.

# Next steps

If you're an ad tech developer, experiment and participate with the Topics API. Read the developer guide for more in-depth resources.

# Engage and share feedback

• GitHub: Read the Topics API explainer, and raise questions and follow discussion in issues on the proposal repo.
• W3C: Discuss industry use cases in the Improving Web Advertising Business Group.
• Announcements: Join or view the mailing list.
• Privacy Sandbox developer support: Ask questions and join discussions on the Privacy Sandbox Developer Support repo.
• Chromium: File a Chromium bug to ask questions about the implementation currently available to test in Chrome.