The Topics API

Enable interest-based advertising, without having to resort to tracking the sites a user visits.

Published on Updated on

Translated to: Español, Português, 한국어, 中文, Pусский, 日本語

Implementation status

This document outlines a new proposal for interest-based advertising: the Topics API.


Take part in a Topics origin trial

A Privacy Sandbox Relevance and Measurement origin trial has been made available in Chrome Beta 101.0.4951.26 and above on desktop for the Topics, FLEDGE 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 Topics JavaScript API on pages that provide a valid trial token:

  • 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 Topics code—such as a document.browsingTopics() call to observe topics—will need to provide a token that matches its origin.

Caution

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

Testing the Privacy Sandbox ads relevance and measurement APIs explains why this is, 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 try out the Topics API for a single user running Chrome 101 or above:

  • Set the --enable-features=PrivacySandboxAdsAPIsOverride flag from the command line
  • Enable chrome://flags/#privacy-sandbox-ads-apis

Run Chromium with flags explains how to set flags when running Chrome and other Chromium-based browsers from the command line.

This is an in-progress version of the API for early testing, so it should not be considered feature complete or indicative of the final implementation.

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

Detect feature support

Before using the API, check if it's supported by the browser and available in the document:

'browsingTopics' in document && document.featurePolicy.allowsFeature('browsing-topics') ?
console.log('document.browsingTopics() is supported on this page') :
console.log('document.browsingTopics() 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. To protect user privacy, there is no way to check for this programmatically.


Why do we need this API?

The Topics API is a Privacy Sandbox proposal for a mechanism to enable interest-based advertising, without having to resort to tracking the sites a user visits.

Interest-based advertising (IBA) is a form of personalized advertising in which an ad is selected for a user based on their interests, inferred from the sites they've recently visited. This is different from contextual advertising, which aims to match content on the page the user is visiting.

IBA can help advertisers to reach potential customers and help fund websites that cannot otherwise easily monetize visits to their site purely via contextual advertising. IBA can also supplement contextual information for the current page to help find an appropriate advertisement for the visitor.

The Topics API proposes a way to provide topics that a user might currently be interested in, based on their recent browsing activity. These topics can supplement contextual information to help select appropriate advertisements.

The Topics API has three main tasks:

  • Map website hostnames to topics of interest. For example, a yoga website might be classified as being related to "Fitness".
  • Calculate the top topics for a user based on their recent browsing activity.
  • Provide a JavaScript API to provide topics currently of interest to the user, to help select the appropriate ads.

The Topics API can help facilitate robust user controls, as the API is built on top of recognizable, high-level topics. Chrome plans to offer users the option to remove individual topics, and to show the user the topics stored in the browser.

How would topics be curated and selected?

Topics would be selected from a taxonomy: a list of items such as "Country Music", "Make-Up & Cosmetics" or "Vegetarian Cuisine". These topics would initially be curated by Chrome for testing, but with the goal that the topic taxonomy becomes a resource maintained by trusted ecosystem contributors. The taxonomy needs to provide a set of topics that is small enough in number (currently proposed to be around 350, though we expect the final number of topics to be between a few hundred and a few thousand) so that many browsers will be associated with each topic.

To avoid sensitive categories, these topics must be public, human-curated, and kept updated. The initial taxonomy proposed for testing by Chrome has been human-curated to exclude categories generally considered sensitive, such as ethnicity or sexual orientation.

The Topics API proposes using machine learning to infer topics from hostnames. The classifier model for this would initially be trained by the browser vendor, or a trusted third party, using human-curated hostnames and topics. The model would be distributed with the browser, so it would be openly developed and freely available. The browser, on the user's device, could then use the model to calculate the most popular topics for a user, based on the hostnames of the sites recently visited.

View the topics inferred for hostnames from the chrome://topics internal page.

The diagram below outlines a simplified example, to demonstrate how the Topics API might help an adtech platform to select an appropriate ad. The example assumes that the user's browser already has a model to map website hostnames to topics.

Diagram showing the stages in the Topics API lifecycle, from a user visiting websites to an ad   being displayed.

The Topics API lifecycle: view a larger version

How does the Topics API work?

The Topics API proposal is at the initial discussion phase to gather and act on feedback from the ecosystem.

The API design is not final and the details below will change as discussions progress.

A mechanism to facilitate interest-based advertising, such as the Topics API, must ensure that the topics of interest it provides are kept up to date.

With the Topics API proposal, the browser would infer topics for a user based on their browsing activity during a period of time known as an epoch, currently proposed to be one week. The topic selected for each epoch would be randomly selected from the user's top five topics for that time period. To further enhance privacy and ensure that all topics may be represented, there is a 5% chance the topic is randomly selected from all possible topics in the Taxonomy.

The Topics JavaScript API has one method: document.browsingTopics(). This returns a promise that resolves to an array of up to three topics, one for each of the three most recent epochs, in random order.

The Topics explainer proposes that each topic object in the array returned by document.browsingTopics() would have three properties:

  • value: a number identifying the topic in the taxonomy
  • taxonomyVersion: a string identifying the set of topics currently in use by the browser
  • classifierVersion: a string identifying the machine-learning classifier used to infer site topics from hostnames

The design of the Topics API is currently under discussion as an explainer, which is only the first step in the standardization process. The API is not finalized.

The parameters described in this article, and details of the API (such as taxonomy size, the number of topics calculated per week and the number of topics returned per call) are subject to change as we incorporate ecosystem feedback and iterate on the API.

API callers only receive topics they've observed

A design goal of the Topics API is to enable interest-based advertising without the sharing of information to more entities than is currently possible with third-party cookies. The Topics API proposes that topics can only be returned for API callers that have already observed them, within a limited timeframe.

Key Term

A Topics API caller is the entity that calls the document.browsingTopics() JavaScript method, and will use the topics returned by the method to help select relevant ads. Typically, a call to document.browsingTopics() would be from code included in a site from a third party such as an adtech platform. The browser determines the caller from the site of the current document. So, if you're a third party on a page, make sure you call the API from an iframe that your site owns.

In order for document.browsingTopics()to return one or more topics, it must be called in code from the same origin as code that was on a site where those topics were observed.

An API caller is said to have observed a topic for a user if it has called the document.browsingTopics() method in code included on a site that the Topics API has mapped to that topic. For example:

  1. The Topics API maps the hostname knitting.example to topics including "Fabric & Textile Arts".
  2. Code from adtech.example is included in pages on knitting.example.
  3. A user visits knitting.example.
  4. The adtech.example code calls document.browsingTopics().
  5. One of the topics the browser has inferred for knitting.example is "Fabric & Textile Arts".
  6. adtech.example is said to have observed the topic "Fabric & Textile Arts" for that user.

The API's document.browsingTopics() method will only provide topics that have already been observed by the caller within the most recent three epochs. This helps stop information about the user from being shared with more entities than technologies the API is replacing (including third-party cookies).

The number of topics returned by document.browsingTopics() depends on the number of topics that the API caller has previously observed, and the number of topics that the user has available (such as the number of weeks of data accumulated). Anywhere from zero to three topics may be returned.

Access topics with the JavaScript API

Here is a basic example of possible API usage to access topics for the current user. To keep it simple, there's no error handling.

Warning

This snippet of code is provided only to show how the Topics JavaScript API might be used. API design is subject to change.

// Get the array of top topics for this user.
const topics = await document.browsingTopics();

// Request an ad creative.
const response = await fetch('https://ads.example/get-creative', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(topics)
})

