Dokument: browsingTopics()-Methode
Deprecated
To be removed
This feature is pending removal from browsers. Using it now may lead to broken functionality in future updates. Following the announcement that Chrome will maintain its current approach to third-party cookies, Chrome decided to withdraw certain Privacy Sandbox features including the topics API.
Nicht standardisiert: Diese Funktion ist nicht standardisiert. Wir raten davon ab, nicht-standardisierte Funktionen auf produktiven Webseiten zu verwenden, da sie nur von bestimmten Browsern unterstützt werden und sich in Zukunft ändern oder entfernt werden können. Unter Umständen kann sie jedoch eine geeignete Option sein, wenn es keine standardisierte Alternative gibt.
Warnung: Dieses Feature wird derzeit von zwei Browser-Anbietern abgelehnt. Siehe den Abschnitt Standards-Positionen unten für Details zur Ablehnung.
Hinweis: Ein Registrierungsprozess ist erforderlich, um dieses Feature in Ihren Anwendungen zu nutzen.
Die browsingTopics()-Methode des Document-Interfaces gibt ein Versprechen (promise) zurück, das mit einem Array von Objekten erfüllt wird, die die Top-Themen für den Benutzer darstellen, eines aus jedem der letzten drei Epochen. Diese Themen könnten dann in einer nachfolgenden Fetch-Anfrage an die Werbetechnologie-Plattform übermittelt werden. Standardmäßig führt die Methode auch dazu, dass der Browser den aktuellen Seitenbesuch als vom Aufrufer beobachtet protokolliert, sodass der Hostname der Seite später in der Themenberechnung verwendet werden kann.
Hinweis:
browsingTopics() stützt sich nicht auf HTTP-Header, um Themen zu senden und als beobachtet zu markieren, wie es die anderen Features zur Aktivierung der Topics API tun, ist aber etwas weniger performant. Es wird empfohlen, eines der auf HTTP-Header basierenden Features zu verwenden und browsingTopics() nur in Situationen einzusetzen, in denen die Header nicht geändert werden können.
Syntax
browsingTopics()
browsingTopics(options)
Parameter
optionsOptional-
Ein Optionsobjekt, das die folgenden Eigenschaften enthalten kann:
skipObservation-
Ein boolescher Wert, der, wenn er auf
truegesetzt ist, den Browser dazu veranlasst, Themen nicht zu beobachten, wennbrowsingTopics()aufgerufen wird. Der Standardwert istfalse, was dazu führt, dass Themen beobachtet werden.
Rückgabewert
Ein Promise, das mit einem Array von bis zu drei Objekten erfüllt wird, die die ausgewählten Themen des aktuellen Benutzers für die letzten drei Epochen darstellen. Jedes Objekt enthält die folgenden Eigenschaften:
configVersion-
Ein String, der den Algorithmus (außerhalb des Modellteils) identifiziert, der zur Berechnung des Themas verwendet wird.
modelVersion-
Ein String, der das Modell darstellt, das verwendet wird, um einen String (wie den Hostnamen einer Webseite) in Themen-IDs zu klassifizieren.
taxonomyVersion-
Ein String, der die verwendete Taxonomie-Version darstellt.
topic-
Eine Zahl, die die ID des Themas darstellt, die vom Browser verwendet werden kann, um das Thema aus der Taxonomie abzurufen (siehe ein Beispiel für eine Interessen-Taxonomie).
version-
Die
configVersion,modelVersionundtaxonomyVersion, zusammengefügt mit Doppelpunkten (:) zwischen jedem.
Die genauen Eigenschaftswerte können je nach Browser-Implementierung variieren. Ein Beispielobjekt aus Chrome könnte wie folgt aussehen:
{
"configVersion": "chrome.1",
"modelVersion": "1",
"taxonomyVersion": "1",
"topic": 43,
"version": "chrome.1:1:1"
}
Ausnahmen
NotAllowedErrorDOMException-
Wird ausgelöst, wenn:
- Die Nutzung der Topics API durch eine
browsing-topicsBerechtigungsrichtlinie nicht erlaubt ist. - Die aufrufende Seite die Topics API nicht in einem erfolgreichen Registrierungsprozess der Privacy Sandbox inkludiert hat.
- Die Nutzung der Topics API durch eine
Beispiele
// Get an array of top topics for this user
const topics = await document.browsingTopics();
// Request an ad creative
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
Spezifikationen
Dieses Feature ist nicht Teil eines offiziellen Standards, obwohl es im Topics API Unofficial Proposal Draft spezifiziert ist.