Topics API
Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
Non-standard: This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.
Warning: This feature is currently opposed by two browser vendors. See the Standards positions section below for details of opposition.
Note: An Enrollment process is required to use the Topics API in your applications. See the Enrollment section for details of what sub-features are gated by enrollment.
The Topics API provides a mechanism for developers to implement use cases such as interest-based advertising (IBA) based on topics collected by the browser as the user navigates different pages, rather than collected by the developer by tracking the user's journey around different sites with third-party cookies.
Concepts and usage
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.
Note: This process only happens on sites where a Topics API feature is used (see What API features enable the Topics API?).
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.
What topics are there?
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.
Interfaces
The Topics API has no distinct interfaces of its own.
Extensions to other interfaces
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()
, thebrowsingTopics
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 thebrowsingtopics
content attribute value.
HTML elements
HTTP headers
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
; thebrowsing-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 aSec-Browsing-Topics
header will fail with aNotAllowedError
DOMException
.
Enrollment
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 aNotAllowedError
DOMException
. - Creating or modifying the
Sec-Browsing-Topics
header will fail silently, and any existingSec-Browsing-Topics
header will be deleted.
Examples
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 aSec-Browsing-Topics
header can be used to observe and then access topics (see source code).
Specifications
This feature is not part of an official standard, although it is specified in the Topics API Unofficial Proposal Draft.
Standards positions
Browser compatibility
BCD tables only load in the browser
See also
- Topics API on developer.chrome.com (2023)
- The Privacy Sandbox on developer.chrome.com (2023)