// Get the JSON from the response.
const creative = await response.json();

// Display ad.

How does the Topics API decide which callers can see which topic?

API callers only receive topics they've recently observed, and the topics for a user are refreshed once each epoch. That means the API provides a rolling window in which a given caller may receive certain topics.

The table below outlines an example (though unrealistically small) of a hypothetical browsing history for a user during a single epoch, showing topics associated with the sites they've visited, and the API callers present on each site (the entities that call document.browsingTopics() in JavaScript code included on the site).

SiteTopicsAPI callers on site
yoga.exampleFitnessadtech1.example adtech2.example
knitting.exampleCraftsadtech1.example
hiking-holiday.exampleFitness, Travel & Transportationadtech2.example
diy-clothing.exampleCrafts, Fashion & Style[none]

At the end of the epoch (currently proposed to be one week) the Topics API generates the browser's top topics for the week.

  • adtech1.example is now eligible to receive the "Fitness" and "Crafts" topics, since it observed them on yoga.example and also on knitting.example.
  • adtech1.example is not eligible to receive the "Travel & Transportation" topic for this user as it is not present on any sites the user visited recently that are associated with that topic.
  • adtech2.example has seen the "Fitness" and "Travel & Transportation" topics, but has not seen the "Crafts" topic.

The user visited diy-clothing.example, which has the "Fashion & Style" topic, but there were no calls to the Topics API on that site. At this point, this means the "Fashion & Style" topic would not be returned by the API for any caller.

