Integrationsanleitung für die Topics API

Hier erfahren Sie, wie Sie mit der Topics API bestimmte Anwendungsfälle im Bereich Anzeigentechnologie erfüllen.

Hinweis

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

1. Entwicklerdokumentation lesen:
   1. Lesen Sie sich zuerst die Übersicht durch, um sich mit der Topics API und ihren Funktionen vertraut zu machen.
   2. Sehen Sie sich die Anleitung zur Topics-Demo (Video) an.
   3. Probieren Sie die Demos für den Topics-Header und die JavaScript API aus.
   4. Verzweigen Sie die Demos (beide enthalten Links zu ihrem Code) und führen Sie sie von 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. Die Rolle der API bei der Unterstützung der Anzeigenrelevanz auch in Zukunft ohne Cookies
4. Wenn Sie über Statusänderungen in der API informiert werden möchten, registrieren Sie sich für die Mailingliste für Entwickler und halten Sie sich über die neuesten Updates zu Topics auf dem Laufenden.
5. Bleiben Sie auf dem Laufenden über die neuesten Nachrichten zur Topics API.
6. Leisten Sie einen Beitrag über GitHub-Probleme oder W3C-Anrufe.
7. Wenn Sie auf unbekannte Begriffe stoßen, lesen Sie das Privacy Sandbox-Glossar.
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 können.

1. Lokales Testen und Bereitstellen (geschätzte Dauer: etwa 2 Tage)
   1. Aktivieren Sie die API mit Ihrem lokalen Browser über die Befehlszeile mit Funktions-Flags. Testen Sie den header und die JavaScript API-Demos, um die Topics API in Aktion zu sehen (Video mit Schritt-für-Schritt-Anleitung).
   2. Führen Sie das Topics Colab aus, um die Inferenz der Themen mit dem Topics-Modell für maschinelles Lernen zu testen.

Topics im Browser aktivieren

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

1. Alle APIs zum Datenschutz bei Werbung unter chrome://settings/adPrivacy aktivieren.
2. Empfohlen: Führen Sie Chrome über die Befehlszeile mit Chromium-Flags und Topics API-spezifischen Parametern zur Konfiguration nach Bedarf aus.

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

Vorschau der Funktionsweise der Topics API

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

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

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

• Topics State (Themenstatus): Hier werden die Themen angezeigt, die für den aktuellen Nutzer beobachtet wurden.
• Klassifikator:Vorschau der für Hostnamen abgeleiteten Themen.
• Funktionen und Parameter:Überprüfen Sie anhand der API-Parameterwerte, ob Funktions-Flags wie vorgesehen funktionieren.

Informationen zum Debuggen von Topics mit dem Tool „Internals“

So gibt die API Themen zurück

Wenn in Chrome nicht genügend beobachtete Themen vorhanden sind, um die fünf wichtigsten Themen für eine Epoche (eine Woche) zu erstellen, fügt die Topics API zufällige Themen hinzu, um die fünf wichtigsten Themen zu vervollständigen. Die Überschrift der Spalte „Interne Themen“ mit der Überschrift Real oder zufällig gibt an, ob das jeweilige Thema auf einer realen Beobachtung oder auf zusätzlichen zufälligen „Padding“ beruht, um die fünf Top-5 abzuschließen. Weitere Informationen zu diesem Mechanismus finden Sie in der Erläuterung.

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

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

Weitere Informationen zur Auswahl von Themen finden Sie unter Themenklassifizierung.

Wichtige Empfehlungen

1. Schließen und beenden Sie alle Chrome-Prozesse, bevor Sie einen neuen Prozess mithilfe der Flags starten.
2. Unter chrome://settings/adPrivacy müssen alle APIs zum Datenschutz bei Werbung aktiviert sein.
3. Verwenden Sie die Fehlerbehebungsseite, um zu verstehen, wie Topics lokal funktioniert.
4. Wenn Sie Fragen haben, lesen Sie die Erläuterung zu GitHub-Problemen.
5. Sollte die API nicht wie erwartet funktionieren, lesen Sie unsere Tipps zur Fehlerbehebung.

