Topics API für Mobilgeräte: Übersicht

Informationen zur Topics API auf Android-Geräten und zur Implementierung Du kannst auch direkt mit der Implementierung von Themen beginnen.

How the Topics API works

The Topics API can be used to observe and provide access to topics that appear to be of interest to the user, based on their activity. The Topics API can then give API callers (such as ad tech platforms) access to a user's topics of interest, but without revealing additional information about the user's activity.

Key concepts

  • A topic is a human-readable topic of interest for the current user and is part of the Topics taxonomy.
  • A caller is an entity, such as an app, a third-party SDK, a website, or service, that makes a request to the Topics API to observe or access a user's interests.
  • A topic is observed by a caller, if the caller made a Topics API request from a web page or app associated with this topic during the past three epochs.
  • An epoch is a period of topic computation, which defaults to one week.
  • A taxonomy is a hierarchical list of categories, which includes, for example, such categories as /Arts & Entertainment/Music & Audio/Soul & R&B and /Business & Industrial/Business Services/Corporate Events.
  • Topics are derived using a classifier model that maps user activity to zero or more topics.

Topics API flow core steps

The Topics API lifecycle has three main steps:

  • Observe user activity, such as when they visit the web page https://cats.example/tabby/index.html or download the app cats.
  • Derive topics from user activity, for example /Pets & Animals/Pets/Cats.
  • Access topics previously observed for the user, for example as a signal to select relevant advertising (such as a cat food promotion).

Observe topics

Callers can only access topics of interest that they've observed. A caller observes a topic when they make a Topics API request from a context associated with this topic. To illustrate this concept, consider the following simplified example.

  • Suppose there are two Topics API callers: A and B.
  • There are two contexts:
    • Greenhouse, for example an app named Greenhouse or a website greenhouse.example, associated with the topic Home & Garden.
    • Tennis exercises, for example an app named Tennis Exercises or a website tennis.example, associated with the topic Sports/Tennis.
  • Both caller A and B are present in the context of Greenhouse.
  • Only the caller B is present in the context of Tennis exercises.
  • Assume that no topics were observed for the user before epoch 1, for the sake of simplification.
  • The user visits the Greenhouse app, and callers A and B make a Topics API call to record the user visit to the page or app (see the implementation guide suggested in Next steps to find out how to call the Topics API). This record (a hostname or app data) is later used to derive topics of interest. The Topics API will later mark the topic Home & Garden as observed by both callers A and B.
  • The user visits the Tennis exercises app. Only the caller B sends a Topics API request. The Topics API will later mark the topic Sports/Tennis as observed by the caller B.
  • By the end of the epoch, the Topics API refreshes the user's top topics and determines the callers that observed these topics based on user activity.
  • Later, when the caller B makes another Topics API call, it can get either Home & Garden or Sports/Tennis topic (or, with a 5% chance, a random topic) for this user in the response array.
  • Caller A can only access the topic Home & Garden, as it has never observed the topic Sports/Tennis. This means that a third-party will only learn about a user's topic of interest within the specific context (app or website) where it is present.
Diagram showing that the Topics API only marks the topics as observed if the callers has presence in the context.
The Topics API marks the topics observed only by the callers that have presence in the context of these topics. The callers will only be able to access the topics they have observed.

Derive topics

Topics derives topics of interest from user activity. The topics are selected from a predefined open-source taxonomy. Once per epoch, Topics refreshes the user's top five topics and the callers that observed them during the epoch. The Topics classifier model derives topics from user activity: hostname for a web page visit, app information on Android.

Caller accesses user's topics of interest

The API returns only topics that have been observed by the caller within the most recent three epochs. A maximum of three topics may be returned to a caller,one topic for each of the three recent epochs (if the caller observed topics for that epoch). The returned topics can be used by the caller to supplement any contextual information and can be combined to help find a more relevant ad for the user.

Epochs

The Topics API must ensure that the topics of interest it provides are kept up to date. The topics are inferred for a user based on their activity during a period of time known as an epoch, one week by default. Each user has their own epochs (epochs are "per user") and the initial start time is randomized.

Once each epoch, the Topics API computes the user's top five topics and determines which callers observed those topics using on-device information. The topic selected for each epoch is randomly selected from the user's top five topics for that time period. To further enhance privacy and ensure that all topics may be represented, there is a 5% chance the topic is randomly selected from all possible topics in the taxonomy of interests.

Themen zu Android in der Praxis

