Diese Seite wurde von der Cloud Translation API übersetzt.

Topics API-Entwicklerleitfaden

Hier erfahren Sie, wie Sie die API verwenden und Chrome-Flags zum Testen verwenden.

Implementierungsstatus

Die Topics API hat die öffentliche Diskussionsphase abgeschlossen und ist derzeit für 99 % der Nutzer verfügbar. Eine Skalierung auf bis zu 100 % ist möglich.
Wenn Sie Feedback zur Topics API geben möchten, können Sie in der Erläuterung zu Topics ein Problem erstellen oder in der Unternehmensgruppe zur Verbesserung der Webwerbung an Diskussionen teilnehmen. Sie enthält eine Reihe offener Fragen, die noch genauer definiert werden müssen.
Im Privacy Sandbox-Zeitplan finden Sie den Zeitplan für die Implementierung der Topics API und anderer Privacy Sandbox-Vorschläge.
Im Artikel Topics API: Neueste Updates finden Sie Informationen zu Änderungen und Verbesserungen der Topics API und deren Implementierungen.

Zur Demo

Mit zwei Topics API-Demos können Sie die Topics API als einzelner Nutzer ausprobieren.

JavaScript API-Demo: topics-demo.glitch.me
Header-Demo: topics-fetch-demo.glitch.me

Sie können auch das Collab für Topics ausführen, um das Klassifizierungsmodell für Topics zu testen.

Sie können die JavaScript API verwenden, um auf Themen zuzugreifen und sie wie erfasst zu erfassen.

Die Topics JavaScript API hat eine Methode: document.browsingTopics(). Dies hat zwei Zwecke:

Bitten Sie den Browser, den aktuellen Seitenbesuch als Beobachtung für den Aufrufer aufzuzeichnen, damit dies später verwendet werden kann, um Themen für den Nutzer (für den Aufrufer) zu berechnen.
Auf Themen für den Nutzer zugreifen, die vom Aufrufer beobachtet wurden.

Die Methode gibt ein Promise zurück, das sich in ein Array von bis zu drei Themen auflöst, eines für jede der drei jüngsten epochen in zufälliger Reihenfolge. Eine Epoche ist ein Zeitraum, der in der Chrome-Implementierung auf eine Woche festgelegt ist.

Jedes Themenobjekt im von document.browsingTopics() zurückgegebenen Array hat die folgenden Eigenschaften:

configVersion: ein String zur Identifizierung der aktuellen Topics API-Konfiguration, z. B. chrome.2
modelVersion: ein String, der den Klassifikator für maschinelles Lernen identifiziert, der zum Ableiten von Themen für die Website verwendet wird, z. B. 4
taxonomyVersion: Ein String, der die vom Browser verwendeten Themen identifiziert, z. B. 2
topic: eine Zahl, die das Thema in der Taxonomie identifiziert, z. B. 309
version: ein String, der configVersion, taxonomyVersion und modelVersion verkettet, z. B. chrome.2:2:4

Die in diesem Leitfaden beschriebenen Parameter und Details der API (z. B. die Taxonomiegröße, die Anzahl der pro Woche berechneten Themen und die Anzahl der pro Aufruf zurückgegebenen Themen) können sich ändern, da wir Feedback aus der Umgebung berücksichtigen und die API weiterentwickeln.

Unterstützung für „document.browsingTopics“ erkennen

Bevor Sie die API verwenden, prüfen Sie, ob sie vom Browser unterstützt wird und im Dokument verfügbar ist:

'browsingTopics' in document && document.featurePolicy.allowsFeature('browsing-topics') ?
 console.log('document.browsingTopics() is supported on this page') :
 console.log('document.browsingTopics() is not supported on this page');

Auf Themen mit der JavaScript API zugreifen

Hier sehen Sie ein einfaches Beispiel für die API-Nutzung für den Zugriff auf Themen für den aktuellen Nutzer.

try {
  // Get the array of top topics for this user.
  const topics = await document.browsingTopics();
  
  // Request an ad creative, providing topics information.
  const response = await fetch('https://ads.example/get-creative', {
   method: 'POST',
   headers: {
     'Content-Type': 'application/json',
   },
   body: JSON.stringify(topics)
  })
  
  // Get the JSON from the response.
  const creative = await response.json();
  
  // Display ad.

} catch (error) {
  // Handle error.
}

Auf Themen zugreifen, ohne den Status zu ändern

