Fazer um leilão baseado em navegador com um único vendedor

Neste documento, você vai encontrar uma visão geral de alto nível para realizar um leilão com dados da API Protected Audience para um único vendedor, conforme usado na iteração atual da API Protected Audience. Um leilão com um único vendedor pode ser executado como parte de um leilão mais complexo envolvendo vários vendedores. Nesse caso, o leilão de um único vendedor é chamado de "leilão de componente", que pode fornecer candidatos a anúncios para o "leilão de nível superior" com vários vendedores participantes.

Leia o guia para desenvolvedores para conhecer o ciclo de vida completo da API Protected Audience e consulte a explicação da API Protected Audience para uma discussão detalhada sobre como os vendedores realizam leilões no dispositivo.

Seis estágios de um leilão de anúncios da API Protected Audience

1. Um usuário acessa um site que mostra anúncios.
2. O código do vendedor executa navigator.runAdAuction(). Isso especifica qual espaço de anúncio está à venda e quem pode fazer lances. Os vendedores também precisam incluir um script que pontua cada lance, scoreAd().
3. O código do comprador convidado é executado para gerar um lance, um URL para um criativo de anúncio relevante e outros dados. O script de lances pode consultar dados em tempo real, como o orçamento restante da campanha publicitária, do serviço de chave/valor do comprador.
4. O código do vendedor pontua cada lance e seleciona um vencedor. Essa lógica usa o valor do lance e outros dados para retornar a conveniência de um lance. Os anúncios que não conseguem superar o vencedor contextual são rejeitados. O vendedor pode usar o próprio serviço de chave-valor para dados em tempo real.
5. O anúncio vencedor é retornado como um valor opaco, que aparece em um frame isolado. Nem o vendedor nem o editor poderão ver esse valor.
6. O leilão é informado ao vendedor e aos compradores vencedores.

Um leilão pode ocorrer quando um usuário navega até uma página que mostra um anúncio. Os leilões podem ser realizados com antecedência para que o criativo do anúncio esteja pronto quando o slot de anúncio aparecer.

Os vendedores iniciam o leilão de anúncios, pontuam os anúncios candidatos usando a lógica personalizada fornecida como uma função scoreAd() e são responsáveis por informar os resultados do leilão para si mesmos e para o comprador vencedor. Os vendedores também podem aplicar as regras do publisher e filtrar a qualidade do anúncio usando a função scoreAd().

Um vendedor pode se referir a:

• Publishers de conteúdo, agindo por conta própria para hospedar conteúdo de anúncios no site
• Plataformas de fornecimento (SSPs), que trabalham com o publisher de anúncios e oferecem outros serviços
• Scripts de terceiros que atuam em nome de editores para permitir a participação em leilões de anúncios.

Pré-requisitos para fazer um leilão

Um vendedor precisa de duas funções JavaScript definidas para realizar um leilão:

• scoreAd(), que pontua um candidato a anúncio
• reportResult(), que lida com a geração de relatórios do resultado do leilão para o próprio vendedor

Esses scripts precisam ser veiculados de um único endpoint de propriedade do vendedor.

scoreAd()

Um vendedor precisa definir uma função scoreAd() veiculada de um endpoint de propriedade dele. O endpoint é especificado na configuração do leilão como o decisionLogicUrl. A função scoreAd() tem a seguinte assinatura:

scoreAd(
  adMetadata,
  bid,
  auctionConfig,
  trustedScoringSignals,
  browserSignals,
  directFromSellerSignals)

Os parâmetros scoreAd() são:

• adMetaData, que são metadados arbitrários sobre o criativo do anúncio fornecidos pelo comprador. É um objeto serializável em JSON que vendedores e compradores precisam definir e concordar com a estrutura.
• bid, que é um valor numérico que representa o lance.
• auctionConfig, que é a configuração usada para executar o leilão.
• trustedScoringSignals, que são indicadores lidos no momento do leilão no servidor de chave/valor do vendedor. A plataforma vai usar o renderUrl do anúncio candidato como chave para essa pesquisa.
• browserSignals, que é um objeto construído pelo navegador, incluindo informações que o navegador conhece e que o script de leilão do vendedor pode querer verificar.
• directFromSellerSignals é um objeto que pode conter os seguintes campos: ** sellerSignals: semelhante a auctionConfig.sellerSignals, mas transmitido usando o mecanismo directFromSellerSignals. ** auctionSignals: semelhante a auctionConfig.auctionSignals, mas transmitido usando o mecanismo directFromSellerSignals.

Confira um exemplo de browserSignals. O renderUrl do anúncio candidato está disponível por estes indicadores:

{ 'topWindowHostname': 'www.example-publisher.com',
  'interestGroupOwner': 'https://www.example-buyer.com',
  'renderURL': 'https://cdn.com/render_url_of_bid',
  'renderSize': {width: 100, height: 200}, /* if specified in the bid */
  'adComponents': ['https://cdn.com/ad_component_of_bid',
                   'https://cdn.com/next_ad_component_of_bid',
                   ...],
  'biddingDurationMsec': 12,
  'bidCurrency': 'USD', /* bidCurrency returned by generateBid, or '???' if none */
  'dataVersion': 1, /* Data-Version value from the trusted scoring signals server's response */
}

reportResult()

Um vendedor precisa definir uma função reportResult() veiculada de um endpoint de propriedade dele. O endpoint é especificado na configuração do leilão como decisionLogicUrl. A função reportResult() tem a seguinte assinatura:

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

Os parâmetros reportResult() são:

• auctionConfig, que é a configuração usada para executar o leilão.
• browserSignals, que é um objeto construído pelo navegador, incluindo informações que o navegador conhece e que o script de leilão do vendedor pode querer verificar. É o mesmo objeto transmitido para a função scoreAds().

reportResult() retorna signalsForWinner, que é um objeto JSON arbitrário transmitido para a função de geração de relatórios do comprador vencedor. Isso deve incluir qualquer informação relevante que o vendedor possa fornecer sobre o leilão e que o comprador precisa para os relatórios.

Fazer um leilão da API Protected Audience

Há quatro etapas principais que um vendedor precisa seguir para realizar um leilão. Estas etapas pressupõem que o vendedor tem um endpoint configurado para retornar o JavaScript necessário, mencionado anteriormente neste guia.

1. Configure o leilão. Esta etapa inclui a criação de um objeto auctionConfig. Isso permite que o vendedor especifique quais compradores devem participar do leilão e forneça indicadores relevantes durante a geração de lances ou a pontuação de anúncios.
2. Execute o leilão chamando navigator.runAdAuction() e transmitindo a configuração criada na etapa anterior. Isso inicia a cadeia de compradores que geram lances e pontuações. O resultado final dessa etapa é um candidato a anúncio que pode ser renderizado para exibir um anúncio.
3. Renderize o anúncio vencedor em um frame isolado ou iframe.
4. Informar o resultado do leilão. Há uma função, navigator.sendReportTo(), que inicia a geração de relatórios. O vendedor sempre vai receber um relatório com os resultados do leilão. Somente o comprador que venceu o leilão vai receber um relatório. Isso usa o reportResult() do vendedor descrito anteriormente neste guia para informar ao servidor dele.