Document.browsingTopics() — Methode · JavaScript-Referenz

Signatur

Document.prototype.browsingTopics(options)

Beschreibung

document.browsingTopics() gehört zur Topics API aus Googles Privacy Sandbox. Die Methode sollte interessenbasierte Werbung ohne Drittanbieter-Cookies ermöglichen. Der Browser ordnet besuchte Websites lokal Themen aus einer festen Taxonomie zu (z. B. „Fitness“ oder „Reisen“). Für jede zurückliegende Epoche (in der Regel eine Woche) ermittelt er die häufigsten Themen des Nutzers.

Beim Aufruf erfüllt der Browser das Promise mit einem Array aus höchstens drei Themen-Objekten, je eines aus jeder der letzten drei Epochen. Der Aufrufer erhält nur Themen, die er selbst bei diesem Nutzer beobachtet hat: Er muss in der jeweiligen Epoche also auf einer Seite mit diesem Thema eingebunden gewesen sein. In etwa 5 % der Fälle wird ein zufälliges Thema geliefert (plausible Abstreitbarkeit). Das Array kann daher auch leer sein.

Der Aufruf gilt standardmäßig selbst als Beobachtung: Die aktuelle Seite fließt dann in die Themenberechnung künftiger Epochen ein. Mit skipObservation: true lassen sich Themen lesen, ohne diese Beobachtung zu speichern. Als Alternativen zum JavaScript-Aufruf gibt es die Option browsingTopics: true bei fetch() und das Attribut browsingtopics an <iframe>. Die Themen stehen dann im Anfrage-Header Sec-Browsing-Topics.

In der Praxis rufen meist Werbe-Skripte die Methode in einem Drittanbieter-iframe auf. Die Themen gehen dann an einen Ad-Server, der passende Anzeigen auswählt. Neuen Code sollte man darauf nicht mehr aufbauen, weil Google die Privacy-Sandbox-Technologien einstellt.

Parameter

Name	Typ	Default	Beschreibung
$options	Object	{}	Optionales Konfigurationsobjekt.
$options.skipObservation	boolean	false	Bei `true` liefert der Aufruf zwar Themen zurück, die aktuelle Seite wird aber nicht als Beobachtung für künftige Epochen gespeichert.

Rückgabewert

Typ

Promise<Array<{configVersion: string, modelVersion: string, taxonomyVersion: string, topic: number, version: string}>>

Beschreibung

Ein Promise, das mit einem Array aus 0–3 Objekten erfüllt wird. topic ist die numerische ID in der Taxonomie. taxonomyVersion, modelVersion und configVersion geben die Version von Taxonomie, Klassifizierungsmodell und Konfiguration an. version fasst diese Angaben zusammen (z. B. "chrome.1:1:2"). Das Promise wird mit einer DOMException abgelehnt, zum Beispiel mit NotAllowedError (durch die Permissions Policy browsing-topics blockiert, Aufrufer nicht registriert oder opake Origin) oder mit InvalidStateError (Dokument nicht vollständig aktiv).

Beispiele

Themen abrufen mit Feature-Erkennung

const ladeThemen = async () => {
  if (!('browsingTopics' in document)) {
    console.log('Topics API nicht verfügbar');
    return [];
  }
  try {
    const topics = await document.browsingTopics();
    for (const t of topics) {
      console.log(`Thema ${t.topic} (Taxonomie ${t.taxonomyVersion}, ${t.version})`);
    }
    return topics;
  } catch (err) {
    // z. B. NotAllowedError durch Permissions Policy
    console.warn('Themen nicht abrufbar:', err.name);
    return [];
  }
};

ladeThemen();

Thema 186 (Taxonomie 2, chrome.1:2:2) (oder: Topics API nicht verfügbar)

Themen lesen, ohne eine Beobachtung zu speichern

// Etwa auf einer Übersichtsseite, die das Profil nicht beeinflussen soll
const topics = await document.browsingTopics({ skipObservation: true });
const ids = topics.map((t) => t.topic);
console.log('Themen-IDs:', ids);

Themen-IDs: [57, 186]

Themen an einen Ad-Server senden

const holeAnzeige = async (slotId) => {
  let topics = [];
  if ('browsingTopics' in document) {
    topics = await document.browsingTopics().catch(() => []);
  }
  const res = await fetch('https://ads.example.com/anzeige', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      slotId,
      topics: topics.map(({ topic, taxonomyVersion }) => ({ topic, taxonomyVersion }))
    })
  });
  return res.json();
};

holeAnzeige('banner-oben').then((ad) => console.log(ad));

Alternative: Themen per fetch-Header übermitteln

// Der Browser hängt den Header Sec-Browsing-Topics automatisch an
const res = await fetch('https://ads.example.com/themen', {
  browsingTopics: true
});
// Antwortet der Server mit "Observe-Browsing-Topics: ?1",
// wird die aktuelle Seite als Beobachtung gespeichert.
console.log(res.status);

200

// Wichtig · Fallstricke

Veraltet und nicht standardisiert: Die Topics API gibt es nur in Chromium-Browsern. Firefox und Safari lehnen sie ab und setzen sie nicht um. Google stellt die Privacy-Sandbox-Technologien inzwischen ein. Nutzen Sie die Methode nur hinter einer Feature-Erkennung ('browsingTopics' in document) und sehen Sie immer einen Fallback vor.
Registrierung nötig: In Chrome funktioniert der Aufruf nur für Origins, die sich für die Privacy Sandbox registriert und bestätigt haben. Sonst wird das Promise abgelehnt.
Permissions Policy: Die Direktive browsing-topics steuert den Zugriff (Standard: *). Mit Permissions-Policy: browsing-topics=() kann eine Website die API für sich und alle eingebetteten iframes sperren.
Nutzereinstellungen: Nutzer können die API in den Browser-Einstellungen abschalten oder einzelne Themen blockieren. Im Inkognito-Modus, bei blockierten Drittanbieter-Cookies und in manchen Regionen liefert sie ebenfalls keine Themen. Ein leeres Array ist daher der Normalfall und kein Fehler.
Nur eigene Beobachtungen: Ein Aufrufer erhält nur Themen, die er selbst beobachtet hat. Durch die rund 5 % Zufallsthemen sind die Daten außerdem ungenau.
Datenschutz: Themen gelten als personenbezogene Profildaten. Nach DSGVO und ePrivacy-Richtlinie ist deshalb in der Regel eine Einwilligung (Consent) nötig, bevor sie gelesen oder weitergegeben werden.
Der Aufruf funktioniert nur in einem sicheren Kontext (HTTPS) und in einem vollständig aktiven Dokument.

Siehe auch

Document new VTTRegion() Document.ariaNotify() Document.createTouch() Document.adoptNode()