Topics API for Mobile overview

Provide feedback

About the Topics API

In mobile advertising, advertisers want to serve relevant ads that relate to a user's interest. The Topics API is designed to support third-party advertising SDKs that typically operate across multiple apps. This support comes in the form of surfacing some of the cross-app interests that those SDKs would normally observe. Individual app developers shouldn't expect to learn additional information about their users. Learn how Topics enables interest-based advertising.

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

Ad tech 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. Assume that the topic classification for the app and the ad tech SDKs in these apps are as follows:

    App Topic classification Ad tech 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 through ad SDKs are used. This means that if an app doesn't include any ad SDKs that call the Topics API, the topics associated with that app don't contribute to the pool of topics accessible by 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 publicly available, 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 registerLaunchSettingsAppButton() {
    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);
            }
        });
}

Enroll an ad tech platform

To access the Topics API, all ad tech platforms (including Google's) need to complete an enrollment process.

App developers can manage which ad tech developers can access the Topics APIs by including the ad tech developer's enrollment ID inside of the app manifest.

Encryption of returned topics

Enrolled ad tech platforms that call the Topics API are also required to provide encryption keys to ensure that the returned topics are readable only to the caller.

Privacy Sandbox will fetch these keys from the ad tech provided endpoint. We recommend, as best practice, that the keys must be updated often, but no later than every 6 months.

Privacy Sandbox will ask that ad techs confirm the availability of the endpoint provided by the ad tech during the enrollment process. For more details on action required by current and newly enrolled adtechs, see the Enrollment Developer Guide.

Encryption details

With the introduction of encryption, calls to 'GetTopics()' will now generate a response with a list of 'EncryptedTopic' objects. Decrypting these results will result in an object with the same JSON format of the previous Topic object.

Topics API supports one shot implementation of HPKE (Hybrid Public Key Encryption). We expect the enrolled caller to host a 32-bit public key on the public encryption URL endpoint provided during enrollment. These keys are expected to be Base64 encoded.

EncryptedTopic object's have 3 fields. The list of returned topics can be obtained by using the corresponding private key for the public key.

For development purposes, you can test the Topics API encryption by disabling the enrollment check. This would force the API to use the test public key for encrypting your responses. You can decrypt the encrypted topics using the corresponding private key.