Diese Seite wurde von der Cloud Translation API übersetzt.

Topics API-Entwicklerleitfaden

Hier erfahren Sie, wie Sie die API verwenden und Chrome-Flags zu Testzwecken 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.

Demo ansehen

Es gibt zwei Topics API-Demos, mit denen Sie Topics als einzelner Nutzer ausprobieren können.

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

Sie können auch die Topics API ausführen, um das Topics-Klassifikatormodell auszuprobieren.

Die JavaScript API verwenden, um auf Themen zuzugreifen und sie wie beobachtet zu erfassen

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

Weisen Sie den Browser an, den aktuellen Seitenbesuch als für den Aufrufer beobachtet zu erfassen, damit dieser später zur Berechnung der Themen für den Nutzer (für den Aufrufer) verwendet werden kann.
Auf Themen für den Nutzer zugreifen, die vom Aufrufer beobachtet wurden

Die Methode gibt ein Versprechen zurück, das in ein Array von bis zu drei Themen aufgelöst wird, eines für jede der drei letzten Epochen in zufälliger Reihenfolge. Eine Epoche ist ein Zeitraum, der in der Chrome-Implementierung auf eine Woche festgelegt ist.

Jedes Themenobjekt im Array, das von document.browsingTopics() zurückgegeben wird, hat die folgenden Eigenschaften:

configVersion: ein String, der die aktuelle Topics API-Konfiguration identifiziert, z. B. chrome.2
modelVersion: ein String, der den Klassifikator für maschinelles Lernen identifiziert, der zur Ableitung 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 die API-Details (z. B. Taxonomiegröße, die Anzahl der pro Woche berechneten Themen und die Anzahl der pro Aufruf zurückgegebenen Themen) können sich ändern, wenn wir Feedback aus der Umgebung berücksichtigen und die API iterieren.

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');

Mit der JavaScript API auf Themen zugreifen

Hier ist ein einfaches Beispiel für eine mögliche API-Verwendung 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 vom Aufrufer für den aktuellen Nutzer beobachtet wurden. Standardmäßig führt die Methode außerdem dazu, dass der Browser den vom Aufrufer beobachteten aktuellen Seitenbesuch aufzeichnet, sodass er später bei der Berechnung von Themen verwendet werden kann. Ab Chrome 108 kann an die Methode ein optionales Argument übergeben werden, damit der Seitenaufruf nicht erfasst wird: {skipObservation:true}.

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

Verwenden Sie Header, um auf Themen zuzugreifen und sie als beobachtet zu markieren

Sie können auf Themen zugreifen und Seitenaufrufe als „Beobachtet“ markieren. request und response-Headers.

Der Header-Ansatz kann wesentlich leistungsfähiger sein als die JavaScript API, da die API einen ursprungsübergreifenden iFrame erstellen und von diesem aus einen document.browsingTopics()-Aufruf ausführen muss. Für den Aufruf muss ein ursprungsübergreifender iFrame verwendet werden, da durch den Kontext, aus dem die API aufgerufen wird, sichergestellt wird, dass der Browser die für den Aufrufer geeigneten Themen zurückgibt. In der Topics-Erklärung finden Sie weitere Erläuterungen: Gibt es eine Möglichkeit, Themen mit „Abruf als Anfrageheader“ zu senden? .

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

Hinweis:Der Topics-Header kann nur vorübergehend in XHR-Anfragen aufgenommen werden. Der Support wird in Zukunft entfernt.

Einen Observe-Browsing-Topics: ?1-Header für die Antwort auf die Anfrage festlegen erfasst der Browser den aktuellen, vom Aufrufer beobachteten Seitenaufruf und kann später bei der Berechnung von Themen verwendet werden.

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

fetch(): Fügen Sie {browsingTopics: true} dem Optionsparameter einer fetch()-Anfrage hinzu. Die Topics-Header-Demo zeigt ein vereinfachtes Beispiel dafür.
iFrame-Attribut: Fügen Sie einem <iframe>-Element das browsingtopics-Attribut hinzu oder legen Sie das entsprechende JavaScript fest Property iframe.browsingTopics = true. Die registrierfähige Domain der iFrame-Quelle ist die aufrufende Domain, z. B. für <iframe src="https://example.com" browsingtopics></iframe>: Der Aufrufer ist example.com.

