JavaScript Document browsingTopics() Method

What You’ll Learn

document.browsingTopics() is a deprecated, non-standard instance method from the Topics API. It returns a Promise of topic objects for interest-based advertising. Learn the return shape, skipObservation, enrollment requirements, why MDN recommends HTTP headers instead, and five try-it labs for educational reference.

Introduction

Third-party cookies are being phased out in many browsers. Google’s Privacy Sandbox proposed alternatives for ad targeting, including the Topics API—a way to share coarse interest categories (topics) instead of cross-site tracking cookies.

MDN: 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, calling it also records the current page visit as observed so the page hostname can be used in future topic calculation.

Related tutorials: ariaNotify(), Document constructor, JavaScript hub.

Understanding document.browsingTopics()

An instance method on the page’s document object, part of the Topics API (Privacy Sandbox).

• Returns — a Promise resolving to up to three topic objects (MDN).
• Each topic object — topic, configVersion, modelVersion, taxonomyVersion, version (MDN).
• Default behavior — observes the current page for topics unless skipObservation: true (MDN).
• Enrollment — calling site must complete Privacy Sandbox enrollment (MDN).
• Permissions Policy — browsing-topics can block usage (MDN).
• Performance — MDN advises HTTP header-based Topics features when headers can be modified.

📝 Syntax

General forms of Document.browsingTopics (MDN):

browsingTopics()
browsingTopics(options)

Parameters

• options (optional) — an object that may include:
  • skipObservation — boolean. If true, the browser does not observe topics when invoked. Default false (MDN).

Return value

A Promise that fulfills with an array of up to three topic objects (MDN).

Example topic object (MDN / Chrome)

{
  "configVersion": "chrome.1",
  "modelVersion": "1",
  "taxonomyVersion": "1",
  "topic": 43,
  "version": "chrome.1:1:1"
}

Exceptions

• Topics API disallowed by browsing-topics Permissions Policy (MDN).
• Site not enrolled in Privacy Sandbox enrollment (MDN).

Common patterns

// Feature-detect first
if (typeof document.browsingTopics !== "function") {
  console.log("browsingTopics not available");
} else {
  const topics = await document.browsingTopics();
  console.log(topics);
}

// Read without observing this page
const topicsOnly = await document.browsingTopics({ skipObservation: true });

⚖️ browsingTopics() vs Topics HTTP headers

Examples Gallery

Examples follow MDN Document: browsingTopics() for educational reference. The API may be unavailable without enrollment or in most browsers.

try {
  const topics = await document.browsingTopics();
  console.log(topics.length, "epoch topic(s)");
  console.log(topics);
} catch (err) {
  console.error("browsingTopics failed:", err.message);
}

0–3 epoch topic(s)
[{ topic: 43, version: "chrome.1:1:1", ... }]
—or— browsingTopics not available / not enrolled

if (typeof document.browsingTopics === "function") {
  console.log("browsingTopics API present (may still require enrollment)");
} else {
  console.log("browsingTopics not supported in this browser");
}

browsingTopics API present
  — or —
browsingTopics not supported in this browser

const topics = await document.browsingTopics({
  skipObservation: true
});

console.log("Topics without observing this page:", topics);

Topics without observing this page: [...]

const topics = await document.browsingTopics();

topics.forEach((t, i) => {
  console.log(`Epoch ${i + 1}:`, {
    topic: t.topic,
    version: t.version,
    taxonomyVersion: t.taxonomyVersion
  });
});

Epoch 1: { topic: 43, version: "chrome.1:1:1", taxonomyVersion: "1" }

const topics = await document.browsingTopics();

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

const creative = await response.json();
// Display ad using creative

POST body: [{ topic: 43, ... }]
(simulated in try-it — real endpoint needs enrollment)

🚀 Historical Use Cases

• Interest-based ads — share coarse topics instead of third-party cookies (Privacy Sandbox).
• Ad server requests — include topics JSON in a subsequent fetch (MDN example).
• Read-only analytics — skipObservation: true when you must not observe the page.
• Legacy code review — understand Topics API calls in older ad integrations.
• Not for new apps — MDN deprecated; vendor opposition and limited support.
• Prefer headers — MDN recommends HTTP Topics headers when modifiable.

📝 Notes

• MDN: Deprecated and Non-standard.
• Two browser vendors oppose the feature (MDN standards positions).
• Privacy Sandbox enrollment required for production use (MDN).
• browsing-topics Permissions Policy can block the API (MDN).
• Prefer Topics HTTP headers over this method when headers can be modified (MDN).
• Related: ariaNotify(), Document(), JavaScript hub.

💡 Best Practices