Privacy Sandbox on Android Developer Preview is here! Learn how to get started, and continue to provide feedback.

Interest-based advertising with the Topics API

Provide feedback

About the Topics API

In mobile advertising, advertisers want 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 an ad is selected for the user based on interests derived from the apps with which the user has engaged in the past. This is different from contextual advertising, which is based solely on the interests derived from the current content being viewed. One of IBA's benefits over contextual advertising is that IBA enables apps to show more relevant and engaging ads to users.

The Topics API infers coarse-grained interest signals on-device based on a user's app usage. These signals, called topics, will be shared with advertisers, supporting IBA use cases without requiring tracking of individual users across apps.

Key concepts

  • A topic is a human-readable topic of interest for this user and is part of the Topics taxonomy.
  • A topic is observed by a caller (an app or a third-party SDK used in the app) if the caller made a Topics API request from an app associated with this topic during the past 3 epochs.
  • An epoch is a period of topic computation, such as one week.

How it works

With this proposal, the Topics API intends to provide callers with coarse-grained advertising topics of interest based on the user's app usage. These topics can be used to supplement any contextual information related to the app that wants to display an ad and can be combined to help find an appropriate ad for the user.

Refer to the Topics API developer guide for code examples that demonstrate how to set up the ability to fetch topics for interest-based advertising. Note: APIs are not yet finalized.

The topics are selected from a predefined open-source taxonomy.

The platform uses a classifier model to infer topics. The Topics API implementation and its usage of the classifier will be part of the Android Open Source Project, and will improve over time.

For illustrative purposes, the following code example demonstrates the usage of topics to fetch an interest-based ad. APIs used here are not final.

// Initialize the Topics API.
…
topicsFuture = AdvertisingTopicsClient.getTopics();

// Retrieve Topics and use them in Ad request.
Futures.addCallback(
    topicsFuture,
    new FutureCallback<AdvertisingTopicsInfo>() {
        @Override
        public void onSuccess(@Nullable AdvertisingTopicsInfo topicsInfo) {
            // Sanitize Topics result.
            ...
            // Initialize ad request with Topics obtained.
            AdRequest adRequest = AdRequest.initialize(topicsInfo);
        }

        @Override
        public void onFailure(Throwable t) {
            // Handle error.
            ...
        }
});

To get a better understanding of how the classifier model works, you can test how different app data reacts in the system using the Android Topics Classifier Colab.

Get access to Topics APIs

Adtech platforms need to enroll to access the Topics API, see Enroll for a Privacy Sandbox account for more information.