Wichtiger Hinweis:CSP-Anweisungen können die Ausführung von Drittanbietercode auf einer Seite untersagen, z. B. den Aufruf von fetch() in einem Script für Anzeigentechnologien.

Zusätzliche Hinweise zu Überschriften:

Weiterleitungen werden gefolgt und die in der Weiterleitungs-Anfrage gesendeten Themen sind für die Weiterleitungs-URL spezifisch.
Der Anfrageheader ändert den Status für den Aufrufer nur, wenn es einen entsprechenden Antwortheader gibt. Ohne Antwortheader wird der Seitenbesuch also nicht als beobachtet erfasst und daher hat er keinen Einfluss auf die Berechnung des Themas des Nutzers für die nächste Epoche.
Der Antwortheader wird nur berücksichtigt, wenn die entsprechende Anfrage den Topics-Header enthielt.
Die URL der Anfrage enthält die registrierfähige Domain, die als aufrufende Domain aufgezeichnet wird.

Fehler in der API-Implementierung beheben

Die Seite chrome://topics-internals ist in Chrome auf dem Computer verfügbar, nachdem 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. Unter bugs.chromium.org können Sie uns Feedback geben.

Für Ihren Browser berechnete Themen ansehen

Auf chrome://topics-internals können sich Nutzer Informationen zu Themen ansehen, die während der aktuellen und der vorherigen Epochen für ihren Browser beobachtet wurden.

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

Dieser Screenshot zeigt, dass topics-demo-cats.glitch.me und cats-cats-cats-cats.glitch.me kürzlich besuchte Websites sind. Dadurch wählt die Topics API Pets und Cats als zwei der Top-Themen für die aktuelle Epoche aus. Die übrigen drei Themen wurden zufällig ausgewählt, da der Browserverlauf (auf Websites mit Themenbeobachtung) nicht ausreicht, um fünf Themen anzugeben.

Die Spalte Domains im Kontext beobachtet (gehasht) enthält den Hash-Wert eines Hostnamens, für den ein Thema beobachtet wurde.

Für Hostnamen abgeleitete Themen ansehen

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

Auf der Seite „chrome://topics-internals“ ist das Steuerfeld „Klassifikator“ ausgewählt. — Auf der Seite „chrome://topics-internals“ werden die ausgewählten Themen, die besuchten Hosts sowie die Modellversion und der Pfad angezeigt.

Die aktuelle Implementierung der Topics API leitet Themen nur von Hostnamen ab. und nicht aus einem anderen Teil einer URL.

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

Informationen zur Topics API ansehen

Informationen zur Implementierung und zu den Einstellungen der Topics API, z. B. die Taxonomieversion und die Epochendauer, finden Sie in chrome://topics-internals. Diese Werte entsprechen den Standardeinstellungen für die API oder den erfolgreich über die Befehlszeile festgelegten Parametern. So können Sie prü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. — Unter chrome://topics-internals Funktionen und Parameter werden die aktivierten Funktionen, die Zeit pro Epoche, die Anzahl der Epochen für die Berechnung von Themen, die Taxonomieversion und andere Einstellungen angezeigt.