In week two, the user visits another site:

SiteTopicsAPI callers on site
sewing.exampleCraftsadtech2.example

In addition, code from adtech2.example is added to diy-clothing.example:

SiteTopicsAPI callers on site
diy-clothing.exampleCrafts, Fashion & Styleadtech2.example

As well as "Fitness" and "Travel & Transportation" from week 1, this means that adtech2.example will now be able to receive the "Crafts" and "Fashion & Style" topic — but not until the following epoch, week 3. This ensures that third parties can't learn more about a user's past (in this case, an interest in fashion) than they could with cookies.

After another two weeks, "Fitness" and "Travel & Transportation" may drop out of adtech2.example's list of eligible topics, if the user doesn't visit any sites with those topics that include code from adtech2.example.

How does the API infer topics for a site?

The Topics API explainer proposes that topics are derived from a classifier model that maps website hostnames to zero or more topics.

Analyzing additional information (such as full URLs or page contents) might allow for more relevant ads, but might also reduce privacy.

The classifier model for mapping hostnames to topics would be publicly available, and the explainer proposes that it should be possible to view the topics for a site via browser developer tools. The model is expected to evolve and improve over time and be updated periodically; the frequency of this is still under consideration.

Where can I find the current classifier model?

Topics are manually curated for 10,000 top domains, and this curation is used to train the classifier. This list can be found in override_list.pb.gz, which is available atchrome://topics-internals/ under the current model in the "Classifier" tab. The domain-to-topics associations in the list are used by the API in lieu of the output of the model itself.

To run the model directly, refer to TensorFlow's guide to running a model.

To inspect the override_list.pb.gz file:

  • Unpack it: gunzip -c override_list.pb.gz > override_list.pb
  • Use protoc to inspect: protoc --decode_raw < override_list.pb > output.txt

A full taxonomy of topics with IDs is available on GitHub.

How can I provide feedback or input on the classifier model?

There are several channels for providing feedback on the Topics proposal. For feedback on the classifier model, we recommend submitting a GitHub issue or replying to an existing issue. For example:

How are the user's top five topics selected?

The API returns one topic for each epoch, up to a maximum of three. If three are returned, this includes topics for the current epoch and the previous two.

  1. At the end of each epoch, the browser compiles a list of pages that meet the following criteria:

    • The page was visited by the user during the epoch.
    • The page includes code that calls document.browsingTopics()
    • The API was enabled (for example, not blocked by the user or via a response header).
  2. The browser, on the user's device, uses the classifier model provided by the Topics API to map the hostname for each page to a list of topics.

  3. The browser accumulates the list of topics.

  4. The browser generates a list of the top five topics by frequency.

The document.browsingTopics() method then returns a random topic from the top five for each epoch, with a 5% chance that any of these may be randomly chosen from the full taxonomy of topics. In Chrome, users would also be able to remove individual topics, or clear their browsing history to reduce the number of topics returned by the API. Users may also opt-out of the API: see User opt-out.

View information about topics observed during the current epoch from the chrome://topics internal page.

How can I debug API usage?

