Integrationsanleitung für die Topics API

Hier erfahren Sie, wie Sie die Topics API für bestimmte AdTech-Anwendungsfälle verwenden.

Hinweis

Machen Sie sich zuerst mit der Topics API und den Diensten vertraut.

  1. Entwicklerdokumentation ansehen:
    1. Lesen Sie zuerst die Übersicht, um sich mit der Topics API und ihren Funktionen vertraut zu machen.
    2. Sehen Sie sich die Demo zu Topics an (Video).
    3. Probieren Sie die Demos für den Topics-Header und die JavaScript API aus.
    4. Erstellen Sie einen Fork der Demos (beide enthalten Links zu ihrem Code) und führen Sie sie auf Ihrer eigenen Website aus.
    5. Weitere Informationen finden Sie in der API-Erklärung.
  2. Prüfen Sie den Implementierungsstatus und den Zeitplan der Topics API.
  3. Bedeutung der API für die Anzeigenrelevanz auch in Zukunft ohne Cookies
  4. Wenn Sie über Statusänderungen in der API informiert werden möchten, treten Sie der Mailingliste für Entwickler bei und halten Sie sich über die neuesten Topics-Updates auf dem Laufenden.
  5. Aktuelle Informationen zur Topics API
  6. Sie können über GitHub-Probleme oder W3C-Anrufe zur Unterhaltung beitragen.
  7. Wenn Sie auf unbekannte Begriffe stoßen, sehen Sie sich das Privacy Sandbox-Glossar an.
  8. Weitere Informationen zu Chrome-Konzepten wie Chrome-Flags finden Sie in den kurzen Videos und Artikeln unter goo.gle/cc.

Build lokal erstellen und testen

In diesem Abschnitt wird beschrieben, wie Sie die Topics API als einzelner Entwickler ausprobieren.

  1. Lokale Tests und Bereitstellung (geschätzte Zeit: etwa 2 Tage)
    1. Aktivieren Sie die API in Ihrem lokalen Browser über die Befehlszeile mit Funktions-Flags. Testen Sie die Header- und die JavaScript API-Demos, um Topics in Aktion zu sehen (Video mit Schritt-für-Schritt-Anleitung).
    2. Führen Sie das Topics-Collab aus, um die Inferenz von Themen mithilfe des Topics-Modells für maschinelles Lernen zu testen.

Topics im Browser aktivieren

Sie haben zwei Möglichkeiten, die Topics API für lokale Tests in Ihrer eigenen Chrome-Instanz zu aktivieren:

  1. Öffnen Sie chrome://flags/#privacy-sandbox-ads-apis und aktivieren Sie die Privacy Sandbox APIs.
  2. Empfohlen: Führen Sie Chrome über die Befehlszeile mit Chromium-Flags aus. Verwenden Sie dazu die spezifischen Parameter der Topics API, um die Konfiguration nach Bedarf zu konfigurieren.
Aktivieren Sie die Privacy Sandbox APIs unter chrome://flags/#privacy-sandbox-ads-apis.
Privacy Sandbox APIs aktivieren

Wenn Sie Chrome über die Befehlszeile ausführen, können Sie die Topics-Funktionen genauer steuern. Es ist beispielsweise möglich, Topics-Epochen (der Zeitraum, der von der API zur Berechnung der Nutzerinteressen verwendet wird) festzulegen und das Verhalten der API entsprechend Ihren Anforderungen zu konfigurieren.

Bei aktiviertem chrome://flags/#privacy-sandbox-ads-apis wird Ihre Befehlszeileneinstellung der Epoche überschrieben und auf den Standardwert zurückgesetzt (derzeit eine Woche).

Vorschau der Topics API-Mechanismen

Mit den Tools unter chrome://topics-internals können Sie sich lokal einen Einblick in die zugrunde liegenden Mechanismen der Topics API verschaffen.

Werfen Sie einen Blick auf die Topics API unter chrome://topics-internals.
Tab „Status der Themen“ in den Tools von chrome://topics-internals

Mit dem Topics API Internals-Tool können Sie den Klassifikator auf der Grundlage der von Ihnen besuchten Websites lokal testen.

