Topics API setup

Get your environment ready to use, test, and develop web applications with the Topics API.

Build and test locally

This section describes how to set up your local environment to try out the Topics API as an individual developer. We recommend to explore the demos to understand how Topics works before diving into the implementation.

Enable Topics in your browser

To enable the Topics API in your own Chrome instance for local testing you have two options:

  1. Enable all the Ad privacy APIs under chrome://settings/adPrivacy.
  2. (Recommended) Run Chrome from the command line with Chromium flags using Topics API-specific parameters to configure as needed. You have more fine-grained control over Topics features by running Chrome from the command line. For example, it's possible to set Topics epochs (the timeframe used by the API to calculate user interests) and configure the behavior of the API according to your needs.

Key recommendations

  1. Make sure you close and stop all Chrome processes before starting the new one using the flags.
  2. Make sure that all the Ad privacy APIs are enabled under chrome://settings/adPrivacy.
  3. If the API doesn't work as expected, try our troubleshooting tips.
  4. If you have questions, check the GitHub issues for the explainer.

Control Topics API with Chrome flags

Chrome flags can modify the behavior of the Topics API. Run Chrome from the command line with the parameters specified to facilitate testing. For example, the headers demo recommends using the following flags:

--enable-features=BrowsingTopics,BrowsingTopicsParameters:time_period_per_epoch/15s/max_epoch_introduction_delay/3s,PrivacySandboxAdsAPIsOverride,PrivacySandboxSettings3,OverridePrivacySandboxSettingsLocalTesting

The following table explains each parameter, its default value, and its purpose.

Flag name Default value Description
BrowsingTopics enabled Whether the Topics API is enabled.
PrivacySandboxAdsAPIsOverride enabled Enables ads APIs: Attribution Reporting, Protected Audience, Topics, Fenced Frames.
PrivacySandboxSettings4 disabled Enables the fourth release of the Privacy Sandbox UI settings.
OverridePrivacySandboxSettingsLocalTesting enabled If enabled, the browser no longer requires the underlying settings to be enabled for enabling the Privacy Sandbox features.
BrowsingTopicsBypassIPIsPubliclyRoutableCheck disabled If enabled, the check for whether the IP address is publicly routable will be bypassed when determining the eligibility for a page to be included in topics calculation.
BrowsingTopics:number_of_epochs_to_expose 3 The number of epochs from where to calculate the topics to give to a requesting context. The browser will internally keep up to N+1 epochs.
BrowsingTopics:time_period_per_epoch 7d-0h-0m-0s Duration of each epoch. For debugging, it can be useful to set this to (say) 15 seconds, rather than the default seven days.
BrowsingTopics:number_of_top_topics_per_epoch 5 Number of topics calculated per epoch.
BrowsingTopics:use_random_topic_probability_percent 5 Probability that an individual topic within an epoch is one returned at random from the entire taxonomy of topics. The randomness is sticky to an epoch and site.
BrowsingTopics:number_of_epochs_of_observation_data_to_use_for_filtering 3 How many epochs of API usage data (i.e. topics observations) will be used for filtering the topics for a calling context.
BrowsingTopics:max_number_of_api_usage_context_domains_to_keep_per_topic 1000 The maximum number of observed-by context domains to keep for each top topic. The intent is to cap in-use memory.
BrowsingTopics:max_number_of_api_usage_context_entries_to_load_per_epoch 100000 The maximum number of entries allowed to be retrieved from the database for each query for the API usage contexts. The query will occur once per epoch at topics calculation time. The intent is to cap peak memory usage.
BrowsingTopics:max_number_of_api_usage_context_domains_to_store_per_page_load 30 The maximum number of API usage context domains allowed to be stored per page load.
BrowsingTopics:config_version 1 Encodes the Topics API configuration parameters. Each version number should only be mapped to one configuration set. Updating the configuration parameters without updating the config_version should usually be fine for local testing, but in some situations could leave the browser in an inconsistent state and could result in a browser crash, for example updating the number_of_top_topics_per_epoch.
BrowsingTopics:taxonomy_version 1 The taxonomy version used by the API.

Before you begin to implement

Before you begin your implementation, we recommend you to review these resources to familiarize yourself with the Topics API.

  1. Review developer docs:
    1. Understand the purpose of Topics API and its role in interest-based advertising
    2. Understand how Topics works on the Web.
    3. Try the demos and watch the Topics demos, colab and tools walkthrough video.
    4. Fork the demos and run them from your own site.
    5. Read the API explainer to understand more of the details.
  2. Understand the API's role in supporting ad relevance if the future, where third-party cookies won't be available for an increasing proportion of users.
  3. To be notified of status changes in the API, join the mailing list for developers and stay tuned for the latest Topics updates.
  4. Contribute to the conversation on GitHub issues or W3C calls.
  5. If you encounter unfamiliar terms, review the Privacy Sandbox glossary.
  6. For more information on Chrome concepts, such as Chrome flags, review the short videos and articles available at goo.gle/cc.

Next steps

Check out implementation details and code samples for callers to observe and access topics.
Learn how to deploy, test and scale Topics based solutions.