Support resources for Topics API on the Web

Find recommendations for debugging, troubleshooting, and support resources for Topics on the Web.

Troubleshooting

If you make a document.browsingTopics() call or afetch() request with the header Sec-Browsing-Topics set, but receive an empty array as a response, there are a number of debugging steps you can take to identify the root cause of the issue, both in your local development environment and in the live system.

Debug locally

If you test locally, ensure you're running Chrome with the required parameters.

  • To bypass enrollment, enable the flag chrome://flags/#privacy-sandbox-enrollment-overrides and add the URL of the site that calls Topics.

  • Configure the Topics API for testing using the feature flags. These flags let you modify such parameters as epoch duration, number of top topics and others, so that you can comfortably test Topics. You can use this recommended feature flags:

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

  • Before running Chrome with flags, make sure you've closed all other Chrome instances and processes.

  • Make sure that:

    • You're using Chrome 101 or later.
    • Your script has called the Topics API to observe topics. When testing, you can simulate user behavior by visiting the sites where your script is embedded. Refer to the demo for a practical example.
    • You don't have an adblocker or a similar app or extension running.
    • You're not in Incognito mode.
    • From chrome://settings/trackingProtection, the Block all third-party cookies option is disabled.

Debug live implementation

If you are calling the Topics API from a live application within the first week of observing a user, then empty result is expected, as your application may have not yet observed topics for a user. You can debug your solution following our recommendations.

  • Make sure your site is enrolled with Privacy Sandbox.
  • Test your frontend code to make sure your JavaScript is working as expected.
  • Test your backend to receive the topics results.
    • Remember to make sure data types and backend API parameters are configured correctly.
    • Make sure your backend is configured to scale appropriately.
  • From our experience, it is necessary to allow at least three weeks before starting to get more relevant topics results.
  • Not all users will have Topics enabled:
    • Users can explicitly disable the Topics API.
    • Publisher's pages can control permissions policy and opt-out their sites.
  • Add metrics and observability to this environment: you'll need them to analyze the first results. Example metrics include:
    • Latency of calls.
    • HTTP errors on topics calls.
  • Try to limit changes to your implementation during the initial three weeks.

Resources