MVP-Bereitstellung planen

Über die Topics API erhalten Sie Zugriff auf Themen, die für einen Nutzer relevant sind, ohne dass Sie die vom Nutzer besuchten Websites verfolgen oder seinen Navigationsverlauf offenlegen müssen.

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

Die Topics API wurde zum Filtern von Ergebnissen pro Aufrufer oder pro eTLD+1 des aufrufenden Kontexts entwickelt. Mit anderen Worten, der Ursprung des iFrame (bei Verwendung der JavaScript API) oder die URL der Abrufanfrage (bei Verwendung von Headern) wird als Aufrufer betrachtet und die Themen werden entsprechend diesem Aufrufer berechnet.

Das folgende Diagramm veranschaulicht diesen Ansatz:

In diesem Diagramm:

1. Ein Nutzer ��ffnet Chrome und ruft mehrere Websites auf (z. B. „kundeA.beispiel“ oder „kundeB.beispiel.br“), auf denen sich der iFrame Ihrer Anzeigentechnologie (Quelle: iFrame.adtech.beispiel) oder die Header „Fetch-Aufruf“ weiterleiten lässt.
   • Chrome zeichnet die Interessen dieses Nutzers auf.
2. Nachdem innerhalb von sieben Tagen die Interessengebiete von der Topics API beobachtet wurden, besucht derselbe Nutzer auf demselben Gerät eine Zielwebsite (z. B. Publisher-Beispiel). Die Topics API gibt eine Liste von Themen zurück. In diesem konkreten Beispiel wird ein Thema zurückgegeben, das aus der vorangegangenen Woche der Beobachtungen dieses Nutzers berechnet wurde.
   • Nur Browser von Nutzern, die Websites besucht haben, die in Schritt 1 von adtech.example erfasst wurden, geben in Schritt 2 Themenergebnisse zurück. Diese Filterung bezeichnen wir als Beobachtungsfilter. Sie können keine Themen von Nutzern sehen, die Sie noch nie gesehen haben.