Die Topics API auf Android wurde entwickelt, um Anzeigen-SDKs von Drittanbietern zu unterstützen, die in der Regel in mehreren Apps verwendet werden. Topics bietet Aufrufern grobkörnige Werbethemen, die auf der App-Nutzung des Nutzers basieren, ohne dass App-übergreifende Kennungen erforderlich sind. Diese Themen können verwendet werden, um Kontextinformationen zu ergänzen, die sich auf die App beziehen, in der eine Anzeige ausgeliefert werden soll. Sie können auch kombiniert werden, um eine geeignete Anzeige für den Nutzer auszuwählen.

Im Zusammenhang mit der Topics API sind Käufer und Werbetreibende von der Sell-Side abhängig. Die Verkäuferseite ist in den Apps des Publishers stark vertreten, beobachtet die Themen der Nutzer und teilt diese dann mit den Käufern, damit sie relevantere Anzeigen auswählen können. Damit Themen abgerufen werden können, müssen Apps und SDKs auf der Sell-Side mindestens eine Epoche lang als Beobachter der Topics API registriert sein.

Im Implementierungsleitfaden für die Topics API finden Sie Codebeispiele, die zeigen, wie Sie die Abruffunktion für Themen für interessenbezogene Werbung einrichten.

Themenintegration nach Unternehmenstyp

Aktivieren Sie die Topics API für interessenbezogene Werbung. Folgen Sie der Anleitung für Ihren AdTech-Unternehmenstyp, um die Topics API zu integrieren und sich auf die Einführung vorzubereiten.

Für alle Anzeigentechnologien

Für AdTech-Anbieter auf der Verkaufsseite

  • Melden Sie sich als Beobachter an, um einen Topics API-Footprint zu erstellen. Die Topics API bietet ein neues Signal. Sie müssen Ihr SDK also aktualisieren, um die Topics API aufzurufen. Damit Themen zuverlässig abgerufen werden können, muss dein SDK die API mindestens einmal pro Epoche aus Publisher-Apps aufrufen. Es dauert bis zu vier Epochen, bis die maximale Anzahl von Themen (drei Themen) für Ihre Anzeigenanfragen ermittelt wurde.
  • Fügen Sie Informationen zur Topics API in Ihre Anzeigenanfragen ein. Geben Sie Ihre Topics API-Daten für jede Anzeigenanfrage für Partner auf Käuferseite frei. Die Topics API soll andere Signale (z. B. Kontextsignale) ergänzen, um eine geeignete Werbung für einen bestimmten Besucher zu finden.
  • Erarbeiten Sie gemeinsam mit Ihren Buy-Side-Partnern ein Protokoll für die Weitergabe von Themen. Für die Topics API muss jedes SDK mit Downstream-Partnern vereinbaren, wie Topics API-Daten weitergegeben werden.

Für Anzeigentechnologien auf der Kaufseite

  • Wenden Sie sich an Partner auf der Sell-Side, um ihre Pläne zur Beobachtung von Themen und zum Aufbau einer Präsenz zu erfahren. Damit verkaufsseitige Anbieter Themen erhalten, müssen sie die Topics API mindestens einmal pro Epoche aufrufen.
  • Erarbeiten Sie gemeinsam mit Ihren Partnern auf der Verkaufsseite ein Protokoll für den Empfang von Themen. „Topics“ ist ein neues Signal, das von Partnern auf der Sell-Side im Rahmen der Anzeigenanfrage weitergegeben wird. Käufer müssen mit ihren Upstream-Partnern abstimmen, wie Topics weitergegeben werden.
  • Nehmen Sie Themen in Gebots- und Optimierungsmodelle auf. Die Topics API soll andere Signale wie Kontextsignale ergänzen, um eine geeignete Werbung für den Besucher zu finden.

So inferiert die API Themen für eine App

Unter Android leitet die Topics API Themen für eine App anhand von App-Informationen mithilfe eines Klassifizierungsmodells ab. In der aktuellen Implementierung werden in Topics App- und Paketnamen verwendet, um einer App Themen zuzuweisen. Dies kann später um weitere Informationen wie die App-Beschreibung erweitert werden.

Themenklassifikator

Themen von Interesse werden aus einem Klassifizierungsmodell abgeleitet, das mit öffentlich verfügbaren App-Informationen trainiert wird.

  • Wenn das Klassifizierungsmodell für die Inferenz verwendet wird, um die Themen für eine bestimmte Epoche zu berechnen, verbleiben die verwendeten Signale auf dem Gerät. Diese Signale können installierte oder kürzlich verwendete Apps umfassen und werden später möglicherweise um weitere Signale erweitert.
  • Das V5-Modell wurde von Google mit 540.000 von Menschen und 17 Millionen von ML-Systemen gekennzeichneten öffentlich zugänglichen App-Informationen aus App-Shops wie dem Google Play Store trainiert. Das Modell verwendet App- und Paketnamen als Eingabesignale und ist für App-Entwickler kostenlos verfügbar, damit sie testen können, zu welchen Themen ihre App klassifiziert wird.
  • Es ist möglich, dass eine App mehreren oder gar keinen Themen zugeordnet wird oder dass sie dem Themenverlauf des Nutzers nicht hinzugefügt wird. Wenn eine App mehreren Themen in der Taxonomie zugeordnet ist, wird die Anzahl der für diese App ausgewählten Themen auf die drei wichtigsten beschränkt.

