Topics API implementieren

Auf dieser Seite werden Implementierungsdetails für Aufrufer der Topics API beschrieben, die Themen beobachten und darauf zugreifen möchten. Bevor Sie mit der Implementierung Ihrer Lösung beginnen, müssen Sie sicherstellen, dass Ihr Browser richtig eingerichtet ist. Im Übersichtsbereich finden Sie weitere Informationen dazu, wie Anrufer die Themen von Nutzern sehen und darauf zugreifen können.

Themen beobachten und darauf zugreifen

Es gibt zwei Möglichkeiten, die Themen eines Nutzers zu beobachten und darauf zuzugreifen: HTTP-Header und JavaScript API.

HTTP-Header

Die Verwendung von HTTP-Headern ist ein empfohlener Ansatz für die Beobachtung und den Zugriff auf Nutzerthemen. Dieser Ansatz kann viel leistungsfähiger sein als die Verwendung der JavaScript API. Bei HTTP-Headern wird die registrierbare Domain, die als aufrufende Domain aufgezeichnet wird, aus der URL der Anfrage abgeleitet. Dies ist die Domain, die die Themen des Nutzers beobachtet hat.

Anfrage initiieren

Es gibt zwei Möglichkeiten, Themen mit Headern zu verwenden:

  • Durch den Zugriff auf Anfrage- und Antwortheader bei einer fetch()-Anfrage, die eine browsingTopics: true-Option enthält.
  • Durch den Zugriff auf Header für ein iframe-Element, das ein browsingtopics-Attribut enthält.
Anfrage mit einem Fetch initiieren

Beim Abrufen sendet der API-Aufrufer eine Anfrage, die {browsingTopics: true} im Parameter „options“ enthält. Der Ursprung des URL-Parameters der Abrufanfrage ist der Ursprung, bei dem Themen beobachtet wurden.

   fetch('<topics_caller_eTLD+1>', { browsingTopics: true })
    .then((response) => {
        // Process the response
    });
Anfrage mit einem iFrame initiieren

Fügen Sie dem Element <iframe> das Attribut browsingtopics hinzu. Der Browser fügt den Header Sec-Browsing-Topics in die Anfrage des iFrames ein. Der Ursprung des iFrames ist der Aufrufer.

   <iframe src="https://adtech.example" browsingtopics></iframe>

Werte von Anfrageheadern interpretieren

Bei beiden Ansätzen (Abruf und Iframe) können die für einen Nutzer beobachteten Themen auf dem Server aus dem Anfrageheader Sec-Browsing-Topics abgerufen werden. Die Topics API fügt Nutzer-Themen automatisch in den Header ein, wenn eine fetch()- oder Iframe-Anfrage erfolgt. Wenn die API ein oder mehrere Themen zurückgibt, enthält eine Abrufanfrage an den Ursprung, von dem die Themen beobachtet wurden, einen Sec-Browsing-Topics-Header wie diesen:

   (325);v=chrome.1:1:1, ();p=P000000000

Wenn von der API keine Themen zurückgegeben werden, sieht der Header so aus:

   ();p=P0000000000000000000000000000000

Weiterleitungen werden berücksichtigt und die in der Weiterleitungsanfrage gesendeten Themen sind spezifisch für die Weiterleitungs-URL. Sec-Browsing-Topics-Headerwerte werden aufgefüllt, um das Risiko zu verringern, dass ein Angreifer die Anzahl der Themen, die für einen Aufrufer gelten, anhand der Headerlänge ermittelt.

Serverseitige Antwort verarbeiten

Wenn die Antwort auf die Anfrage einen Observe-Browsing-Topics: ?1-Header enthält, bedeutet dies, dass der Browser die Themen aus der zugehörigen Anfrage als beobachtet markieren und den aktuellen Seitenaufruf in die nächste Epochenberechnung der Themen des Nutzers einbeziehen soll. Fügen Sie den Observe-Browsing-Topics: ?1-Header in die Antwort in Ihrem serverseitigen Code ein:

   res.setHeader('Observe-Browsing-Topics', '?1');
Anfrage- und Antwortheader zum Festlegen und Abrufen von Themen.
Header für iFrame und fetch()

Beobachtete Themen mit Partnern teilen

Da SSPs nur auf der Publisher-Seite präsent sind, möchten DSPs möglicherweise Themen, die sie auf den Websites des Werbetreibenden beobachten, mit ihren Partner-SSPs teilen. Dazu können sie eine fetch()-Anfrage mit dem Header „Themen“ an die SSPs aus dem Kontext auf oberster Ebene des Werbetreibenden senden.