3. Mit dieser Liste (von vorerst 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. Abhängig von Ihrem Anwendungsfall können Sie jetzt ein personalisierteres Erlebnis für diesen Nutzer schaffen, indem Sie auf die Interessengebiete zugreifen, die Sie in den letzten Wochen für ihn beobachtet haben.

Topics API aufrufen

Sie haben zwei Möglichkeiten, die Themen für einen Nutzer zu beobachten und darauf zuzugreifen. Mit

• In der JavaScript API in einem iFrame:
  • Einen iFrame auf Zielwebsites (Websites des Publishers) hinzufügen, der JavaScript-Code zum Aufrufen der Topics API mit document.browsingTopics() enthält.
• Header-Option:
  • Fetch (empfohlen) oder XHR (nicht empfohlen und war nur während des abgeschlossenen Ursprungstests verfügbar):
    • Sie können auf Themen über den Sec-Browsing-Topics-Header in Anfragen an das AdTech-Back-End zugreifen. Dies ist die leistungsstärkste Option (niedrige Latenz, um Themen eines bestimmten Nutzers zu beobachten).
  • iFrame-Tag mit dem Attribut browsingtopics verwenden:
    • Sie können einen iFrame mit einem browsingtopics-Attribut hinzufügen. Chrome fügt dann Themen (beobachtet für eTLD+1 des iFrames) in den Sec-Browsing-Topics-Header der iFrame-Anfrage ein.

Implementierung mit JavaScript und iFrames

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

Du kannst ein <iframe>-Element in HTML einfügen oder einen iFrame dynamisch mit JavaScript hinzufügen. Eine Möglichkeit, einen iFrame dynamisch zu erstellen, ist folgendes JavaScript:

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 in diesem iFrame auf:

const topics = await document.browsingTopics();

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

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

[{'configVersion': String, 
  'modelVersion': String, 
  'taxonomyVersion': String, 
  'topic': Number, 
  'version': String}]

• configVersion: Ein String, der die aktuelle Konfiguration identifiziert.
• modelVersion: Ein String, der den Klassifikator für maschinelles Lernen identifiziert, der zum Ableiten 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 die Themen kann über den Sec-Browsing-Topics-Header einer Abruf()/XHR-Anfrage oder einer iframe-Anfrage zugegriffen werden.

Sie können die in Anfrageheadern angegebenen Themen markieren, indem Sie in der Antwort auf die Anfrage einen Observe-Browsing-Topics: ?1-Header festlegen. Der Browser verwendet diese Themen dann, um die Interessen der Nutzer zu ermitteln.

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

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

Mit fetch() implementieren

Fügen Sie auf der Publisher-Seite den Code für die Abrufanfrage hinzu und geben Sie dabei {browsingTopics: true} an.

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, der die für den Anfrage-URL-Hostnamen beobachteten Themen auflistet.

Mit einem iFrame implementieren

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

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

In diesem Fall ist das der Aufrufer, ähnlich wie beim Fetch-Aufruf.

Serverseitig – in allen Fällen identisch

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

Hier ein JavaScript-Beispiel mit setHeader():

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

Topics-Backend-Implementierung

Das Hinzufügen eines Backends für Topics 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

Themenbezogene 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 nach Drittanbieter-Cookies maximieren erläutert, gibt es mehrere Möglichkeiten, mit Topics relevante Anzeigen auszuliefern. Bei einigen davon werden Themen zum Erstellen von Zielgruppen verwendet, bei anderen wird die Verwendung von Topics als ein Signal unter anderem empfohlen, um Modelle für maschinelles Lernen zu trainieren, mit denen zusätzliche Interessen der Zielgruppe abgeleitet oder sogar die Gebotslogik optimiert werden kann.

Erstellen und bereitstellen

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

Auf einigen Zielwebsites bereitstellen

Jetzt, da Sie über den Code verfügen, fügen wir ihn einigen Ziel-Websites für einen ersten Test hinzu, um sicherzustellen, dass die API stabil ist und in dieser kontrollierten Umgebung funktioniert.

Wir empfehlen die Auswahl von Websites, auf die Folgendes zutrifft:

• Geringe Anzahl von monatlichen Besuchen erzielen (weniger als 1 Million Besuche pro Monat): Sie sollten die API zuerst für eine kleine Zielgruppe bereitstellen.
• Sie sind Inhaber und haben die Kontrolle: Bei Bedarf können Sie die Implementierung ohne komplexe Genehmigungen schnell deaktivieren.
• sind nicht geschäftskritisch: Da diese Implementierung die Nutzererfahrung beeinträchtigen kann, beginnen Sie mit Zielwebsites mit niedrigem Risiko.
• Maximal fünf Websites: Für den Moment sind nicht so viele Zugriffe oder Präsenz erforderlich.
• Verschiedene Themen repräsentieren: Wählen Sie Websites aus, die unterschiedliche Kategorien repräsentieren, z. B. eine zu Sport, eine weitere zu Nachrichten oder eine weitere zu Essen und Trinken. Sie können das Tool für interne Themen in Chrome verwenden, um Domains zu prüfen und zu überprüfen, wie sie mithilfe des Topics-Klassifikators für maschinelles Lernen klassifiziert werden. Weitere Informationen zum Debugging finden Sie im Entwicklerleitfaden für die Topics API.

Funktionstests und Validierung

Beim Aufrufen der Topics API in dieser begrenzten Umgebung ist Folgendes zu erwarten:

• Ein leeres Themen-Array [], wenn dies der erste Aufruf 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 des Nutzers repräsentieren.
• Nach sieben Tagen der Beobachtung sollten Sie Folgendes erhalten:
  • Ein Thema, das das Interesse dieses Nutzers darstellt, berechnet aus dem Navigationsverlauf der jeweiligen Woche.
    • Ein wichtiges Detail: Wenn Sie für einen Nutzer nicht genügend Themen ermittelt haben, damit die Topics API die fünf wichtigsten Themen dieser Woche berechnen kann, werden mit der Topics API so viele zufällige Themen hinzugefügt, wie erforderlich sind, um die Gesamtzahl der fünf Themen zu ermitteln. Weitere Informationen zur API
• Ein neuer Themeneintrag, der einen der drei ersetzt, wenn Sie ihn nach vier Wochen Beobachtung anrufen.
  • Dies liegt daran, dass die Topics API in den nächsten Wochen stabil bleibt und nicht zu viele Interessen des Nutzers offenlegt. Weitere Details auf GitHub
• Wenn du länger als drei Wochen keine Themen für den Nutzer beobachtet hast, gibt die Topics API wieder ein leeres Array [] zurück.

Messen Sie die Leistung und Messwerte der Nutzererfahrung.

• Die Laufzeit der JavaScript-Aufrufe an die Topics API in einem ursprungsübergreifenden iFrame sollte gemessen werden, um bei künftigen Leistungsanalysen verwendet zu werden. Achten Sie darauf, Telemetriedaten in Ihrem Back-End richtig zu erfassen und zu speichern.
  • Ein weiterer möglicher Messwert, der berechnet werden kann, ist die Zeit, die nach Erhalt der Themen für das Erstellen eines iFrames und von postMessage() Themen benötigt wird.

Fehlerbehebung

Ich rufe die Topics API auf, erhalte aber null als Ergebnis. 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 erwartungsgemäß funktioniert.

2. Testen Sie Ihr Backend, um die Ergebnisse der Themen zu erhalten.

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

3. Unserer Erfahrung nach sollten Sie mindestens drei Wochen warten, bevor Sie relevantere Ergebnisse zu Themen erhalten.

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

   1. Nutzer können die Topics API explizit deaktivieren.
   2. Die Berechtigungsrichtlinie kann auf den Seiten des Publishers gesteuert werden. Entsprechende Informationen finden Sie im Entwicklerleitfaden zur Topics API.
   3. Weitere Informationen finden Sie unter chromestatus.com.

5. Fügen Sie dieser Umgebung Messwerte und Beobachtbarkeit hinzu. Sie benötigen sie, um die ersten Ergebnisse zu analysieren. Beispiele für Messwerte:

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

6. Versuchen Sie, Änderungen an Ihrer Implementierung in den ersten drei Wochen zu begrenzen.

Auf Produktion skalieren

Hier ist eine Schritt-für-Schritt-Zusammenfassung dazu, wie Sie für die Produktion skalieren können. Die Schritte sind nachfolgend beschrieben.

1. Implementierung skalieren (Produktion). Dieser Vorgang wird unten beschrieben.
   1. iFrame zu den Websites mehrerer Publisher hinzufügen
2. Themendaten verarbeiten und verwenden (geschätzte Zeit: etwa 4 Wochen).
   1. Themendaten als zusätzliches Signal mit anderen Daten ergänzen
   2. Partner für Echtzeitgebote finden.
   3. Führen Sie Dienstprogrammtests mit Themen als zusätzliches Signal zu Ihren anderen Daten durch.

Implementierung skalieren

An dieser Stelle sollten Sie über Themendaten von einigen Websites in einer kontrollierten Umgebung verfügen, die ein höheres Maß an Zuverlässigkeit in Bezug auf die gesamte Lösung bietet.

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 Themendaten erfassen und Ihre Zielgruppen besser verstehen.

Wir empfehlen Folgendes:

1. Führen Sie die Bereitstellung schrittweise auf Ihren Websites durch, insbesondere bei hohem Traffic-Volumen.
2. Führen Sie Belastungstests für Ihre Themendaten entsprechend dem erwarteten Traffic durch.
   1. Vergewissern Sie sich, dass Ihr Back-End eine große Anzahl von Anrufen bewältigen kann.
   2. Messwerterfassung und Logs für die Analyse einrichten.
3. Prüfen Sie sofort nach der Bereitstellung der Topics API Ihre Messwerte, um schwerwiegende Endnutzerprobleme zu erkennen. Überprüfen Sie Ihre Messwerte regelmäßig.
4. Bei einer Unterbrechung oder unerwartetem Verhalten führen Sie ein Rollback der Bereitstellung durch und analysieren Ihre Logs, um das Problem zu verstehen und zu beheben.

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.