Mit diesem Tool können Sie Folgendes überprüfen:

  • Status der Themen:Hier sehen Sie Themen, die für den aktuellen Nutzer beobachtet wurden.
  • Klassifikator:Für Hostnamen abgeleitete Themen in der Vorschau ansehen.
  • Funktionen und Parameter:Rufen Sie API-Parameterwerte auf, um zu prüfen, ob Funktions-Flags wie vorgesehen funktionieren.

Informationen zum Debuggen von Themen mit dem Internals-Tool

So gibt die API Themen zurück

Wenn in Chrome nicht genügend beobachtete Themen vorhanden sind, um die fünf Topthemen für eine Epoche (eine Woche) zu ermitteln, fügt die Topics API zufällige Themen hinzu, um die fünf wichtigsten Themen zu vervollständigen. Die Spalte „Interne Themen“ mit der Überschrift Echt oder zufällig gibt an, ob das betreffende Thema auf einer tatsächlichen Beobachtung oder einem zusätzlichen zufälligen „Padding“ basiert, um die ersten fünf Punkte zu vervollständigen. Weitere Informationen zu diesem Verfahren findest du in der Erläuterung.

Das Thema einer Epoche wird nach dem Zufallsprinzip aus den fünf relevantesten Themen des Nutzers für den jeweiligen Zeitraum ausgewählt. Wenn während der Epoche nicht genügend Themen beobachtet wurden, werden nach dem Zufallsprinzip fünf Themen ausgewählt. Diese zufällig ausgewählten Themen werden gefiltert.

Um den Datenschutz weiter zu verbessern und sicherzustellen, dass alle Themen repräsentiert werden können, besteht eine Wahrscheinlichkeit von 5 %, dass das für eine Epoche ausgewählte Thema nach dem Zufallsprinzip und nicht aus den beobachteten Themen ausgewählt wird. Wie im Beispiel oben, bei dem zu wenige Themen beobachtet wurden, werden diese zufällig ausgewählten Themen nicht herausgefiltert.

Weitere Informationen zur Auswahl von Themen finden Sie unter Klassifizierung von Themen.

Wichtige Empfehlungen

  1. Beenden Sie alle Chrome-Prozesse, bevor Sie den neuen Prozess mithilfe der Flags starten.
  2. Beim Testen in Ihrer lokalen Umgebung sollten Sie chrome://flags/#privacy-sandbox-ads-apis deaktivieren, da dadurch die Befehlszeileneinstellungen überschrieben und auf die Standardwerte zurückgesetzt werden.
  3. Auf der Seite zur Fehlerbehebung erfahren Sie, wie Topics lokal funktioniert.
  4. Wenn Sie Fragen haben, sehen Sie sich die Erläuterung der GitHub-Probleme an.
  5. Sollte die API nicht wie erwartet funktionieren, probiere unsere Tipps zur Fehlerbehebung aus.

MVP-Bereitstellung planen

Die Topics API ermöglicht den Zugriff auf Themen, die für einen Nutzer von Interesse sind, ohne dass die vom Nutzer besuchten Websites verfolgt oder sein Navigationsverlauf offengelegt werden muss.

Der Aufrufer der Topics API ist die Entität, die die document.browsingTopics()-JavaScript-Methode aufruft oder Themen mithilfe von HTTP-Anfrageheadern beobachtet und darauf zugreift. Der Aufrufer ist in diesem Fall Ihr Code und die eTLD+1, von der aus er aufgerufen wird. Wenn Sie die Topics API aufrufen, weisen Sie den Browser des Nutzers an, die für ihn relevanten Themen zu beobachten, wenn er eine Website besucht. Dieser Besuch wird dann bei der Themenberechnung für die nächste Epoche berücksichtigt.

Die Topics API wurde entwickelt, um Ergebnisse pro Aufrufer oder pro eTLD+1 des aufrufenden Kontexts zu filtern. Das heißt, der Ursprung des iFrames (bei Verwendung der JavaScript API) oder die URL der Abrufanfrage (bei Verwendung von Headern) wird als Aufrufer betrachtet und die Themen werden anhand dieses Aufrufers berechnet.

Das folgende Diagramm veranschaulicht diesen Ansatz:

Die Schritte, die die Topics API beim Besuch von Websites ausführt, auf denen die API verwendet wird.
Wie die API Themen überwacht und auf sie zugreift.

In diesem Diagramm:

  1. Ein Nutzer öffnet Chrome und ruft mehrere Websites auf (z. B. kundenA.beispiel oder kundenB.beispiel.br), die den iFrame Ihrer Anzeigentechnologie (Quelle: iFrame.adtech.beispiel) oder die Header zur Weiterleitung des Abrufaufrufs enthalten.
    • Chrome zeichnet Themen auf, die für diesen Nutzer relevant sind.
  2. Nach einer siebentägigen Navigation, bei der über die Topics API die Interessen der Nutzer erfasst werden, besucht derselbe Nutzer auf demselben Gerät die Zielwebsite (publisher-e.example). Die Topics API gibt eine Liste von Themen zurück. In diesem Beispiel wird ein Thema zurückgegeben, das aus der letzten Woche mit den Beobachtungen dieses Nutzers berechnet wurde.
    • Nur Browser von Nutzern, die Websites besucht haben, die von adtech.example in Schritt 1 beobachtet wurden, geben Themenergebnisse in Schritt 2 zurück. Wir nennen diesen Beobachtungsfilter, dass Sie keine Themen von Nutzern sehen können, die Sie noch nie gesehen haben.
  3. Mit dieser Liste (mit nur einem Thema) können Sie Ihre Back-End-API (ads.adtech.example/topics-backend) aufrufen, um Themendaten als Teil Ihres kontextbezogenen Datasets zu verwenden.
  4. Je nach Anwendungsfall können Sie nun auf die Themen zugreifen, die Sie in den letzten Wochen für diese Nutzer beobachtet haben, und ihnen so eine personalisiertere Nutzererfahrung bieten.

Topics API aufrufen

Es gibt zwei Möglichkeiten, die Themen für einen Nutzer zu beobachten und darauf zuzugreifen. Du kannst den

  • Die JavaScript API in einem iFrame:
    • Ich füge auf den Zielwebsites (Websites des Publishers) einen iFrame hinzu, der JavaScript-Code enthält, über den die Topics API mit document.browsingTopics() aufgerufen wird.
  • Option für Überschriften:
    • Rufen Sie (empfohlen) oder XHR ab (nicht empfohlen und nur während des abgeschlossenen Ursprungstests verfügbar):
      • Sie können über den Header „Sec-Browsing-Topics“ in Anfragen an das Back-End der Anzeigentechnologie auf Themen zugreifen. Dies ist die leistungsstärkste Option (niedrige Latenz bei der Beobachtung von Themen eines bestimmten Nutzers).
    • Über ein iFrame-Tag mit dem Attribut browsingtopics:
      • Sie können einen iFrame mit einem browsingtopics-Attribut hinzufügen. Chrome fügt dann die für die eTLD +1 des iFrames beobachteten Themen in den Sec-Browsing-Topics-Header der Anfrage für den iFrame ein.

Mit JavaScript und iFrames implementieren

Wir empfehlen, entweder die Topics JavaScript API-Demo oder die Header-Demo zu verzweigen und eine davon als Ausgangspunkt für Ihren Code zu verwenden.

Sie können ein <iframe>-Element in HTML einfügen oder einen iFrame dynamisch mit JavaScript hinzufügen. Eine Möglichkeit, einen iFrame dynamisch zu erstellen, ist mit folgendem JavaScript-Code:

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

Prüfen Sie mithilfe der Funktionserkennung, ob die Topics API auf diesem Gerät unterstützt und 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');

Rufen Sie die Topics API innerhalb dieses iFrames auf:

const topics = await document.browsingTopics();

Sie sollten eine Liste der Themen erhalten, die für diesen Nutzer in den letzten drei Wochen beobachtet wurden. Diese Liste kann leer sein oder ein, zwei oder drei Themen aus den letzten drei Wochen enthalten.

Hier ist ein Beispiel dafür, was die API zurückgibt:

