As part of Privacy Sandbox , Chrome proposed the experimental 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. The topics can supplement the contextual information about the current page, and can be useful to support interest-based advertising.
The Topics API experiment is available to RTB partners in bid requests. Topics are sent to all RTB partners based on availability .
Bid request representation
OpenRTB protocol
Topics are represented as segments in the OpenRTB BidRequest.user.data
message.
| Field | Type | Description |
|---|---|---|
Data.ext.segtax
|
Integer | The ID for a taxonomy that is registered centrally . For Topics, this is the version of the advertising taxonomy which defines the semantic meaning of each topic ID. 600 is used for Chrome's Topics initial taxonomy. |
Data.ext.segclass
|
String | Equivalent to classifier_version
. |
Data.segment.id
|
String | Equivalent to id
casted to a string. |
Data.ext
is an extension to the BidRequest.user.data
message. This extension
is available in the open beta version of the protocol
.
Here's the definition:
//
Ad
Exchange
extensions
for
the
Data
object
.
message
DataExt
{
//
The
ID
for
a
taxonomy
that
is
registered
centrally
.
Used
to
define
the
//
namespace
and
semantic
meaning
of
the
segment
IDs
.
See
//
https:
//gi
thub
.
com
/InteractiveAdvertisingBureau/o
penrtb
/blob/m
aster
/extensions/comm
unity_extensions
/
segtax
.
md
#enumeration-of-taxonomies
//
for
the
enumeration
of
the
taxonomies
that
this
value
can
take
.
Currently
//
only
Chrome
Topics
API
taxonomy
(
segtax
=
600
)
is
supported
.
optional
int32
segtax
=
1
;
//
The
version
of
the
classifier
which
produced
the
segment
IDs
within
the
//
taxonomy
.
For
example
,
in
the
case
of
Chrome
Topics
API
(
segtax
=
600
),
this
//
is
the
version
of
the
classifier
used
by
the
browser
to
map
hostnames
to
//
topics
in
the
taxonomy
.
optional
string
segclass
=
2
;
}
Google RTB protocol (deprecated)
Topics are represented in the topics
field in the BidRequest
message. This
field is available in the open beta version of the protocol
.
Here's the definition:
// Experimental field; subject to change.
// A coarse-grained topic that a website visitor might currently be interested
// in based on recent browsing activity. See
// https://developer.chrome.com/docs/privacy-sandbox/topics/ and/or
// https://privacysandbox.com/intl/en_us/proposals/topics/ for more
// information about the Topics API. Reach out to your account manager to
// participate in the Topics API experiment.
message
Topic
{
// The value of a topic ID. A numerical identifier corresponding to a
// coarse-grained advertising topic. See
// https://github.com/patcg-individual-drafts/topics/blob/main/taxonomy_v1.md
// for a list of topics in the initial taxonomy.
optional
int32
id
=
1
;
// The version of the advertising taxonomy which defines the semantic
// meaning of each topic ID for the topics, for example "v1".
optional
string
taxonomy_version
=
2
;
// The version of the classifier used by the browser to map hostnames to
// topic IDs in the taxonomy.
optional
string
classifier_version
=
3
;
}
// The list of topics that a website visitor might currently be interested in
// inferred by the browser based on recent browsing activity. See
// https://developer.chrome.com/docs/privacy-sandbox/topics/ and/or
// https://privacysandbox.com/intl/en_us/proposals/topics/ for more
// information about Topics API.
repeated
Topic
topics
=
74
;
Examples
The following is an example of how Google Authorized Buyers and OpenRTB protocols represent topics returned by the Chrome Topics API.
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
}
]
OpenRTB BidRequest
:
{
"user": {
"data": [
{
"ext": {
"segtax": 600,
"segclass": "classifier_v1"
},
"segment": [
{ "id": "3" },
{ "id": "44" },
{ "id": "59" }
]
}
]
}
}
Google RTB protocol (deprecated) BidRequest
:
topics {
id: 3
taxonomy_version: "taxonomy_v1"
classifier_version: "classifier_v1"
}
topics {
id: 44
taxonomy_version: "taxonomy_v1"
classifier_version: "classifier_v1"
}
topics {
id: 59
taxonomy_version: "taxonomy_v1"
classifier_version: "classifier_v1"
}
In the Chrome Topics API example above, 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
The presence of topics in the bid request is subject to the existing privacy protections and controls. For example, topics are unavailable if the user opts out of personalized advertising or on non-personalized ads inventory.
