Topics Integration Guide for SSPs

As part of Privacy Sandbox, Chrome proposed a Topics API. The Topics API provides third-party callers on the web page (including ad tech providers) with coarse-grained advertising topics that the page visitor might currently be interested in. These topics can supplement the contextual information about the current page. They can be useful to support interest-based advertising. Display & Video 360 and Google Ads receive these topics in bid requests and might use them alongside other signals for personalized advertising—without relying on third-party cookies. Before diving into the Topics API, first familiarize yourself with Testing in the Privacy Sandbox.

The following guide provides the steps necessary for SSPs to integrate with topics and to test these with Display & Video 360 and Google Ads or any other participating ad tech provider.

Enrollment

Starting in August 2023, SSPs will need to enroll themselves for the Topics API.

Topics Prebid Module

The Topics Prebid Module is used to call the Topics API (document.browsingTopics()) which fetches first-party domain as well as third-party domain (Iframe) topics data to be sent to user.data in a bid stream.

Topics Module (topicsFpdModule) should be included in the prebid final package in order to call the Topics API. Module topicsFpdModule helps to call the Topics API, which sends topics to the DSP (Display & Video 360 and Google Ads) to be used for personalized advertising.

try {
    if ('browsingTopics' in document && document.featurePolicy.allowsFeature('browsing-topics')) {
        topics = document.browsingTopics();
    }
} catch (e) {
    console.error('Could not call topics API', e);
}

Topics Iframe Configuration

Topics iframe implementation is the enhancement of the existing module under topicsFpdModule.js where different bidders will call the Topics API under their domain to fetch the topics for respective domain and the segment data will be part of OpenRTB request under the user.data object. Default config is maintained in the module itself.

Below are the configurations which can be used to configure and override the default config maintained in the module.

pbjs.setConfig({
    userSync: {
        ...,
        topics: {
            maxTopicCaller: 3, // SSP rotation
            bidders: [{
                bidder: 'pubmatic',
                iframeURL: 'https://ads.pubmatic.com/AdServer/js/topics/topics_frame.html',
                expiry: 7 // Configurable expiry days
            },{
                bidder: 'rubicon',
                iframeURL: 'https://rubicon.com:8080/topics/fpd/topic.html', // dummy URL
                expiry: 7 // Configurable expiry days
            },{
                bidder: 'appnexus',
                iframeURL: 'https://appnexus.com:8080/topics/fpd/topic.html', // dummy URL
                expiry: 7 // Configurable expiry days
            }]
        }
        ....
    }
})

Topics Config Descriptions

Topics configuration fields

topics.maxTopicCaller

integer, optional

Defines the maximum numbers of Bidders Iframe which needs to be loaded on the publisher page. Default is 1 which is hardcoded in Module.

For example, if topics.maxTopicCaller is set to 3 and there are 10 bidders configured along with their iframe URLS, 3 bidders will be randomly selected and their iframe URLs will be loaded, which will call TOPICS API. If topics.maxTopicCaller is set to 0, it will load 1 (default) random bidder iframe at the least.

topics.bidders

array of objects, optional

Array of topics callers with the iframe locations and other necessary information like bidder (Bidder code) and expiry. Default array of topics in the module itself.

topics.bidders[].bidder

string, optional

Bidder Code of the bidder(SSP).

topics.bidders[].iframeURL

string, required

The URL hosted on bidder/SSP/third-party domains which will call Topics API.

topics.bidders[].expiry

integer, required

Maximum number of days where Topics data will be persistent. If Data is stored for more than mentioned expiry day, it will be deleted from storage. Default is 21 days which is hardcoded in Module.

Publisher integration

To send DSP topics, SSPs need to work with their connected publishers. Interested publishers must compile Prebid.js with support for this module. This is accomplished by adding the topicsFpdModule module to the list of modules they are already using:

gulp build --modules=topicsFpdModule,...

OpenRTB protocol

A DSP expects topics to be in the user.data object in OpenRTBRequest. Learn how to pass segment IDs in vendor-specific taxonomies using JSON

Example

Chrome Topics API response, returned by document.browsingTopics():

[
  {
    "modelVersion": "classifier_v1",
    "taxonomyVersion": "taxonomy_v1",
    "topic": 3
  },
  {
    "modelVersion": "classifier_v1",
    "taxonomyVersion": "taxonomy_v1",
    "topic": 44
  },
  {
    "modelVersion": "classifier_v1",
    "taxonomyVersion": "taxonomy_v1",
    "topic": 59
  }
]

OpenRTBRequest JSON:

{
  ...
  "user": {
    "data": [
      {
        "ext": {
          "segtax": 600,
          "segclass": "classifier_v1"
        },
        "segment": [
          { "id": "3" },
          { "id": "44" },
          { "id": "59" }
        ]
      }
    ]
  }
}

In the preceding example, taxonomy_version implies that the taxonomy_v1 mapping is used. Based on the taxonomy, these topic IDs correspond to the following topics:

Topic ID Topic Value
3 /Arts & Entertainment/Comics
44 /Arts & Entertainment/Opera
59 /Autos & Vehicles/Classic Vehicles

Availability

For more information about the availability of topics, see the most up-to-date timeline for Privacy Sandbox Origin Trials.