[{'configVersion': String, 
  'modelVersion': String, 
  'taxonomyVersion': String, 
  'topic': Number, 
  'version': String}]
  • configVersion: Ein String zur Identifizierung der aktuellen Konfiguration.
  • modelVersion: Ein String, der den Klassifikator für maschinelles Lernen identifiziert, der zur Ableitung von Themen verwendet wird.
  • taxonomyVersion: ein String, der die aktuell vom Browser verwendeten Themen identifiziert.
  • topic: Eine Zahl, die das Thema in der Taxonomie identifiziert.
  • version: ein String, der configVersion und modelVersion kombiniert.

Weitere Informationen zu dieser Implementierung

Mit HTTP-Headern implementieren

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

Anfrage- und Antwortheader zum Festlegen und Abrufen von Themen.
Header für iFrame und fetch()

Sie können in Anfrageheadern angegebene Themen als beobachtet markieren, indem Sie in der Antwort auf die Anfrage einen Observe-Browsing-Topics: ?1-Header festlegen. Anhand dieser Themen berechnet der Browser dann die Interessengebiete eines Nutzers.

Wenn die API ein oder mehrere Themen zurückgibt, enthält eine Abrufanfrage an die eTLD+1, von der die Themen beobachtet wurden, einen Sec-Browsing-Topics-Header, der so aussieht: 

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

Wenn die API keine Themen zurückgibt, sieht der Header so aus:

();p=P0000000000000000000000000000000

Sec-Browsing-Topics-Headerwerte werden aufgefüllt, um das Risiko zu verringern, dass ein Angreifer die Anzahl der einem Anrufer zugeordneten Themen anhand der Headerlänge erfährt.

Mit fetch() implementieren

Fügen Sie auf der Publisher-Seite den Code für die Abrufanfrage ein und achten Sie dabei darauf, {browsingTopics: true} anzugeben.

fetch('<topics_caller_eTLD+1>', {browsingTopics: true})
    .then((response) => {
        // Process the response
 })

In Browsern, die die API unterstützen, enthält die fetch()-Anfrage einen Sec-Browsing-Topics-Header, in dem die für den Hostnamen der Anfrage-URL beobachteten Themen aufgeführt sind.

Mit einem iFrame implementieren

Ähnlich wie bei einer fetch()-Anfrage wird der Sec-Browsing-Topics-Header gesendet, wenn das Attribut browsingtopics in einem iFrame verwendet wird.

<iframe src="<topics_caller_eTLD+1>" browsingtopics></iframe>

In diesem Fall ist der Aufrufer, ähnlich wie beim Abrufaufruf.

Serverseitig – für alle Fälle identisch

Damit die Themen im Sec-Browsing-Topics-Anfrageheader vom Browser als beobachtet markiert werden, aber auch der aktuelle Seitenbesuch bei der nächsten Berechnung des Top-Themas des Nutzers der nächsten Epoche berücksichtigt wird, muss die Antwort des Servers Observe-Browsing-Topics: ?1 enthalten.

Hier ein JavaScript-Beispiel mit setHeader():

res.setHeader('Observe-Browsing-Topics', '?1');

Themen: Backend-Implementierung

Das Hinzufügen eines Back-Ends für die Topics API ist optional. Ihre Auswahl hängt davon ab, wie und wo Sie die auf dem Gerät (im Browser) berechneten Themen verwenden möchten. 

// Use the language/framework/stack of your preference
function processTopicsBackendAPI(topics, user, domain, caller) {
  // Validate inputs
  // If the list is not empty, continue
  // Use topics as an additional contextual signal
}

Themen als Kontextdaten verwenden

Topics-Daten können zusammen mit anderen Signalen wie URLs, Keywords und sogar Tags als zusätzliches Signal zu Ihrer Zielgruppe betrachtet werden.

Wie im Abschnitt Anzeigenrelevanz ohne Drittanbieter-Cookies maximieren beschrieben, gibt es mehrere Ansätze, um mit der Topics API relevante Anzeigen auszuliefern. Bei einigen dieser Ansätze werden Topics zum Aufbau von Zielgruppen verwendet, andere empfehlen, die Topics API als ein Signal unter anderen zu nutzen, um Modelle für maschinelles Lernen zu trainieren. Diese werden verwendet, um zusätzliche Interessen der Zielgruppe abzuleiten oder sogar die Gebotslogik zu optimieren.

