Use Topics with programmatic bidding in Protected Audience

Learn how to use interests from Topics as an input to the Protected Audience bidding and auction process. Protected Audience has several points where the buyer and seller may pass first-party signals into the bidding and auction process. The signals provided by Topics can be used to enrich the data available during the bidding and ad selection process with information about current user interests increasing the potential value of ad inventory.

Before reading this guide, ensure you're familiar with both Topics and Protected Audience.

Get topics

When calling the Topics API, the caller will see a selection of the topics they have previously observed for that browser.

const currentTopics = await document.browsingTopics();
// Example result
[
  {
    "configVersion": "chrome.2",
    "modelVersion": "4",
    "taxonomyVersion": "2",
    "topic": 310,
    "version": "chrome.2:2:4"
  }
]

In this case topic: 310 maps to "Sports/Cycling".

These examples show the topic values being used directly, but a full implementation may choose to process or combine them with other data.

Use topics to conditionally define an interest group

The resulting topic may be used directly to choose to add a user to an interest group.

if (currentTopics[0].topic === 310) { // Interest in "Sports/Cycling"
  const interestGroup = {
  owner: 'https://dsp.example',
  name: 'custom-bikes',
  }
}

Provide buyer topics to an interest group

The current topics (or data processed out of them) can be included in the userBiddingSignals when creating the interest group. This allows the buyer to use topics when making bids.

const interestGroup = {
  owner: 'https://dsp.example',
  name: 'custom-bikes',
  userBiddingSignals: {
    topics: currentTopics,
    ....
  },
  ...
};

navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);

Provide seller topics to an auction

The current topics visible to the seller (or data processed out of them) may be included in a combination of the auctionSignals, sellerSignals, or perBuyerSignals when configuring the auction. This allows both the buyer to use topics when making bids and the seller to use topics when scoring bids.

const myAuctionConfig = {
  seller: 'https://ssp.example',
  auctionSignals: {
    topics: currentTopics,
  },
  sellerSignals: {
    topics: currentTopics,
  },
  perBuyerSignals: {
    'https://dsp.example': {
      topics: currentTopics,
      // ...
    },
    // ...
  },
  // ...
};
const result = await navigator.runAdAuction(myAuctionConfig);

Use topics when making bids

Then when the buyer's generateBid() function is called, the recorded topics passed in can be used (just like any other data provided in the signals) to aid in bidding. For example, the bidder might use the presence of the "Sports/Cycling" topic to bid higher with this custom-bikes interest group.

generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  const topics = interestGroup.userBiddingSignals.topics;
  // Use the topic values in the bidding logic.
}

Use topics when scoring bids

After bidding when the seller's scoreAd() function is called, the recorded topics can be used like any other data passed in from the auction configuration. For example, the seller may want to weight bids higher for ads that match against detected topics.

scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals, directFromSellerSignals) {
  const sellerTopics = actionConfig.auctionSignals.topics;
  // or corresponding key in sellerSignals
  // use the topics values to score the ads
  //...
}