Topics API

A typical mechanism for advertising on the web involves a user visiting publisher sites that use an advertising technology (ad tech) platform to publish ads for an advertiser's products or services. The publisher is paid to display the ads, which helps to fund their content, and more business is driven to advertiser sites.

The above process can be made more effective using interest-based advertising (IBA). The idea is that when users visit the publisher sites, they are served a personalized selection of ads based on their interests. Their interests are inferred from sites they have previously visited. In the past, third-party cookies have been used to collect information on user interests, but all browsers are phasing out the use of third-party cookies. The Topics API provides part of the path towards this goal — a mechanism to implement IBA that does not depend on third-party cookies.

First of all, the browser infers a user's interests from the URLs of sites they visit that have ad tech <iframe>s embedded. These interests are mapped to specific topics of interest, and the browser calculates and records the users' top topic (i.e. the topic that their interests mapped to most often) at the end of each epoch. An epoch is a week by default. The top topic is updated each week so that interests are kept current and users don't start to see ads for topics that they are no longer interested in.

Once the browser has observed one or more topics for a user, the Topics API can retrieve them and send them to an ad tech platform. The platform can then use those topics to personalize the ads they serve to the user. The API helps to preserve privacy by only returning topics to an API caller that have been observed by them on pages visited by the current user.

See Using the Topics API for an explanation of how the API works.

The available top topics that the browser could calculate are stored in a publicly available taxonomy of interests. The initial taxonomy has been proposed by Chrome, with the intention that it becomes a resource maintained by trusted ecosystem contributors. The taxonomy has been human-curated to exclude categories generally considered sensitive, such as ethnicity or sexual orientation.

The Topics API has no distinct interfaces of its own.

Document.browsingTopics()

Returns a promise that fulfills with an array of objects representing the top topics for the user, one from each of the last three epochs. By default, the method also causes the browser to record the current page visit as observed by the caller, so the page's hostname can later be used in topics calculation.

fetch() / Request(), the browsingTopics option

A boolean specifying that the selected topics for the current user should be sent in a Sec-Browsing-Topics header with the associated request.

HTMLIFrameElement.browsingTopics

A boolean property specifying that the selected topics for the current user should be sent with the request for the associated <iframe>'s source. This reflects the browsingtopics content attribute value.

<iframe>, the browsingtopics attribute

A boolean attribute that, if present, specifies that the selected topics for the current user should be sent with the request for the <iframe>'s source.

Sec-Browsing-Topics

Sends the selected topics for the current user along with a request, which are used by an ad tech platform to choose a personalized ad to display.

Observe-Browsing-Topics

Used to mark topics of interest inferred from a calling site's URL (i.e. the site where the ad tech <iframe> is embedded) as observed in the response to a request generated by a feature that enables the Topics API. The browser will subsequently use those topics to calculate top topics for the current user for future epochs.

Permissions-Policy; the browsing-topics directive

Controls access to the Topics API. Where a policy specifically disallows the use of the Topics API, any attempts to call the Document.browsingTopics() method or send a request with a Sec-Browsing-Topics header will fail with a NotAllowedError DOMException.

To use the Topics API in your sites, you must specify it in a privacy sandbox enrollment process. If you don't do this, the following sub-features won't work:

• The promise returned by the Document.browsingTopics() method will reject with a NotAllowedError DOMException.
• Creating or modifying the Sec-Browsing-Topics header will fail silently, and any existing Sec-Browsing-Topics header will be deleted.

For complete working examples, see:

• Topics API demo: Demonstrates how document.browsingTopics() calls can be used to observe and then access topics (see source code).
• Topics API header demo: Demonstrates a fetch() request with a Sec-Browsing-Topics header can be used to observe and then access topics (see source code).

This feature is not part of an official standard, although it is specified in the Topics API Unofficial Proposal Draft.

Two browser vendors oppose this specification. Known positions are as follows:

• Mozilla (Firefox): Negative
• Apple (Safari): Negative

• Topics API on developers.google.com (2023)
• The Privacy Sandbox on developers.google.com (2023)