大网数据广告活动
Web 标准与前端开发

Topics API

· 52CE 我爱测

[!WARNING] > This feature is currently opposed by two browser vendors. > See the Standards positions section below for details.

Topics API

[!WARNING] This feature is currently opposed by two browser vendors. See the Standards positions section below for details.

[!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 tracking cookies have been used to collect information on user interests, but browsers are phasing out the availability of third-party cookies for an increasing proportion of users. The Topics API provides part of the path towards this goal — a mechanism to implement IBA that does not depend on user tracking.

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.

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.

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.
  • Window/fetch / Request.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.

HTML elements

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

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; the Permissions-Policy/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.

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 a NotAllowedError DOMException.
  • Creating or modifying the Sec-Browsing-Topics header will fail silently, and any existing Sec-Browsing-Topics header will be deleted.

Specifications

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

Standards positions

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

Browser compatibility

See also

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。