Usar a API Topics com lances programáticos na API Protected Audience

Saiba como usar os interesses da API Topics como base para os lances e o processo de leilão da API Protected Audience. A API Protected Audience tem vários pontos em que o comprador e o vendedor podem transmitir indicadores próprios para o processo de lances e leilões. Os indicadores fornecidos pela API Topics podem ser usados para aprimorar os dados disponíveis durante o processo de lances e seleção de anúncios com informações sobre os interesses atuais dos usuários, aumentando o valor em potencial do inventário de anúncios.

Antes de ler este guia, conheça as APIs Topics e Protected Audience.

Receber temas

Ao chamar a API Topics, o autor da chamada verá uma seleção dos temas que observou anteriormente no navegador.

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

Neste caso, 310 é mapeado para "Esportes/ciclismo".

Esses exemplos mostram os valores de tópico sendo usados diretamente, mas uma implementação completa pode optar por processá-los ou combiná-los com outros dados.

Usar temas para definir condicionalmente um grupo de interesse

O tópico resultante pode ser usado diretamente para adicionar um usuário a um grupo de interesse.

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

Fornecer temas de compradores a um grupo de interesse

Os temas atuais (ou os dados processados deles) podem ser incluídos no userBiddingSignals ao criar o grupo de interesse. Isso permite que o comprador use temas ao dar lances.

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

navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);

Fornecer temas de vendedores para um leilão

Os temas atuais que aparecem para o vendedor ou os dados processados neles podem ser incluídos em uma combinação de auctionSignals, sellerSignals ou perBuyerSignals ao configurar o leilão. Isso permite que o comprador use temas ao definir lances e o vendedor use temas ao definir lances.

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

Usar tópicos ao dar lances

Quando a função generateBid() do comprador for chamada, os temas registrados transmitidos poderão ser usados (assim como qualquer outro dado fornecido nos indicadores) para ajudar nos lances. Por exemplo, o bidder pode usar a presença da coluna "Esportes/ciclismo" tópico para definir lances mais altos com este grupo de interesse custom-bikes.

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

Usar tópicos ao pontuar lances

Após dar lances quando a função scoreAd() do vendedor é chamada, os temas registrados podem ser usados como qualquer outro dado transmitido da configuração do leilão. Por exemplo, o vendedor pode querer aumentar o peso dos lances para anúncios que correspondem a tópicos detectados.

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
  //...
}