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

Como um comprador de anúncios (DSPs e anunciantes), talvez você tenha interesse em participar de um leilão de anúncios com 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ê alcança os clientes identificados em outros sites sem comprometer a privacidade.

Em um leilão com 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 fica 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 de interesse 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 seguro, limitado na comunicação com contexto externo. Quando generateBid() é executado, o navegador transmite os indicadores para a função como argumentos. Esses indicadores contêm várias informações de diferentes fontes, como dados próprios do editor, do vendedor, em tempo real e muito mais. Você pode usar esses indicadores para calcular o lance, e o valor é retornado da 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 atratividade 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. Na 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 da estrutura do lance retornado por ela:

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 passado pelo comprador do anúncio. O grupo de interesse pode ser atualizado com dailyUpdateUrl.
auctionSignals	Uma propriedade do argumento auction config 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 ou segundo preço) e outros metadados.
perBuyerSignals	Uma propriedade do argumento auction config transmitida pelo vendedor. Isso pode fornecer indicadores de contexto do servidor do comprador sobre a página se o vendedor for uma SSP que executa uma chamada de lances em tempo real para os servidores do comprador e redirecionar 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 no generateBid() para proteção contra adulterações.
trustedBiddingSignals	Um objeto com chaves que são a trustedBiddingSignalsKeys do grupo de interesse e com valores que 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 com certeza vêm de um vendedor específico, ao contrário de auctionSignals e sellerSignals, que podem vir de qualquer participante no contexto em que 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	O vendedor para quem o lance é 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 componente 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 para os bidders em generateBid(). Os bidders do leilão podem escolher um tamanho de conteúdo diferente para o anúncio, e esse tamanho vai ser dimensionado visualmente para caber no tamanho do contêiner do elemento.
joinCount	O campo joinCount é o número de vezes que este dispositivo entrou nesse grupo de interesse nos últimos 30 dias enquanto o grupo foi armazenado continuamente, ou seja, não há lacunas no armazenamento do grupo de interesse no dispositivo devido à saída ou ao vencimento da assinatura.
recency	O campo recency é a duração (em minutos) entre o momento em que esse dispositivo entrou neste 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, em milissegundos, desde as vitórias anteriores do grupo. O objeto de anúncio contém apenas os campos renderURL e de metadados.
wasmHelper	um objeto WebAssembly.Module com base no biddingWasmHelperURL do grupo de interesse.
dataVersion	Valor da versão de dados das respostas do 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 no 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 ter acesso a esse lance ou criativo. O vendedor usa essas informações na lógica do leilão e da decisão.
adCost	Um valor numérico usado para transmitir os relatórios de custo de cliques ou conversões do anunciante 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, extraída da propriedade adComponents do argumento do grupo de interesse transmitido para navigator.joinAdInterestGroup().
allowComponentAuction	Um valor booleano que indica se o lance pode ser usado em um leilão de componentes. O padrão é "false" caso não seja especificado.
bid	Um lance numérico que entrará no leilão. O vendedor precisa conseguir comparar lances de compradores diferentes. Portanto, os lances precisam estar em alguma 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 qualquer regra de anunciante que defina onde seus anúncios podem ou não ser exibidos.
bidCurrency	A moeda do lance usada para currency-checking.
render	Um dicionário que descreve o criativo que precisa ser renderizado se o lance vencer o leilão. Isso inclui: url: o URL do criativo. width: a largura do criativo. Esse tamanho será comparado com a declaração no grupo de interesse e substituído em todas as macros de tamanho do anúncio presentes no URL do criativo 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) fica congelado nesse tamanho e não mostra as mudanças feitas pelo incorporador. height: a altura do criativo. Confira mais detalhes em width.
modelingSignals	Um número inteiro de 0 a 4.095 (12 bits) transmitido para reportWin(), com ruído, conforme descrito no esquema de agrupamento e ruído. Valores inválidos, como negativos, infinitos e NaN, serão ignorados e não serão transmitidos. Somente os 12 bits mais baixos serão passados. O comprador pode usar os indicadores disponíveis na função generateBid(), incluindo dados de compradores próprios capturados no momento da criação do grupo de interesse no userBiddingSignals, para derivar algum valor que é transmitido à função de relatório de vitórias do comprador e ativar o treinamento do modelo de ML.