Test, deploy and scale a Topics-based solution

This page covers how to build, test, and scale an implementation for production using the Topics API.

Topics backend implementation

Your backend implementation depends on how you want to use the topics calculated in the browser. We recommend that ad tech solutions use Topics as an additional IBA signal.

// Use the language/framework/stack of your preference
function processTopicsBackendAPI(topics) {
 // If the list is not empty, continue
 // Use topics as an additional signal
}

Use Topics as an additional signal

Topics data can be considered alongside other signals such as URLs, keywords, or other metadata, as an additional signal about your audience.

As explained in Maximize ad relevance after third-party cookies, there are multiple approaches to leveraging Topics to serve relevant ads. Some of these involve using Topics to build audiences, and other approaches suggest using Topics as one signal among others to train machine learning models that will be used to infer additional interests of the audience or even to optimize bidding logic.

Build and deploy

  1. Collect topics by observing users in production (estimated implementation time: approximately one week):
    • Understand your options: how to call Topics with HTTP headers or iframe and JavaScript.
    • Define the domain of the iframe that will call the Topics API.
    • Build your solution, using header demo or JavaScript demo as a code reference.
    • Integrate Topics into your code that publishers embed on their sites (for example, your ad iframe). Make sure you call topics from the embed.
    • To start observing user topics, embed the latest version of your script on your production websites. We recommend that you test the implementation on your own websites that have a small number of monthly visits first. At this stage, we recommend embedding your new topics-based solution on at least five sites.
    • At this point, it is expected that the API returns an empty array as a result. This is because no topics have been observed for the user yet. It can take up to three weeks to begin getting user topics.
    • Perform functional testing and validation. You can test your solution manually or automatically. For example:
      • Open your browser with flags and set the epoch to 15 seconds, so that the browser recalculates Topics sooner.
      • Visit the sites that embed your script.
      • Check whether topics are observed by your script on chrome://topics-internals/.
      • See which results you can expect.
  2. Use Topics data together with other contextual signals (such as URLs, metadata etc.) (estimated time: around 3 days).
    • After three weeks in production, your script should have observed some users' topics. At this point, you should be able to use Topics data as an additional signal.
    • Once you start receiving a non-empty list of topics, you can send it to your backend with other contextual signals.

Deploy to target sites

Once you've integrated a Topics call into your script, make sure it's embedded on some production sites for a first test. Make sure your implementation works as expected:

  • Topics API is called.
  • Topics can be observed in this controlled environment.
  • Topics can be accessed (the API returns observed topics for the user).

Choose target sites

Before deploying your solution to publishers' sites, we recommend testing it in a controlled environment, on the websites that you own. We recommend that you pick target websites as follows:

  • The site gets a small number of monthly visits (less than about one million visits/month): You should begin by deploying the API to a small audience first.
  • You own and control the site: If necessary you can quickly disable the implementation without complex approvals.
  • The site is not business critical: Start with low risk target sites.
  • Total no more than five sites: You won't need that much traffic or exposure for now.
  • The target sites represent different themes: Choose websites that represent different categories (for example, one about sports, another about news, one more from food and drink). You can use the internal topics tool in Chrome to validate domains and how they are classified by the Topics machine-learning classifier.

Functional testing and validation

When calling the Topics API in this limited environment, you can expect the following results:

  • An empty array of topics [], if this is the first call of this device, for this site and caller in the last seven days.

  • A list of zero to three topics, representing the interests of this user. After seven days of observation you should receive:

    • One topic, selected from the top five for the user, calculated from hostnames of pages where topics have been observed by the caller during that week.

  • The exact same API response as in all the previous Topics API calls. For the same caller, user, and top-level site, the API will return the same topics for the whole of an epoch. This helps to avoid exposing too many of the user's interests. Find more details on GitHub.

  • A new topic replacing one of the three old ones if you are calling Topics after four weeks of observation.

  • If you have not observed topics for the user for the previous three weeks, or longer, then the Topics API will return an empty array [] again.

Gather performance metrics to assess your user experience:

  • The run time of the JavaScript calls to the Topics API inside a cross-origin iframe should be measured to be used in future performance analysis.
  • The time taken to create an iframe and postMessage() topics, after topics are received.

For troubleshooting, refer to the support section.

Scale to production

At this point you should have tested Topics in a controlled environment (on some sites you own). If everything works as expected, it's time to scale this implementation. Deploy the same code to more target websites. This will enable you to observe more users, collect more topics data, and deepen your understanding of your audiences.

Here's a step-by-step summary of how you can scale to production:

  1. Test your topics-based solution on a higher volume of traffic.
    • Add your iframe to more sites you own with a larger number of visits and follow the instructions below to perform load testing.
  2. Deploy your solution to publishers' sites.
    • Once your solution is working correctly in your own testing environment, collaborate with publishers to integrate your iframe into their websites. For example, they may need to update the library that includes your iframe.
  3. Process and use topics data (estimated time: around four weeks).
    • Incorporate topics data as an additive signal alongside other data.
    • Source real-time-bidding testing partners.
    • Run utility testing with topics as an additive signal to your other data.

Load testing

To ensure your system can handle the traffic, we recommend performing load testing before deploying your topics-based solution to publishers' sites.

  1. Deploy gradually across more target sites that you own, especially those that have a larger volume of traffic.
  2. Perform load testing for your topics data, according to your expected traffic.
    • You will need to send topic information from the iframe to your backend. This lets you further process the Topics API results and use them as an additional signal to help select ads that are more relevant to the user. As more sites incorporate your embed, the number of calls to your backend will increase significantly. Confirm that your backend can handle a large volume of calls from the iframe.
    • Set up metric collection and logs for analysis.
  3. Immediately after deploying the Topics API, check your metrics to detect any severe end-user issues. Keep checking your metrics regularly.
  4. In case of disruption or unexpected behavior, roll back the deployment and analyze your logs to understand and fix the issue.

See also

Check out our resources to better understand the Topics API on the Web.