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

bookmark_border Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Neste documento, você encontra uma visão geral de alto nível sobre como 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 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 participando.

Leia o guia para desenvolvedores para conferir 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 executam leilões no dispositivo.

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

1. Um usuário acessa um site que exibe anúncios.
2. O código do vendedor executa navigator.runAdAuction(). Isso 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, 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 avalia cada lance e seleciona um vencedor. Essa lógica usa o valor do lance e outros dados que retornam a atratividade de um lance. Os anúncios que não podem vencer 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 fechado. Nem o vendedor nem o editor poderão acessar esse valor.
6. O leilão é informado ao vendedor e aos compradores vencedores.

Um leilão pode acontecer quando um usuário acessa 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 uma lógica personalizada fornecida como uma função scoreAd() e são responsáveis por informar os resultados do leilão a si mesmos e ao comprador vencedor. Os vendedores também podem aplicar as regras do editor e filtrar a qualidade do anúncio usando a função scoreAd().

Um vendedor pode se referir a:

• Editores de conteúdo, que atuam por conta própria para hospedar conteúdo de anúncios no site
• Plataformas de fornecimento (SSPs), que trabalham com o editor de anúncios e fornecem outros serviços
• Scripts de terceiros, que agem 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 definir duas funções JavaScript para realizar um leilão:

• scoreAd(), que pontua um candidato de anúncio
• reportResult(), que processa o relatório do resultado do leilão para o vendedor

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

scoreAd()

O vendedor precisa definir uma função scoreAd() que seja veiculada em um endpoint próprio. 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 do anúncio fornecido pelo comprador. Esse é um objeto serializável 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 sinais lidos no leilão do 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 abaixo um exemplo de browserSignals. O renderUrl do anúncio candidato está disponível com 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()

O vendedor precisa definir uma função reportResult() que seja veiculada em um endpoint que ele possui. 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. Esse é o mesmo objeto transmitido para a função scoreAds().

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

Executar 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 devem participar do leilão, além de fornecer indicadores que podem ser relevantes durante a geração de lances ou a pontuação do anúncio.
2. Execute o leilão chamando navigator.runAdAuction() e transmitindo a configuração criada na etapa anterior. Isso inicia a cadeia de compradores gerando lances e depois pontuação. O resultado final desta etapa é um candidato a anúncio que pode ser renderizado para exibir um anúncio.
3. Renderizar o anúncio vencedor em um frame ou iframe.
4. Informe 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 dos 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.