Topics API: integration guide

The Topics API for Android is designed to support interest-based advertising without relying on cross app identifiers.

Advertisers strive to serve relevant ads that relate to a user's interest. For example, if a user is interested in information related to cooking, they might find cooking-related ads to be more relevant to them than ads that aren't related to their interests.

Interest-based advertising (IBA) is a form of personalized advertising in which ads are selected based on interests of the user. With the Privacy Sandbox on Android, these interests are derived from apps that the user has engaged with. This is different from contextual advertising, which is based solely on the interests derived from the current content being viewed. IBA enables apps to show ads that are more relevant and engaging than contextual ads.

IBA typically involves communication between apps, sellers, and buyers. This guide is intended for all of these parties, including networks and ad techs that operate as both buyers and sellers.

The Topics API infers coarse-grained interest signals on-device based on a user's app usage. These signals, called topics, are shared with advertisers to support IBA without the need to track individual users across apps.

There are important high level considerations when implementing interested-based advertising with the Topics API:

  • The inference of user interest is processed on the device: The user's information about exactly what apps are installed on the user's device does not leave the device, and privacy is protected. This model is in contrast to the current commonly-used model of having a user's cross-app data being sent and processed off the device, on ad tech servers. Certain types of processing will continue to remain on ad tech servers, such as using the signals provided by the Topics API in personalization and optimization models for ad selection.

  • Buyers and advertisers depend on the sell-side: To get topics, sell-side apps and SDKs must establish a footprint by being an observer of the Topics API for at least 1 epoch.

Terminology

  • Advertiser: A company that engages users through means of buying ad inventory
  • Publisher: A company that sells ad inventory that is available alongside their content
  • Buyer (or buy-side): An ad tech company that facilitates advertisers in buying ad inventory
  • Seller (or sell-side): An ad tech company that facilitates publishers in selling ad inventory
  • Network: An ad tech company that acts as both a buyer and a seller
  • Owned & operated: A company that acts as the publisher, seller, and buyer

Goals

If IBA is important to your business, we want you to have a version of the Topics API running in the context of your app's business cases so we can get your feedback and enable you to shape the API. We want to ensure that you can unblock designs and development so that you can get topics when the beta launches.

At this time, the goals of integration planning for the Privacy Sandbox on Android Developer Preview include the ability to do the following:

For all ad techs

  • Review the Topics taxonomy and give feedback about included topics.
  • Experiment with the Topics API sample apps to see what topics data is returned from the on-device classifier.
  • Update app and SDK flows to start calling the Topics API.
  • Update protocols to start sending topics in ad requests.
  • Enroll your ad tech with the Privacy Sandbox.

For sell-side ad techs

  • Become an observer to establish a Topics API footprint. The Topics API is a new signal, so you should update your SDK to start calling the Topics API. To consistently retrieve topics, apps must call the API at least once per epoch. It takes up to 4 epochs to get the maximum amount of topics (3 topics) to send with your ad requests.
  • Include Topics API information in your ad requests. For each ad request, start sharing your Topics API data with buy-side partners. The Topics API plans to supplement other signals (such as contextual signals) to help find an appropriate advertisement for a given visitor.
  • Collaborate on a protocol for sharing topics with your buy-side partners. The Topics API needs each SDK to work with downstream partners to agree on how Topics API data is shared.

For buy-side ad techs

  • Connect with sell-side partners to confirm their plans to observe topics and establish footprint. To receive topics, sell-side providers must call the Topics API at least once per epoch.
  • Collaborate on a protocol for receiving topics from your sell-side partners. Topics is a new signal that will be shared by sell-side partners as part of the ad request. Buy-side consumers will need to ensure they work with their upstream partners on how topics will be shared.
  • Incorporate topics in bidding and optimization models. The Topics API is expected to supplement other signals like contextual to help find an appropriate advertisement for the visitor.

Prerequisites and setup

App developers, sellers, and buyers should follow these steps to get set up for using the Topics API.

Familiarize yourself with the API

  1. Begin by reading the design proposal to familiarize yourself with the Topics API and its capabilities.
  2. Read the developer guide to learn how to incorporate the code and API calls that you need for your use cases.
  3. Review the taxonomy and provide feedback on what topics are included in the list.
  4. Submit feedback for the design proposal or documentation.
  5. Sign up to receive updates on the Topics API. This will help you stay current on new features that are introduced in future releases.

Setup and test the sample app

  1. Follow the instructions on this page to set up the Privacy Sandbox on Android SDK in Android Studio.
  2. Fork and run the code in the Java or Kotlin version of the sample app to familiarize yourself with how to retrieve topics on a device.
  3. While testing, experiment with app information for name and description to change what topics will return from the on-device classifier.
  4. After you understand how the client API and on-device classifications work, use the sample app as an example to guide your own integration.

Tip: Carefully review the usefulness of the topics data that is returned for your app. Identify ways in which you think the classification or taxonomy could be improved, and submit feedback if you have recommendations on how to improve the taxonomy.