Wenn Sie mehr über die Funktionsweise des Klassifizierungsmodells erfahren möchten, können Sie mit dem Android Topics Classifier Colab testen, wie sich unterschiedliche App-Daten auf die Klassifizierung auswirken.

Taxonomie

Die Themen werden aus einer vordefinierten Open-Source-Taxonomie ausgewählt. Die Taxonomie ist öffentlich zugänglich und kann sich ändern. Vorschläge können über die Feedbackschaltfläche oben auf dieser Seite eingereicht werden. Diese Taxonomie wird von Menschen kuratiert, sodass sensible Themen nicht Teil der Taxonomie sind. Sie ist auf die Anzeigenkategorien zugeschnitten, die in mobilen Apps auf Android-Geräten ausgeliefert werden können.

Themen zu Android in der Praxis

Angenommen, ein Nutzer hat sieben Apps auf dem Gerät installiert: A, B, C, D, E, F und G. Angenommen, die Themenklassifizierung für die App und die SDKs für Anzeigentechnologien in diesen Apps ist so:

App Themenklassifizierung AdTech-SDK
A T1, T5 ad-sdk1, ad-sdk2
B T2 ad-sdk2
C T3, T6 ad-sdk3, ad-sdk4
D T1, T4 ad-sdk1
E T5 ad-sdk4, ad-sdk5
F T6 ad-sdk2, ad-sdk3, ad-sdk4
G T7 ad-sdk2

Ende der ersten Woche: Die Topics API generiert die fünf wichtigsten Themen des Nutzers für diese Epoche.

Top-Thema Anrufer, die mehr über das Thema erfahren möchten
T1 ad-sdk1, ad-sdk2
T2 ad-sdk2
T3 ad-sdk3, ad-sdk4
T4 ad-sdk1
T5 ad-sdk1, ad-sdk2, ad-sdk4, ad-sdk5

Wenn in Woche 2 ein Nutzer in einer App die API aufruft, enthält die zurückgegebene Themenliste nur Themen, für die der Nutzer in der Spalte „Nutzer, die mehr über das Thema erfahren können“ für dieses Thema für diese App für diese Epoche steht.

  • Der Verlaufszeitraum, der bei der Berechnung der für jeden Anrufer verfügbaren Themen berücksichtigt wird, umfasst drei Epochen (oder drei Wochen).
  • Es werden nur Themen verwendet, die mit Apps verknüpft sind, die die Topics API über Anzeigen-SDKs aufrufen. Wenn eine App also keine Anzeigen-SDKs enthält, die die Topics API aufrufen, tragen die mit dieser App verknüpften Themen nicht zum Pool der Themen bei, auf die über Anzeigen-SDKs zugegriffen werden kann.
  • Eine App kann die Topics API auch deklarativ deaktivieren. Themen, die mit deaktivierten Apps verknüpft sind, werden bei der wöchentlichen Themenberechnung nicht berücksichtigt. Dieses Dokument wird um entsprechende Implementierungsdetails ergänzt.

Wenn die App nicht ausreichend genutzt wird, um fünf Themen zu ermitteln, kann die Plattform Optionen wie die zufällige Generierung der verbleibenden Themen in Betracht ziehen.

Verschlüsselung der zurückgegebenen Themen

Registrierte AdTech-Plattformen, die die Topics API aufrufen, müssen außerdem Verschlüsselungsschlüssel angeben, damit die zurückgegebenen Themen nur für den Aufrufer lesbar sind.

Die Privacy Sandbox ruft diese Schlüssel vom von der Anzeigentechnologie bereitgestellten Endpunkt ab . Wir empfehlen, die Schlüssel regelmäßig, aber mindestens alle sechs Monate zu aktualisieren.

In der Privacy Sandbox werden Anbieter von Anzeigentechnologien gebeten, die Verfügbarkeit des Endpunkts zu bestätigen, den sie während des Registrierungsprozesses angeben. Weitere Informationen zu den erforderlichen Maßnahmen für bestehende und neu registrierte Anbieter von Anzeigentechnologien finden Sie im Anmeldeleitfaden.

Next steps

Check out implementation details and code samples for callers to observe and access topics.
Learn how users and developers can manage and customize the Topics API to suit user's preferences and needs.

See also

Check out our resources to better understand the Topics API on Android.