The chrome://topics-internals page is available in Chrome Canary and Chrome Dev, if you enable the Topics API. This displays topics for the current user, topics inferred for hostnames, and technical information about the API implementation.

The chrome://topics-internals page is new! Design and functionality are still under discussion.

We're currently iterating and improving the design based on developer feedback. Add your feedback at bugs.chromium.org.

View topics calculated for your browser

You can view information about topics observed for your browser during the current and previous epochs.

Screenshot of chrome://topics-internal page with Topics State panel selected.

In this example, recently visited sites included topics-demo-cats.glitch.me and cats-cats-cats-cats.glitch.me. This caused the Topics API to select Pets and Cats as two of the top topics for the current epoch. The remaining three topics have been chosen at random, since there is not enough browsing history (on sites that observe topics) to provide five topics.

The Observed-by context domains (hashed) column provides the hashed value of a hostname for which a topic was observed.

View topics inferred for hostnames

You can view the topics inferred by the Topics classifier model for one or more hostnames.

Screenshot of chrome://topics-internal page with Classifier panel selected.

The current implementation of the Topics API infers topics from hostnames only: not any other part of a URL.

Use hostnames only (without protocol or path) to view inferred topics from the chrome://topics-internals Classifier. chrome://topics-internals will display an error if you attempt to include a "/" in the Host field.

View Topics API information

Information is provided about the Topics API implementation and settings, such as the taxonomy version and epoch duration. These values reflect default settings for the API or parameters successfully set from the command line. This is handy for checking that command line flags have worked as expected: in the example below, time_period_per_epoch has been set to 15 seconds (the default is seven days).

Screenshot of chrome://topics-internal page with Features and Parameters panel selected.