Die im Screenshot dargestellten Parameter entsprechen den Flags, die beim Ausführen von Chrome über die Befehlszeile festgelegt werden können. 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 APIs für Anzeigen: Attribution Reporting, Protected Audience, Topics, Fenced Frames.
: PrivacySandboxSettings4; Standardwert: deaktiviert; Aktiviert die vierte Version der Einstellungen für die Privacy Sandbox-Benutzeroberfläche.
: OverridePrivacySandboxSettingsLocalTesting; Standardwert: aktiviert; Wenn diese Option aktiviert ist, müssen im Browser die zugrunde liegenden Einstellungen für Privacy Sandbox-Funktionen aktivieren
: BrowsingTopicsBypassIPIsPubliclyRoutableCheck; Standardwert: deaktiviert; Wenn diese Option aktiviert ist, wird geprüft, ob die IP-Adresse öffentlich weitergeleitet werden kann wird umgangen, wenn festgestellt wird, ob eine Seite in Themen aufgenommen werden kann. Berechnung.
: BrowsingTopics:number_of_epochs_to_expose; Standardwert: 3; Die Anzahl der Epochen, für die die Themen berechnet werden, die einem anfragenden Element übergeben werden sollen Kontext. Der Browser durchläuft intern N+1 Epochen.
: BrowsingTopics:time_period_per_epoch; Standardwert:7d-0h-0m-0s; Dauer jeder Epoche. Für das Debugging kann es sinnvoll sein, diesen Wert beispielsweise auf 15 Sekunden statt auf die Standardeinstellung von 7 Tagen festzulegen.
: BrowsingTopics:number_of_top_topics_per_epoch; Standardwert: 5; Anzahl der Themen, die pro Epoche berechnet wurden.
: BrowsingTopics:use_random_topic_probability_percent; Standardwert: 5; Wahrscheinlichkeit, dass ein einzelnes Thema innerhalb einer Epoche nach dem Zufallsprinzip der gesamten Taxonomie von Themen. Die Zufälligkeit bleibt für eine Epoche und Site bestehen.
: BrowsingTopics:number_of_epochs_of_observation_data_to_use_for_filtering; Standardwert: 3; Für wie viele Epochen werden API-Nutzungsdaten (z.B. Beobachtung von Themen) verwendet Filtern der Themen für einen aufrufenden Kontext.
: BrowsingTopics:max_number_of_api_usage_context_domains_to_keep_per_topic; Standardwert: 1.000; Die maximale Anzahl von Kontextdomains, die für jedes Top-Thema beobachtet werden sollen. Die Absicht ist die Begrenzung des genutzten Arbeitsspeichers.
: BrowsingTopics:max_number_of_api_usage_context_entries_to_load_per_epoch; Standardwert: 100.000; Die maximale Anzahl von Einträgen, die für jede Abfrage aus der Datenbank abgerufen werden können für die API-Nutzungskontexte. Die Abfrage wird einmal pro Epoche bei der Themenberechnung ausgeführt . Damit soll die maximale Arbeitsspeichernutzung begrenzt werden.
: BrowsingTopics:max_number_of_api_usage_context_domains_to_store_per_page_load; Standardwert: 30; Die maximale Anzahl von Domains für den API-Nutzungskontext, die pro Seitenaufbau gespeichert werden dürfen.
: BrowsingTopics:config_version; Standardwert: 1; Codiert die Konfigurationsparameter der Topics API. Jede Versionsnummer sollte nur ist einem Konfigurationssatz zugeordnet. Wenn Sie die Konfigurationsparameter aktualisieren, ohne den config_version zu aktualisieren, sollte für lokale Tests in der Regel ausreichend, kann aber auch inkonsistenten Status und kann zu einem Browserabsturz führen, z. B. durch das Aktualisieren der number_of_top_topics_per_epoch.
: BrowsingTopics:taxonomy_version; Standardwert: 1; Die Taxonomie Version, die von der API verwendet wird.

Website deaktivieren

Du kannst die Themenberechnung für bestimmte Seiten deiner Website deaktivieren, indem du den Header Permissions-Policy: browsing-topics=() Permissions-Policy auf einer Seite einfügst. Dadurch wird verhindert, dass die Themenberechnung für alle Nutzer dieser Seite verwendet wird. Nachfolgende Besuche anderer Seiten Ihrer Website sind davon nicht betroffen: Wenn Sie eine Richtlinie festlegen, durch die die Topics API auf einer Seite blockiert wird, wirkt sich das nicht auf andere Seiten aus.

Sie können auch festlegen, welche Drittanbieter Zugriff auf Themen auf Ihrer Seite haben. Verwenden Sie dazu den Permissions-Policy-Header, um den Drittanbieterzugriff auf die Topics API zu steuern. Verwenden Sie als Parameter für den Header self und alle Domains, denen Sie den Zugriff auf die API erlauben möchten. Wenn Sie beispielsweise die Verwendung der Topics API in allen Browserkontexten mit Ausnahme Ihres eigenen Ursprungs und https://example.com vollständig 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.