Fazer um leilão no navegador com um único vendedor

Neste documento, você encontra uma visão geral de alto nível para realizar um leilão com Dados da API Protected Audience de um único vendedor, conforme usado na iteração atual do pela API Protected Audience. Um leilão com um único vendedor pode ser como parte de um leilão mais complexo envolvendo vários vendedores. Neste nesse caso, o leilão de vendedor único é chamado de "leilão de componentes", podem oferecer candidatos a anúncios no "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 discussão sobre como os vendedores realizam leilões no dispositivo.

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

Seis etapas de 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(). Isso especifica quais o espaço publicitário está à venda e quem pode dar lances. Os vendedores também precisam incluir um roteiro que pontua cada lance, scoreAd().
  3. O código do comprador convidado é executado para gerar um lance e o URL de um anúncio relevante criativos e outros dados. O script de lances consulta dados em tempo real, como o orçamento restante da campanha publicitária com base no valor Serviço de chave-valor.
  4. O código do vendedor pontua cada lance e seleciona um vencedor. Essa lógica usa o valor de lance e outros dados mostram a atratividade de um lance. Anúncios que não podem vencer o vencedor contextual são rejeitados. O vendedor pode usar as próprias Serviço de chave-valor para dados em tempo real.
  5. O anúncio vencedor é retornado como um valor opaco, exibido em um frame isolado. Tanto o vendedor quanto o editor não terá acesso a 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 executados com antecedência para que o criativo do anúncio esteja pronto quando o anúncio aparecer.

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

Um vendedor pode consultar:

  • Editores de conteúdo, que atuam por conta própria para hospedar conteúdo de anúncios no próprio site.
  • Plataformas de fornecimento (SSPs), que trabalham com o editor de anúncios e fornecem outros serviços
  • Scripts de terceiros, atuando para um editor permitir 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 processa a geração de relatórios do resultado do leilão para o próprio vendedor.

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

scoreAd()

Um vendedor precisa definir uma função scoreAd() que é veiculada por um endpoint. que possuem. 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 que é fornecidas pelo comprador. Esse é um objeto serializável JSON que os vendedores e os compradores precisarão definir e concordar com a estrutura.
  • bid, que é um valor numérico que representa o lance.
  • auctionConfig, que é a configuração de leilão usada para realizar o leilão.
  • trustedScoringSignals, que são indicadores lidos no momento do leilão do do 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 construído pelo navegador, incluindo: informações que o navegador conhece e que o script de leilão do vendedor que queremos 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 directFromSellerSignals.

Veja a seguir um exemplo de browserSignals. Observe que o renderUrl do anúncio candidato é disponibilizado por estes sinais:

{ '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 é veiculada por um endpoint que eles possuem. O endpoint é especificado na configuração do leilão. como decisionLogicUrl. A função reportResult() tem o seguinte assinatura:

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

Os parâmetros reportResult() são:

  • auctionConfig, que é a configuração de leilão usada para realizar 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 que queremos verificar. Esse é o mesmo objeto transmitido para a função scoreAds().

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

Fazer um leilão da API Protected Audience

Existem quatro etapas principais que um vendedor precisa seguir para realizar um leilão. Observe que esses as etapas pressupõem que o vendedor tem um endpoint configurado para retornar o JavaScript necessário mencionados 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 do leilão, além de fornecer indicadores que podem ser relevantes durante o lance ou na pontuação de anúncios.
  2. Execute o leilão chamando navigator.runAdAuction(), transmitindo o a configuração criada na etapa anterior. Isso inicia a cadeia de compradores geração de lances e pontuação. O resultado final dessa etapa é um candidato que podem ser renderizados para exibir um anúncio.
  3. Renderize o anúncio vencedor em um frame isolado ou iframe.
  4. Informar o resultado do leilão. Existe uma função, navigator.sendReportTo(), que vai iniciar a geração de relatórios. O vendedor sempre receber um relatório dos resultados do leilão. Somente o comprador que venceu o leilão receberá um relatório. Ele usa o reportResult() do vendedor descrito anteriormente. neste guia para informar ao servidor.