The meaning of each parameter is explained in the table below. (You'll need to scroll it horizontally to see all the details!)

The parameters correspond to flags that can be set when running Chrome from the command line. For example, the demo at topics-demo.glitch.me recommends using the following flags:

--enable-features=BrowsingTopics:time_period_per_epoch/15s,PrivacySandboxAdsAPIsOverride,PrivacySandboxSettings3,OverridePrivacySandboxSettingsLocalTesting
ParameterDefault valueMeaning
BrowsingTopicsenabledWhether the Topics API is enabled.
PrivacySandboxAdsAPIsOverrideenabledEnables ads APIs: Attribution Reporting, FLEDGE, Topics, Fenced Frames.
PrivacySandboxSettings3disabledEnables the third release of the Privacy Sandbox UI settings.
OverridePrivacySandboxSettingsLocalTestingenabledIf enabled, the browser no longer requires the underlying settings to be enabled for enabling the Privacy Sandbox features.
BrowsingTopicsBypassIPIsPubliclyRoutableCheckdisabledIf enabled, the check for whether the IP address is publicly routable will be bypassed when determining the eligibility for a page to be included in topics calculation.
BrowsingTopics:number_of_epochs_to_expose3The number of epochs from where to calculate the topics to give to a requesting context. The browser will internally keep up to N+1 epochs.
BrowsingTopics:time_period_per_epoch7d-0h-0m-0sDuration of each epoch. For debugging, it can be useful to set this to (say) 15 seconds, rather than the default 7 days.
BrowsingTopics:number_of_top_topics_per_epoch5Number of topics calculated per epoch.
BrowsingTopics:use_random_topic_probability_percent5Probability that an individual topic within an epoch is one returned at random from the entire taxonomy of topics. The randomness is sticky to an epoch and site.
BrowsingTopics:number_of_epochs_of_observation_data_to_use_for_filtering3How many epochs of API usage data (i.e. topics observations) will be used for filtering the topics for a calling context.
BrowsingTopics:max_number_of_api_usage_context_domains_to_keep_per_topic1000The max number of observed-by context domains to keep for each top topic. The intent is to cap the in-use memory.
BrowsingTopics:max_number_of_api_usage_context_entries_to_load_per_epoch100000The max number of entries allowed to be retrieved from the database for each query for the API usage contexts. The query will occur once per epoch at topics calculation time. The intent is to cap the peak memory usage.
BrowsingTopics:max_number_of_api_usage_context_domains_to_store_per_page_load30The max number of API usage context domains allowed to be stored per page load.
BrowsingTopics:config_version1Encodes the Topics API configuration parameters. Each version number should only be mapped to one configuration set. Updating the configuration parameters without updating the `config_version` should be usually fine for local testing, but in some situations could leave the browser in an inconsistent state and/or could let the browser crash, e.g. updating the `number_of_top_topics_per_epoch`.
BrowsingTopics:taxonomy_version1The taxonomy version used by the API.

How does the Topics API address concerns with FLoC?

The origin trial of FLoC in 2021 received a wide range of feedback from adtech and web ecosystem contributors. In particular, there were concerns that FLoC cohorts could be used as a fingerprinting surface to identify users, or could reveal a user's association with a sensitive category. There were also calls to make FLoC more transparent and understandable to users.

The Topics API has been designed with this feedback in mind, to explore other ways to support interest-based advertising, with improved transparency, stronger privacy assurances and a different approach for sensitive categories.

Reduce fingerprinting

The Topics API proposes multiple mechanisms to help ensure that it is difficult to reidentify significant numbers of users across sites using the Topics API alone:

  • The Topics taxonomy provides a set of coarse-grained topics (the first taxonomy has around 350 in total) which means that each topic is likely to have large numbers of users (depending on the total number of users the given browser has). In fact, there is a guaranteed minimum number of users per topic, because 5% of the time the returned topic is random.
  • Topics are returned at random from the user's top five.
  • 5% of the time, a random topic (chosen from the full set of topics) is provided.
  • If a user frequently visits the same site (every week, for example) code running on the site can only learn at most one new topic per week.
  • Different sites will receive distinct topics for the same user in the same epoch. There is only a one-in-five chance that the topic returned for a user on one site matches the topic returned for them on another. This makes it more difficult to determine if they're the same user.
  • Topics are updated for a user once each week, which limits the rate at which information can be shared.
  • A topic will only be returned for an API caller that previously observed the same topic for the same user recently. This model helps limit the potential for entities to learn about (or share) information about user interests they have not observed firsthand.

Sensitive topics

The Topics taxonomy will be public and human-curated to avoid sensitive categories.

In addition, both sites and users can opt out of the Topics API.

The Topics proposal explainer states:

"Third party cookies can be used to track anything about a user, from the exact URLs they visited, to the precise page content on those pages. This could include limitless sensitive material. The Topics API, on the other hand, is restricted to a human-curated taxonomy of topics. That's not to say that other things couldn't be statistically correlated with the topics in that taxonomy. That is possible. But when comparing the two, Topics seems like a clear improvement over cookies."

User controls and transparency

Users should be able to understand the purpose of the Topics API, recognize what is being said about them, know when the API is in use, and be provided with controls to enable or disable it.

The API's human-readable taxonomy enables people to learn about and control the topics that may be suggested for them by their browser. Users can remove topics they specifically do not want the Topics API to share with advertisers or publishers, and there can be UX for informing the user about the API and how to enable or disable it. Chrome would provide information and settings for the Topics API at chrome://settings/privacySandbox. In addition, topics are not available to API callers in Incognito mode, and topics are cleared when browsing history is cleared.

Site opt-out

Only sites that include code which calls the Topics API would be included in the browsing history eligible for topic frequency calculations, and API callers only receive topics they've observed. In other words, sites are not eligible for topic frequency calculations without the site or an embedded service taking action to call the API.

The Topics explainer also proposes sites be allowed to block topic calculation for their visitors with the following Permissions-Policy header:

Permissions-Policy: browsing-topics=()

User opt-out

The Topics API explainer proposes that the list of topics returned will be empty if:

  • The user opts out of the Topics API via browser settings at chrome://settings/privacySandbox.
  • The user has cleared their topics (via the browser settings at chrome://settings/privacySandbox) or cleared their cookies.
  • The browser is in Incognito mode.

The explainer provides more detail about privacy goals and how the API seeks to address them.


Engage and share feedback

Find out more

Last updated: Improve article

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