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 | |
---|---|
|
Defines the maximum numbers of Bidders Iframe which needs to be loaded on
the publisher page. Default is For
example, if |
|
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. |
|
Bidder Code of the bidder(SSP). |
|
The URL hosted on bidder/SSP/third-party domains which will call Topics API. |
|
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.