Topic classification

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

# What is a topic?

A topic, in the Topics API, is a subject a user is interested in as evidenced by the websites they visit.

Topics are a signal to help ad tech platforms select relevant ads. Unlike third-party cookies, this information is shared without revealing further information about the user themself or the user's browsing activity.

The Topics API allows third parties, such as ad tech platforms, to observe and then access topics of interest to a user. For example, the API might suggest the topic "Fiber & Textile Arts" for a user who visits the website knitting.example.

The list of topics used by the Topics API is public, human-curated, human-readable, and designed to avoid sensitive categories. This is the current list, which will expand over time. The list is structured as a taxonomy. The topics can be high-level or more specific. For example, Food & Drink is a broad category, with a subcategory of Cooking & Recipes. Subcategories may be further divided into additional subcategories.

Such a taxonomy of topics needs to make a tradeoff between utility and privacy. If topics are too specific, they could be used to identify an individual user. If they are too general, they aren't useful for selecting advertising or other content.

The topics taxonomy is constructed with two underlying requirements in mind:

• Support interest-based advertising
• Keep users safe and protect their privacy

This suggests several questions. For example:

• What's the best way for the API to infer topics of interest for a user, based on their browsing activity, while preserving the user's privacy?
• How could the taxonomy be structured to make it more useful?
• What specific items should the taxonomy include?

# How the API infers topics for a site

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 is publicly available, and as the explainer notes, it is 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.

Only sites that include code that calls the Topics API are 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 callingß the API.

In addition, a caller can only receive topics that their code has "seen." So if another caller's code registered a topic, say /Autos & Vehicles/Motor Vehicles (By Type)/Hatchbacks, for a user's browser and your code did not cause that topic to be registered for that user's browser, you will not be able to learn of that topic of interest for that user's browser when you call the API from your embedded code.

# The 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 at chrome://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, first unpack it:

gunzip -c override_list.pb.gz > override_list.pb

Use protoc to inspect it as text:

protoc --decode_raw < override_list.pb > output.txt

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

# Providing 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:

• What topics taxonomy should be used long term?
• What if a site disagrees with the topics assigned?

# How the user's top five topics are 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 are also 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.

You can view information about topics observed during the current epoch from the chrome://topics-internals page.

# How the API decides which callers see which topics

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

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:

In addition, code from adtech2.example is added to diy-clothing.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.

# User controls, transparency, and opting out

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 users 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 controls to inform the user about the API and show how to enable or disable it. Chrome provides 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.

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.

# Site opt out

In addition to the user's ability to opt out, you can opt out of Topics for your site or pages on it. The Developer guide explains how.

# Using the Topics API on websites with prebid.js

As noted in the release of Prebid 7, the community is actively developing an integration with the Topics API via a new module. However, as of November 2022, the Topics Module has not yet been completed. To stay abreast with the development, we recommend the following:

• Follow Prebid PR #8947: Topics module: Initial Topics iframe implementation, which is the PR to create the Prebid Topics Module.
• Follow Prebid Issue #8741: Enhancements to Topics module, which has an active discussion on the Prebid Topics module's intended workflow.
• If this is a high dependency, reach out to Prebid.js to check in on status updates and timelines, through whatever standard channel they offer.

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