document.browsingTopics() gibt Themen zurück, die der Aufrufer für den aktuellen Nutzer beobachtet hat. Standardmäßig zeichnet die Methode außerdem den aktuellen Besuch der Seite so auf, wie er vom Aufrufer beobachtet wird, damit er später bei der Themenberechnung verwendet werden kann. Ab Chrome 108 kann der Methode ein optionales Argument übergeben werden, damit der Seitenbesuch nicht aufgezeichnet wird: {skipObservation:true}.

Mit anderen Worten: {skipObservation:true} bedeutet, dass der Methodenaufruf nicht dazu führt, dass die aktuelle Seite in die Berechnung der Themen einbezogen wird.

Über Header auf Themen zugreifen und sie als beobachtet markieren

Mithilfe von Anfrage- und Antwortheadern können Sie auf Themen zugreifen und Seitenaufrufe als beobachtet markieren. Die Verwendung des Header-Ansatzes kann wesentlich effizienter sein als das Aufrufen der JavaScript API.

Auf Themen kann über den Header „Sec-Browsing-Topics“ einer fetch()- oder XHR-Anfrage zugegriffen werden.

Hinweis:Der Themenheader kann nur vorübergehend in XHR-Anfragen verwendet werden. Der Support wird in Zukunft entfernt.

Wenn in der Antwort auf die Anfrage ein Observe-Browsing-Topics: ?1-Header festgelegt wird, zeichnet der Browser den aktuellen Seitenbesuch so auf, wie er vom Aufrufer beobachtet wird, sodass er später bei der Themenberechnung verwendet werden kann.

Es gibt zwei Möglichkeiten, mit HTTP-Headern auf Themen zuzugreifen und sie zu beobachten:

fetch(): Fügen Sie {browsingTopics: true} dem Optionsparameter einer fetch()-Anfrage hinzu. Die Demo zu Topics-Headern zeigt ein vereinfachtes Beispiel dafür.
iFrame-Attribut: Füge einem <iframe>-Element das Attribut browsingtopics hinzu oder lege das entsprechende JavaScript-Attribut iframe.browsingTopics = true fest. Die registrierfähige Domain der iFrame-Quelle ist die Aufrufdomain. Für <iframe src="https://example.com" browsingtopics></iframe> ist der Aufrufer beispielsweise example.com.

Wichtiger Hinweis:Bei CSP-Anweisungen kann die Ausführung von Drittanbietercode auf einer Seite nicht zulässig sein, z. B. ein fetch()-Aufruf in einem Anzeigentechnologie-Skript.

Einige zusätzliche Hinweise zu Überschriften:

Den Weiterleitungen wird gefolgt und die in der Weiterleitungsanfrage gesendeten Themen sind für die Weiterleitungs-URL spezifisch.
Der Anfrageheader ändert den Status für den Aufrufer erst, wenn ein entsprechender Antwortheader vorhanden ist. Ohne den Antwortheader wird der Seitenbesuch also nicht als beobachtet erfasst, sodass die Themenberechnung durch den Nutzer für die nächste Epoche nicht beeinflusst wird.
Der Antwortheader wird nur berücksichtigt, wenn die entsprechende Anfrage den Topics-Header enthielt.
Die URL der Anfrage gibt die registrierbare Domain an, die als Aufrufdomain aufgezeichnet wird.

Fehler in der API-Implementierung beheben

Die Seite chrome://topics-internals ist in Chrome auf dem Computer verfügbar, sobald Sie die Topics API aktiviert haben. Hier werden Themen für den aktuellen Nutzer, für Hostnamen abgeleitete Themen und technische Informationen zur API-Implementierung angezeigt. Wir iterieren und verbessern das Design der Seite basierend auf dem Feedback von Entwicklern. Ihr Feedback können Sie unter bugs.chromium.org eingeben.

Für deinen Browser berechnete Themen ansehen

Nutzer können sich Informationen zu Themen ansehen, die in ihrem Browser in der aktuellen und der vorherigen Epoche beobachtet wurden, indem sie chrome://topics-internals aufrufen.

Die Seite „chrome://topics-internals“ mit ausgewähltem Bereich „Themenstatus“. — Auf der Seite „chrome://topics-internals“ werden Themen-IDs angezeigt. Hier werden Themen-IDs, zufällige und echte Themenzuweisungen sowie Taxonomie- und Modellversionen angezeigt.

Dieser Screenshot zeigt, dass unter anderem topics-demo-cats.glitch.me und cats-cats-cats-cats.glitch.me zu den kürzlich besuchten Websites gehören. Dadurch wählt die Topics API Pets und Cats als zwei der Topthemen für die aktuelle Epoche aus. Die übrigen drei Themen wurden nach dem Zufallsprinzip ausgewählt, da der Browserverlauf auf Websites zu Themen nicht ausreicht, um fünf Themen bereitzustellen.

