Fazer um leilão no 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 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 que envolve vários vendedores. Nesse caso, o leilão de vendedor único é chamado de "leilão de componentes", que pode fornecer candidatos a anúncios para o "leilão de nível superior" que tem vários vendedores participando.

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

Seis fases de um leilão de anúncios da API Protected Audience

Seis fases em um leilão de anúncios da API Protected Audience
Este diagrama descreve cada etapa de um leilão de anúncios da API Protected Audience.
  1. Um usuário visita um site que exibe anúncios.
  2. O código do vendedor executa navigator.runAdAuction(). Ela especifica qual espaço publicitário está à venda e quem pode dar 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, o URL de 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, no serviço de chave-valor do comprador.
  4. O código do vendedor pontua cada lance e seleciona o vencedor. Essa lógica usa o valor do lance, e outros dados retornam a atratividade de um lance. Os anúncios que não puderem vencer o vencedor contextual serã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 é exibido em um frame isolado. O vendedor e o editor não podem conferir 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 exibe um anúncio. Os leilões podem ser realizados com antecedência para que o criativo do anúncio esteja pronto quando o espaço do anúncio for exibido.

Os vendedores iniciam o leilão de anúncios, classificam 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 a eles mesmos e ao comprador vencedor. Os vendedores também podem aplicar regras do editor e filtrar a qualidade do anúncio usando a função scoreAd().

Um vendedor pode consultar:

  • Editores de conteúdo, agindo por conta própria para hospedar conteúdo de anúncios em seu site
  • Plataformas de fornecimento (SSPs), que trabalham com o editor de anúncios e prestam outros serviços
  • Scripts de terceiros, atuando para que um editor permita a participação em leilões de anúncios.

Pré-requisitos para realizar 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 gerencia os relatórios do resultado do leilão para o próprio vendedor.

Esses scripts precisam ser veiculados em um endpoint do vendedor.

scoreAd()

Um vendedor precisa definir uma função scoreAd() que é disponibilizada a partir de um endpoint de sua propriedade. O endpoint é especificado na configuração do leilão como 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 de anúncio fornecido pelo comprador. Esse é um objeto serializável JSON que vendedores e compradores precisarão definir e concordar sobre a estrutura.
  • bid, que é um valor numérico que representa o lance.
  • auctionConfig, que é a configuração usada para realizar 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 a chave para essa pesquisa.
  • browserSignals, que é um objeto criado 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.

Veja a seguir 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() que é disponibilizada a partir de um endpoint que pertence a ele. 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 realizar o leilão.
  • browserSignals, que é um objeto criado pelo navegador, incluindo informações que o navegador conhece e que o script de leilão do vendedor pode querer verificar. Esse é o mesmo objeto transmitido para a função scoreAds().

reportResult() retorna signalsForWinner, que é um objeto JSON arbitrário que é transmitido à função de relatório do comprador vencedor. Isso precisa incluir todas as informações relevantes que o vendedor pode fornecer sobre o leilão que ele exige para a geração de relatórios.

Fazer um leilão da API Protected Audience

Há quatro etapas principais que um vendedor precisa seguir para realizar um leilão. Essas etapas pressupõem que o vendedor tenha 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 vão participar do leilão, além de fornecer indicadores que possam ser relevantes durante a geração de lances ou a pontuação do anúncio.
  2. Execute o leilão chamando navigator.runAdAuction(), transmitindo a configuração criada na etapa anterior. Isso inicia a cadeia de compradores que geram lances e, em seguida, pontuam. O resultado final dessa etapa é um candidato a anúncio que pode ser renderizado para mostrar um anúncio.
  3. Renderize o anúncio vencedor em um frame isolado ou iframe.
  4. Informe o resultado do leilão. Há uma função, navigator.sendReportTo(), que iniciará a geração de relatórios. O vendedor sempre vai receber um relatório dos resultados do leilão. Somente o comprador que ganhar o leilão vai receber um relatório. Ela usa o reportResult() do vendedor, descrito anteriormente neste guia, para informar ao servidor.