Dokument: browsingTopics() Methode
Limited availability
This feature is not Baseline because it does not work in some of the most widely-used browsers.
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.
Veraltet: Diese Funktion wird nicht mehr empfohlen. Obwohl einige Browser sie möglicherweise noch unterstützen, könnte sie bereits aus den relevanten Webstandards entfernt worden sein, in Kürze entfernt werden oder nur noch aus Kompatibilitätsgründen bestehen. Vermeiden Sie die Verwendung und aktualisieren Sie vorhandenen Code, falls möglich; siehe die Kompatibilitätstabelle am Ende dieser Seite, um Ihre Entscheidung zu unterstützen. Beachten Sie, dass diese Funktion jederzeit aufhören könnte zu funktionieren.
Warnung: Diese Funktion wird derzeit von zwei Browseranbietern abgelehnt. Details zur Ablehnung finden Sie im Abschnitt Standards Positionen unten.
Hinweis: Ein Anmeldeverfahren ist erforderlich, um diese Funktion in Ihren Anwendungen zu nutzen.
Die browsingTopics() Methode des Document Interfaces gibt ein Promise zurück, das mit einem Array von Objekten erfüllt wird, die die Top-Themen des Nutzers darstellen, eines aus jeder der letzten drei Epochen. Diese Themen könnten dann in einer nachfolgenden Abrageanfrage an die Ad-Tech-Plattform zurückgegeben werden. Standardmäßig führt die Methode dazu, dass der Browser den aktuellen Seitenbesuch als vom Aufrufer beobachtet aufzeichnet, damit der Hostname der Seite später in der Themenberechnung verwendet werden kann.
Siehe Verwendung der Topics API für weitere Details.
Hinweis:
browsingTopics() verlässt sich nicht auf HTTP-Header, um Themen zu senden und als beobachtet zu markieren, im Gegensatz zu den anderen Topics API aktivierenden Funktionen, ist jedoch etwas weniger performant. Es wird empfohlen, eine der HTTP-Header-verwendenden Funktionen zu verwenden und auf browsingTopics() nur in Situationen zurückzugreifen, 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, dazu führt, dass der Browser keine Themen beobachtet, 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 Nutzers für die letzten drei Epochen darstellen. Jedes Objekt enthält die folgenden Eigenschaften:
configVersion-
Ein String, der den Algorithmus identifiziert (außer dem Modellteil), 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 Nummer, die die ID des Themas darstellt, die vom Browser genutzt werden kann, um das Thema aus der Taxonomie abzurufen (siehe ein Beispiel Taxonomie der Interessen).
version-
Die
configVersion,modelVersionundtaxonomyVersion, mit Doppelpunkten (:) zwischen jeder verkettet.
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 untersagt ist. - Die aufrufende Seite die Topics API nicht in einem erfolgreichen Privacy Sandbox Anmeldeprozess enthalten 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
Diese Funktion ist kein Teil eines offiziellen Standards, obwohl sie im Topics API Unofficial Proposal Draft spezifiziert ist.