Die Spalte Beobachtet von Kontextdomains (gehasht) enthält den Hash-Wert eines Hostnamens, für den ein Thema erfasst wurde.

Für Hostnamen abgeleitete Themen ansehen

Sie können sich auch die vom Topics-Klassifizierungsmodell abgeleiteten Themen für einen oder mehrere Hostnamen in chrome://topics-internals ansehen.

Die Seite „chrome://topics-internals“ mit ausgewähltem Bereich „Klassifikator“. — Im Klassifikatorbereich auf der Seite „chrome://topics-internals“ werden die ausgewählten Themen, die besuchten Hosts sowie die Modellversion und der Modellpfad angezeigt.

In der aktuellen Implementierung der Topics API werden Themen nur von Hostnamen und nicht von einem anderen Teil einer URL abgeleitet.

Verwenden Sie nur Hostnamen (ohne Protokoll oder Pfad), um vom Klassifikator chrome://topics-internals abgeleitete Themen anzusehen. chrome://topics-internals zeigt eine Fehlermeldung an, wenn Sie versuchen, einen „/“ in das Feld „Host“ einzufügen.

Informationen zur Topics API ansehen

Informationen zur Implementierung der Topics API und zu den Einstellungen, z. B. die Taxonomieversion und die Epochendauer, finden Sie unter chrome://topics-internals. Diese Werte entsprechen den Standardeinstellungen für die API oder für Parameter, die über die Befehlszeile festgelegt wurden. So können Sie überprüfen, ob Befehlszeilen-Flags wie erwartet funktionieren.

Im Beispiel wurde time_period_per_epoch auf 15 Sekunden festgelegt. Der Standardwert ist sieben Tage.

Auf der Seite chrome://topics-internals ist der Bereich „Funktionen und Parameter“ ausgewählt. — Im Bereich „chrome://topics-internals Funktionen und Parameter“ werden die aktivierten Funktionen, die Zeit pro Epoche, die Anzahl der zur Berechnung von Themen zu verwendenden Epochen, die Taxonomieversion und andere Einstellungen angezeigt.

Die im Screenshot gezeigten Parameter entsprechen den Flags, die festgelegt werden können, wenn Chrome über die Befehlszeile ausgeführt wird. In der Demo unter topics-fetch-demo.glitch.me wird beispielsweise empfohlen, die folgenden Flags zu verwenden:

--enable-features=BrowsingTopics,BrowsingTopicsParameters:time_period_per_epoch/15s/max_epoch_introduction_delay/3s,PrivacySandboxAdsAPIsOverride,PrivacySandboxSettings3,OverridePrivacySandboxSettingsLocalTesting

In der folgenden Liste werden die einzelnen Parameter, ihr Standardwert und ihr Zweck erläutert.

Chrome-Flags

