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

Saiba como usar os interesses da API Topics como entrada no processo de lances e leilões 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 Topics podem ser usados para enriquecer os dados disponíveis durante o processo de licitação e seleção de anúncios com informações sobre os interesses atuais dos usuários, o que aumenta o valor potencial do inventário de anúncios.

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

Acessar temas

Ao chamar a API Topics, o autor da chamada verá uma seleção dos temas observados anteriormente para esse navegador.

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

Neste tópico: 310 é mapeado para "Esportes/Ciclismo".

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

Usar tópicos para definir um grupo de interesse condicionalmente

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 neles) 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 do vendedor para um leilão

Os temas atuais visíveis para o vendedor (ou os dados processados com base 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 dar lances e o vendedor use temas ao pontuar 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 definir lances

Assim, 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 do tópico "Esportes/ciclismo" para dar um lance mais alto com esse grupo de interesse de 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

Depois de 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, ele pode querer ponderar lances mais altos 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
  //...
}