Erstellen und bereitstellen

  1. Themen durch Beobachtung von Nutzern in der Produktion erfassen, noch nicht skaliert (geschätzte Zeit: etwa 1 Woche)
    1. Informieren Sie sich über Ihre Optionen: iFrame und JavaScript oder HTTP-Header.
    2. Definieren Sie die Domain des iFrames.
    3. Erstellen Sie den JavaScript-Code mithilfe der Demo-App als Codereferenz oder implementieren Sie die Option für Header.
    4. Stellen Sie Topics in Ihrer kontrollierten Umgebung (einige Produktionswebsites) bereit.
    5. Fügen Sie einigen Zielwebsites die Topics-Implementierung hinzu (derzeit maximal fünf Websites).
    6. Funktionstests und Validierung
  2. [Optional] Topics-Daten als Kontextsignal verwenden (mit URLs, Tags usw.) (Geschätzte Zeit: etwa 3 Tage).
    1. Nachdem Sie die Liste der Themen erhalten haben, können Sie sie zusammen mit anderen Kontextsignalen an Ihr Backend senden.

Auf einigen Zielwebsites bereitstellen

Jetzt, wo Sie den Code haben, fügen wir ihn für einen ersten Test einigen Zielwebsites hinzu, um sicherzustellen, dass die API stabil ist und in dieser kontrollierten Umgebung funktioniert.

Wir empfehlen die Auswahl von Zielwebsites, die:

  • Eine geringe Anzahl monatlicher Besuche erzielen (weniger als 1 Million Besuche/Monat): Zuerst sollten Sie die API für eine kleine Zielgruppe bereitstellen.
  • Sie sind Inhaber und Kontrolle: Bei Bedarf können Sie die Implementierung schnell und ohne komplexe Genehmigungen deaktivieren.
  • sind nicht geschäftskritisch: Da diese Implementierung die Nutzererfahrung beeinträchtigen kann, sollten Sie mit Zielwebsites mit geringem Risiko beginnen.
  • Insgesamt nicht mehr als fünf Websites: Sie benötigen im Moment nicht so viele Zugriffe und keine so hohe Präsenz.
  • Verschiedene Themen repräsentieren: Wählen Sie Websites für unterschiedliche Kategorien aus, z. B. eine über Sport, eine weitere über Nachrichten oder eine weitere zu den Themen Essen und Trinken. Mit dem internen Topics-Tool in Chrome können Sie Domains validieren und feststellen, wie sie mit dem Topics-Klassifikator für maschinelles Lernen klassifiziert werden. Weitere Informationen zur Fehlerbehebung finden Sie im Entwicklerleitfaden für die Topics API.

Funktionstests und Validierung

Wenn Sie die Topics API in dieser eingeschränkten Umgebung aufrufen, können Sie Folgendes erwarten:

  • Ein leeres Array mit Themen [], wenn dies der erste Anruf dieses Geräts für diese Website und den Anrufer in den letzten sieben Tagen ist.
  • Eine Liste mit null bis drei Themen, die die Interessen dieses Nutzers repräsentieren.
  • Nach sieben Tagen sollten Sie Folgendes erhalten:
    • Ein Thema, das das Interesse dieses Nutzers darstellt, berechnet aus dem Navigationsverlauf dieser Woche.
      • Ein wichtiges Detail: Wenn von Ihnen nicht genügend Themen für die Topics API zur Berechnung der fünf Top-Themen der Woche erfasst wurden, werden so viele zufällige Themen hinzugefügt, wie für die Gesamtzahl der fünf Themen erforderlich sind. Weitere Informationen zur API
  • Ein neuer Themeneintrag, der eine der drei ersetzt, wenn Sie es nach vier Wochen Beobachtung aufrufen.
  • Wenn Sie mehr als drei Wochen lang keine Themen des Nutzers beobachtet haben, gibt die Topics API wieder ein leeres Array [] zurück.