: BrowsingTopics; Standardwert: aktiviert; Gibt an, ob die Topics API aktiviert ist.
: PrivacySandboxAdsAPIsOverride; Standardwert:aktiviert; Aktiviert Ads APIs: Attribution Reporting, Protected Audience, Topics, Fenced Frames.
: PrivacySandboxSettings4; Standardwert: deaktiviert; Aktiviert die vierte Version der UI-Einstellungen der Privacy Sandbox.
: OverridePrivacySandboxSettingsLocalTesting; Standardwert: aktiviert; Wenn diese Option aktiviert ist, müssen die zugrunde liegenden Einstellungen des Browsers nicht mehr aktiviert sein, um die Privacy Sandbox-Funktionen aktivieren zu können.
: BrowsingTopicsBypassIPIsPubliclyRoutableCheck; Standardwert:deaktiviert; Wenn diese Option aktiviert ist, wird die Prüfung, ob die IP-Adresse öffentlich routbar ist, bei der Bestimmung der Berechtigung für die Aufnahme einer Seite in die Themenberechnung umgangen.
: BrowsingTopics:number_of_epochs_to_expose; Standardwert:3; Die Anzahl der Epochen, von denen aus die Themen berechnet werden sollen, die einem anfragenden Kontext zugeordnet werden sollen. Der Browser hält intern bis zu N+1 Epochen.
: BrowsingTopics:time_period_per_epoch; Standardwert:7d-0h-0m-0s; Dauer der einzelnen Epochen. Für die Fehlerbehebung kann es hilfreich sein, diesen Wert auf (z. B.) 15 Sekunden anstelle der Standardeinstellung von 7 Tagen festzulegen.
: BrowsingTopics:number_of_top_topics_per_epoch; Standardwert: 5; Anzahl der pro Epoche berechneten Themen.
: BrowsingTopics:use_random_topic_probability_percent; Standardwert:5; Wahrscheinlichkeit, dass ein bestimmtes Thema innerhalb einer Epoche zufällig aus der gesamten Taxonomie der Themen zurückgegeben wird. Die Zufälligkeit ist von einer Epoche und Website abhängig.
: BrowsingTopics:number_of_epochs_of_observation_data_to_use_for_filtering; Standardwert: 3; Gibt an, wie viele Epochen mit API-Nutzungsdaten (z.B. Beobachtungen von Themen) zum Filtern der Themen für einen aufrufenden Kontext verwendet werden.
: BrowsingTopics:max_number_of_api_usage_context_domains_to_keep_per_topic; Standardwert:1.000; Die maximale Anzahl von nach Kontext beobachteten Domains, die für jedes Top-Thema beibehalten werden sollen. Die Absicht besteht darin, den genutzten Arbeitsspeicher zu begrenzen.
: BrowsingTopics:max_number_of_api_usage_context_entries_to_load_per_epoch; Standardwert:100.000; Die maximale Anzahl von Einträgen, die bei jeder Abfrage für die API-Nutzungskontexte aus der Datenbank abgerufen werden können. Die Abfrage wird einmal pro Epoche zum Zeitpunkt der Themenberechnung ausgeführt. Damit soll die maximale Arbeitsspeichernutzung eingeschränkt werden.
: BrowsingTopics:max_number_of_api_usage_context_domains_to_store_per_page_load; Standardwert:30; Die maximale Anzahl von Domains für API-Nutzungskontexte, die pro Seitenaufbau gespeichert werden dürfen.
: BrowsingTopics:config_version; Standardwert: 1; Codiert die Konfigurationsparameter der Topics API. Jede Versionsnummer sollte nur einem Konfigurationssatz zugeordnet werden. Das Aktualisieren der Konfigurationsparameter ohne Aktualisierung von config_version sollte für lokale Tests in der Regel problemlos funktionieren. In einigen Fällen kann der Browser jedoch in einem inkonsistenten Zustand bleiben und zu einem Browserabsturz führen, z. B. beim Aktualisieren von number_of_top_topics_per_epoch.
: BrowsingTopics:taxonomy_version; Standardwert: 1; Die von der API verwendete Taxonomieversion.

Website deaktivieren

Du kannst die Themenberechnung für bestimmte Seiten deiner Website deaktivieren, indem du den Header der Berechtigungsrichtlinie Permissions-Policy: browsing-topics=() auf einer Seite einfügst. So wird die Themenberechnung nur für alle Nutzer dieser Seite verhindert. Nachfolgende Besuche auf anderen Seiten Ihrer Website sind davon nicht betroffen: Wenn Sie eine Richtlinie zum Blockieren der Topics API auf einer Seite festlegen, hat das keine Auswirkungen auf andere Seiten.

Sie können auch festlegen, welche Drittanbieter Zugriff auf Themen auf Ihrer Seite haben. Verwenden Sie dazu den Header „Permissions-Policy“, um den Zugriff von Drittanbietern auf die Topics API zu steuern. Verwenden Sie self und alle Domains, denen Sie Zugriff auf die API gewähren möchten, als Parameter für den Header. Wenn Sie beispielsweise die Verwendung der Topics API in allen Browserkontexten außer Ihrem eigenen Ursprung und https://example.com deaktivieren möchten, legen Sie den folgenden HTTP-Antwortheader fest:

Permissions-Policy: browsing-topics=(self "https://example.com")

Nächste Schritte

Weitere Informationen

Reagieren und Feedback geben

GitHub: Lesen Sie die Erläuterung zur Topics API, stellen Sie Fragen und folgen Sie den Diskussionen zu Problemen im API-Repository.
W3C Erörtern Sie Anwendungsfälle aus der Branche in der Improving Web Advertising Business Group.
Ankündigungen: Sie können der Mailingliste beitreten oder sie aufrufen.
Entwicklersupport für die Privacy Sandbox: Hier können Sie Fragen stellen und sich an Diskussionen zum Privacy Sandbox-Entwicklersupport-Repository beteiligen.
Chromium: Melden Sie einen Fehler in Chromium, um Fragen zur Implementierung zu stellen, die derzeit zum Testen in Chrome verfügbar ist.