Details

  • Once each epoch (e.g. once a week), the user's top 5 topics are computed using on-device information.

    • When the Topics API is called, the platform will check if a topic is assigned to the app that invokes the API. If there aren't any assigned topics, one will be chosen as follows and the chosen topic will be assigned to this app for the rest of this epoch.
      • With 95% probability, a topic is randomly chosen from the list of the top 5 topics computed for that epoch.
      • With 5% probability, a topic is randomly chosen from the taxonomy.
      • A caller can specify that they would like to retrieve topics without modifying the state by calling getTopics using the parameter shouldRecordObservation = false. This means that topics can be returned, but the call won't be included in the weekly epoch calculation, nor will it update the list of topics observed for the caller.
    • The reason that each app gets one of several topics is to ensure that different apps get different topics, making it harder for apps to cross-correlate the same user.
      • For example, app A might see topic T1 for the user, but app B might see topic T2. This makes it more difficult for the two apps to determine that this information is associated with the same user.
  • The Topics API returns a list of up to 3 topics, 1 for each of the past 3 epochs.

    • By providing up to 3 topics, infrequently used apps will have enough topics to find relevant ads, but frequently used apps will learn at most 1 new topic per week.
    • The returned topic information includes a topic ID (int) corresponding to an entry in the taxonomy, a taxonomy version, and a classifier model version.
    • Only callers that observed the user use an app associated with the topic in question within the past 3 epochs can receive the topic.
    • All topics returned represent the interests of the user, and you can select any or all of these topics for ad personalization in your ad request.
  • After a topic is assigned to the app that invokes the Topics API, the platform will determine whether the caller can receive this topic.

    • Only callers that observed user engagement of an app associated with the topic in question within the past 3 epochs can receive the topic.
    • If the caller did not call the API in the past for that user on an app about that topic, then the topic will not be included in the list returned by the API.
    • If the caller did not receive any topics in the past 3 epochs, the Topics API will return an empty list.

    For example, say the user has 7 apps installed on the device: A, B, C, D, E, F and G. Let's assume that the topic classification for the app and the ad tech SDKs in these apps are as follows:

    App Topic classification 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
    • End of week 1: The Topics API generates the user's top 5 topics for this epoch.
    Top Topic Callers that can learn about the topic
    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
    • In week 2, if a caller on any app calls the API, then the returned topic list will only include topics for which the caller is in the "Callers that can learn about the topic" column for that topic for that app for that epoch.
    • The history window included in the calculation of topics available to each caller is 3 epochs (or 3 weeks).
    • Only topics associated with apps that invoke the Topics API, directly or through ad SDKs, are used. This means that if an app doesn't include any ad SDKs that call the Topics API and doesn't invoke the API itself, the topics associated with that app don't contribute to topics shared with other apps or ad SDKs.
    • An app can also declaratively opt out of the Topics API through new manifest and XML elements, in order to disallow ad SDKs from using the API for that app. Topics associated with opted-out apps will not contribute to the weekly topic computation. This document will be updated to include related implementation details.
  • If there's not enough app usage for the platform to infer 5 topics, the platform may consider options like randomly generating remaining topics.

Taxonomy

  • In the current proposal, the initial taxonomy will include somewhere between a few hundred and a few thousand topics. The initial taxonomy proposal will be shared in a future update of this document.
  • This taxonomy will be human-curated so that sensitive topics are not part of the taxonomy.
  • This taxonomy will be tailored to the categories of ads that can be shown on mobile apps on Android.
  • The taxonomy is open source, and subject to change. Suggestions can be filed using the feedback button at the top of this page.

Topic classifier

Topics of interest are derived from a classifier model that is trained on publicly available app information (like app name, description and package name).

  • When the classifier model is used for inference to compute the topics for a given epoch, the set of signals used remain on the device. This set of signals may include apps installed or recently used, and it may later be expanded to include other signals.
  • Initial models will be trained by Google, where the training data includes human-curated labels for publicly available app information. The model will be freely available for apps to test to see what topics their app classifies to.
  • Initial models will be trained on publicly available information of apps from a limited set of app stores like the Google Play Store.
  • It's possible that an app maps to more than 1 topic, to no topics, or that it doesn't add to the user's topic history. In the event that an app maps to more than 1 topic in the taxonomy, the number of topics chosen for this app will be limited to the top 3.

User controls

  • The design intends to provide users with the ability to view and remove the topics that are associated with their app usage. The implementation of this user control capability is a work in progress, and will be included in a future update.
  • If the user uninstalls an app that contributed to the selection of an inferred topic in the past 3 epochs, that topic will not be removed from the list of topics returned for the past 3 epochs, in order to avoid disclosing information about the uninstallation.

In order to facilitate testing for what the end user experience will be, you can also launch an in-app intent in order to view the settings UI for Topics similar to how an end user would see it. An example of that call can be seen below:

//Button that launches settings UI
private Button mSettingsAppButton;
private static final String RB_SETTING_APP_INTENT = "android.adservices.ui.SETTINGS";


//Does setup for button on screen that will launch settings UI to observe Topics
private void registerLauchSettingsAppButton() {
    mSettingsAppButton.setOnClickListener(
        new View.OnClickListener() {

            @Override
            public void onClick(View view) {
                Context context = getApplicationContext();
                Intent activity2Intent = new Intent(RB_SETTING_APP_INTENT);
                activity2Intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
                context.startActivity(activity2Intent);
            }
        });
}