Messen Sie die Leistung und Messwerte Ihrer Nutzererfahrung.

  • Die Laufzeit der JavaScript-Aufrufe an die Topics API in einem ursprungsübergreifenden iFrame sollte für zukünftige Leistungsanalysen gemessen werden. Achten Sie darauf, Telemetriedaten korrekt in Ihrem Backend zu erfassen und zu speichern.
    • Ein weiterer möglicher Messwert zur Berechnung ist die Zeit, die für das Erstellen eines iFrames und postMessage() Themen nach dem Empfang von Themen benötigt wird.

Fehlerbehebung

Ich rufe die Topics API auf, aber ich erhalte als Ergebnis „null“. Was kann ich tun?
Wenn Sie die Topics API innerhalb der ersten Woche nach der Beobachtung eines Nutzers aufrufen, ist das zu erwarten.

Wichtige Empfehlungen

  1. Testen Sie Ihren Frontend-Code, um sicherzustellen, dass Ihr JavaScript-Code wie erwartet funktioniert.

  2. Testen Sie Ihr Backend, um die Themenergebnisse zu erhalten.

    1. Achten Sie darauf, dass die Datentypen und Backend-API-Parameter richtig konfiguriert sind.
    2. Stellen Sie sicher, dass Ihr Backend für eine angemessene Skalierung konfiguriert ist.

  3. Unserer Erfahrung nach ist es wichtig, dass Sie mindestens drei Wochen warten, bevor Sie relevantere Themenergebnisse erhalten.

  4. Die Topics API ist nicht für alle Nutzer aktiviert:

    1. Nutzer können die Topics API explizit deaktivieren.
    2. Über die Seiten des Publishers kann die Richtlinie für Berechtigungen gesteuert werden. Weitere Informationen finden Sie im Entwicklerleitfaden für die Topics API (zur Deaktivierung).
    3. Weitere Informationen finden Sie unter chromestatus.com.

  5. Fügen Sie dieser Umgebung Messwerte und Beobachtbarkeit hinzu: Sie benötigen sie für die Analyse der ersten Ergebnisse. Beispiele für Messwerte:

    1. Latenz von Aufrufen
    2. HTTP-Fehler bei Topics-Aufrufen

  6. Versuchen Sie, Änderungen an der Implementierung in den ersten drei Wochen einzuschränken.

Auf Produktion skalieren

Im Folgenden finden Sie eine Schritt-für-Schritt-Zusammenfassung, wie Sie für die Produktion skalieren können. Die dafür erforderlichen Schritte sind nachfolgend beschrieben.

  1. Implementierung skalieren (Produktion) Dies wird unten beschrieben.
    1. Sie können den iFrame auf den Websites mehrerer Publisher einfügen.
  2. Themendaten verarbeiten und verwenden (geschätzte Dauer: etwa 4 Wochen)
    1. Themendaten als additives Signal neben anderen Daten einbinden
    2. Partner für Echtzeitgebote beziehen.
    3. Dienstprogrammtests mit Themen als zusätzliches Signal zu Ihren anderen Daten durchführen.

Implementierung skalieren

Jetzt sollten die Themendaten von einigen Websites in einer kontrollierten Umgebung erfasst werden und Sie können die gesamte Lösung mit größerer Sicherheit einschätzen.

Jetzt ist es an der Zeit, diese Implementierung zu skalieren, indem Sie denselben Code auf mehr Zielwebsites bereitstellen. So können Sie mehr Nutzer beobachten, mehr Daten zu Themen erheben und Ihre Zielgruppen besser verstehen.

Wir empfehlen Folgendes:

  1. Nach und nach auf allen Websites bereitstellen, insbesondere bei hohem Traffic-Volumen
  2. Führen Sie Belastungstests für Ihre Themendaten gemäß dem erwarteten Traffic durch.
    1. Stellen Sie sicher, dass Ihr Backend eine große Anzahl von Anrufen verarbeiten kann.
    2. Richten Sie Messwerterfassung und Logs für die Analyse ein.
  3. Prüfen Sie direkt nach der Bereitstellung der Topics API Ihre Messwerte auf schwerwiegende Probleme von Endnutzern. Prüfen Sie Ihre Messwerte regelmäßig.
  4. Bei einer Unterbrechung oder einem unerwarteten Verhalten können Sie ein Rollback der Bereitstellung durchführen und die Logs analysieren, um das Problem zu verstehen und zu beheben.

Reagieren und Feedback geben