Dar lances em um leilão para comprar um espaço de anúncio

Como comprador de anúncios (DSPs e anunciantes), você pode ter interesse em participar de um leilão de anúncios da Protected Audience no site do editor para segmentar um anúncio ao grupo de interesse definido no site do anunciante. Ao participar do leilão da Protected Audience, você pode alcançar os clientes identificados em outros sites preservando a privacidade.

Em um leilão da Protected Audience, você fornece a lógica para gerar o lance, e o navegador calcula o lance usando essa lógica. Isso é diferente de outras arquiteturas de leilão em que você envia o lance diretamente, em vez de fornecer a lógica.

Você fornece sua lógica de geração de lances na função JavaScript generateBid(), e o arquivo é hospedado no seu servidor. Quando você adiciona um usuário a um grupo de interesse, a localização desse arquivo é transmitida para a configuração do grupo como um biddingLogicUrl.

Durante o leilão, o navegador busca sua lógica de lances especificada no campo biddingLogicUrl e executa a função generateBid() para cada grupo de interesse em um ambiente isolado e seguro que é limitado na comunicação com o contexto externo. Quando generateBid() é executado, o navegador transmite sinais para a função como argumentos. Esses indicadores contêm informações de diferentes fontes, como dados próprios do editor, do vendedor, em tempo real e muito mais. É possível usar esses indicadores para calcular o lance, e o valor é retornado pela chamada generateBid(). Depois que os lances são enviados, o navegador executa a lógica de pontuação do vendedor em cada lance para calcular a pontuação de desejabilidade do vendedor.

Observação :com a aplicação de k-anonimato, o generateBid será chamado uma segunda vez se o lance da primeira chamada não for k-anônimo. Quando chamada pela segunda vez, a lista de anúncios no argumento interestGroup vai incluir apenas anúncios k-anônimos.

generateBid()

Veja a seguir a descrição dos argumentos da função generateBid() e a estrutura do lance retornado da função:

generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals, directFromSellerSignals) {
  return {
    ad: adObject,
    adCost: optionalAdCost,
    bid: bidValue,
    bidCurrency: 'USD',
    render: {
      url: renderURL,
      width: renderWidth,
      height: renderHeight
    },
    adComponents: [
      {url: adComponent1, width: componentWidth1, height: componentHeight1},
      {url: adComponent2, width: componentWidth2, height: componentHeight2},
      // ...
    ],
    allowComponentAuction: false,
    modelingSignals: 123 // 0-4095 integer (12-bits)
  };
}

Argumentos

generateBid() usa os seguintes argumentos:

Argumento	Papel
interestGroup	Um objeto transmitido pelo comprador de anúncios. O grupo de interesse pode ser atualizado com dailyUpdateUrl.
auctionSignals	Uma propriedade do argumento configuração do leilão transmitida para navigator.runAdAuction() pelo vendedor. Ela fornece informações sobre o contexto da página (como o tamanho do anúncio e o ID do editor), o tipo de leilão (primeiro preço ou segundo preço) e outros metadados.
perBuyerSignals	Uma propriedade do argumento configuração do leilão transmitido pelo vendedor. Isso pode fornecer indicadores de contexto do servidor do comprador sobre a página se o vendedor for uma SSP que realiza uma chamada de lances em tempo real para os servidores do comprador e encaminhar a resposta ou se a página do editor entrar em contato diretamente com o servidor do comprador. Nesse caso, o comprador pode verificar uma assinatura criptográfica desses indicadores em generateBid() como proteção contra adulteração.
trustedBiddingSignals	Um objeto cujas chaves são as trustedBiddingSignalsKeys do grupo de interesse e cujos valores são retornados na solicitação trustedBiddingSignals.
browserSignals	Um objeto criado pelo navegador, que pode incluir informações sobre o contexto da página (como o hostname da página atual, que o vendedor poderia falsificar) e dados do próprio grupo de interesse (como um registro de quando o grupo venceu um leilão anteriormente, para permitir o limite de frequência no dispositivo).
directFromSellerSignals	Indicadores que têm a garantia de serem provenientes de um vendedor específico, ao contrário de auctionSignals e sellerSignals, que podem vir de qualquer participante que esteja presente no contexto de onde runAdAuction é executado.

Indicadores do navegador

O objeto browserSignals tem as seguintes propriedades:

{
  topWindowHostname: 'publisher.example',
  seller: 'https://ssp.example',
  topLevelSeller: 'https://www.top-level-ssp.com',
  requestedSize: {width: 100, height: 200},  /* if specified in auction config */
  joinCount: 3,
  recency: 3600000,
  bidCount: 17,
  prevWinsMs: [[timeDeltaMs1,ad1],[timeDeltaMs2,ad2],...],
  wasmHelper: ...
  dataVersion: 1,
  adComponentsLimit: 40
}