const response = await fetch("partner-ssp.example", {
 browsingTopics: true
});

Themen mit JavaScript beobachten und darauf zugreifen

Die JavaScript API-Methode document.browsingTopics() bietet eine Möglichkeit, die Interessenthemen eines Nutzers im Browser zu beobachten und abzurufen: – Beobachtung aufzeichnen:Informiert den Browser darüber, dass der Aufrufer beobachtet hat, dass der Nutzer die aktuelle Seite besucht hat. Diese Beobachtung trägt zur Themenberechnung des Nutzers für den Anrufer in zukünftigen Epochen bei. – Access Topics:Ruft Themen ab, die der Aufrufer zuvor für den Nutzer beobachtet hat. Die Methode gibt ein Array mit bis zu drei Themenobjekten zurück, eines für jede der letzten Epochen, in zufälliger Reihenfolge.

Wir empfehlen, entweder die JavaScript API-Demo für Topics zu forken und als Ausgangspunkt für Ihren Code zu verwenden.

API-Verfügbarkeit

Prüfen Sie vor der Verwendung der API, ob sie unterstützt wird und verfügbar ist:

 if ('browsingTopics' in document && document.featurePolicy.allowsFeature('browsing-topics')) {
    console.log('document.browsingTopics() is supported on this page');
 } else {
    console.log('document.browsingTopics() is not supported on this page');
 }

iFrame einbetten

Für den Aufruf muss ein ursprungsübergreifendes iFrame verwendet werden, da der Kontext, aus dem die API aufgerufen wird, dafür sorgt, dass der Browser die für den Aufrufer geeigneten Themen zurückgibt. Fügen Sie ein <iframe>-Element in Ihren HTML-Code ein:

<iframe src="https://example.com" browsingtopics></iframe>

Sie können auch ein iFrame dynamisch mit JavaScript erstellen:

 const iframe = document.createElement('iframe');
 iframe.setAttribute('src', 'https://adtech.example/');
 document.body.appendChild(iframe);

API aus dem iFrame aufrufen

 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.
 }

Standardmäßig bewirkt die Methode document.browsingTopics() auch, dass der Browser den aktuellen Seitenaufruf aufzeichnet, wie er vom Aufrufer beobachtet wird, damit er später bei der Berechnung von Themen verwendet werden kann. Der Methode kann ein optionales Argument übergeben werden, um zu verhindern, dass der Seitenaufruf aufgezeichnet wird: {skipObservation:true}.

 // current page won't be included in the calculation of topics:
 const topics = await document.browsingTopics({skipObservation:true});

Antwort verstehen

Es werden maximal drei Themen zurückgegeben: eines oder keines für jede der letzten drei Wochen, je nachdem, ob Themen beobachtet wurden oder nicht. Es werden nur Themen zurückgegeben, die vom Anrufer für den aktuellen Nutzer beobachtet wurden. Hier sehen Sie ein Beispiel für die API-Antwort:

 [{
'configVersion': chrome.2,
 'modelVersion': 4,
 'taxonomyVersion': 2,
 'topic': 309,
 'version': chrome.2:2:4
}]
  • configVersion: Ein String, der die Version der Konfiguration des Topics-Algorithmus des Browsers angibt.
  • modelVersion: Ein String, der den Klassifikator für maschinelles Lernen identifiziert, der zum Ableiten von Themen verwendet wird.
  • taxonomyVersion: Ein String, der die vom Browser verwendete Gruppe von Themen identifiziert.
  • topic: Eine Zahl zur Identifizierung des Themas in der Taxonomie.
  • version: Ein String, der configVersion, taxonomyVersion und modelVersion verkettet. Die in diesem Leitfaden beschriebenen Parameter und Details der API (z. B. Taxonomiegröße, Anzahl der pro Woche berechneten Themen und Anzahl der pro Aufruf zurückgegebenen Themen) können sich ändern, da wir Feedback aus dem Ökosystem berücksichtigen und die API weiterentwickeln.

Auf der Seite Testen und in Produktion gehen erfahren Sie, welche Antwort Sie erwarten können und wie Sie Topics als zusätzliches Signal für relevantere Anzeigen verwenden können.

Nächste Schritte

Hier erfahren Sie, wie Sie themenbasierte Lösungen bereitstellen, testen und skalieren.
Hier erfahren Sie mehr über die Tools in Chrome, mit denen Sie Informationen zur Topics API aufrufen, die Zuweisung von Themen nachvollziehen und Ihre Implementierung beheben können.

Weitere Informationen

In unseren Ressourcen finden Sie weitere Informationen zur Topics API im Web.