Propriedade	Descrição
topWindowHostname	O nome do host em que a chamada runAdAuction() foi feita.
seller	Vendedor para quem o lance foi enviado. Em um leilão de componentes, esse valor é o vendedor do componente.
topLevelSeller	O vendedor de nível superior em um leilão de componentes e só está presente em um leilão de componente.
requestedSize	A propriedade requestedSize recomenda um tamanho de frame para o leilão. O vendedor define o tamanho solicitado na configuração do leilão, e o valor é disponibilizado aos bidders na generateBid(). Os bidders que participam do leilão podem escolher um tamanho de conteúdo diferente para o anúncio, e esse tamanho resultante é dimensionado visualmente para se ajustar ao tamanho do contêiner do elemento.
joinCount	O campo joinCount é o número de vezes que o dispositivo entrou nesse grupo de interesse nos últimos 30 dias enquanto o grupo estava armazenado continuamente, ou seja, não há lacunas no armazenamento do grupo de interesse no dispositivo devido ao cancelamento ou à expiração da associação.
recency	O campo recency é o período (em minutos) entre o momento em que o dispositivo entrou no grupo de interesse até agora
bidCount	O número de vezes que o grupo de interesse enviou um lance.
prevWinsMs	O campo prevWinMs contém os anúncios vencedores do grupo de interesse e o tempo desde as vitórias anteriores em milissegundos. O objeto de anúncio aqui contém apenas os campos renderURL e metadados.
wasmHelper	Um objeto WebAssembly.Module com base no biddingWasmHelperURL do grupo de interesse.
dataVersion	Valor de versão de dados nas respostas de serviço de chave-valor do comprador.
adComponentsLimit	Número máximo de componentes de anúncio que generateBid() pode retornar

Calcular um lance

Para calcular um valor de lance, o código em generateBid() pode usar as propriedades dos parâmetros da função.

Exemplo:

function generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  return {
   //  ...
    bid: auctionSignals.is_above_the_fold ? perBuyerSignals.atf_value : perBuyerSignals.btf_value,
    // ...
  }
}

Retornar um lance

generateBid() retorna um objeto com as seguintes propriedades:

Propriedade	Papel
ad	Metadados arbitrários sobre o anúncio, como informações que o vendedor espera saber sobre esse lance ou criativo do anúncio. O vendedor usa essas informações na lógica de leilão e decisão.
adCost	Um valor numérico usado para transmitir o custo do clique ou da conversão do anunciante do relatório de generateBid para reportWin. A precisão desse número é limitada a uma mantissa de 8 bits e um expoente de 8 bits, com qualquer arredondamento realizado estocasticamente.
adComponents	Uma lista opcional de até 20 componentes para anúncios compostos por várias partes, recebida da propriedade adComponents do argumento do grupo de interesse transmitido para navigator.joinAdInterestGroup().
allowComponentAuction	É um valor booleano que indica se esse lance pode ser usado em um leilão de componentes. Se nada for especificado, o padrão será "false".
bid	É um lance numérico que vai entrar no leilão. Como o vendedor precisa estar em posição de comparar lances de diferentes compradores, os lances precisam estar em uma unidade escolhida pelo vendedor (como"USD por mil"). Se o lance for zero ou negativo, esse grupo de interesse não participará do leilão do vendedor. Com esse mecanismo, o comprador pode implementar regras de anunciantes para determinar onde os anúncios podem ou não ser exibidos.
bidCurrency	A moeda do lance, usada para verificação de moeda.
render	Um dicionário que descreve o criativo que deverá ser renderizado se esse lance vencer o leilão. Isso inclui: url: o URL do criativo. width: a largura do criativo. Esse tamanho será comparado à declaração no grupo de interesse e substituído por qualquer macro de tamanho presente no URL do anúncio. Quando o anúncio é carregado em um frame isolado, o frame interno do frame isolado (ou seja, o tamanho visível para o criativo do anúncio) vai ser congelado até esse tamanho, e ele não vai conseguir ver as mudanças no tamanho do frame feitas pelo incorporador. height: a altura do criativo. Confira mais detalhes em width.
modelingSignals	Um número inteiro de 0 a 4095 (12 bits) transmitido para reportWin(), com ruído, conforme descrito no esquema de ruído e agrupamento por classes. Valores inválidos, como valores negativos, infinitos e NaN, serão ignorados e não transmitidos. Somente os 12 bits mais baixos serão transmitidos. O comprador pode usar os indicadores disponíveis na função generateBid(), incluindo dados de compradores próprios coletados no momento da criação do grupo de interesse em userBiddingSignals, para derivar algum valor que é transmitido à função de relatório de ganhos do comprador para ativar o treinamento do modelo de ML.