Guia do vendedor: realize leilões de anúncios

Guia da API do vendedor e referências para o leilão de anúncios da API Protected Audience.

Neste artigo, você vai encontrar uma referência técnica para o leilão de anúncios, conforme usado na iteração atual da API Protected Audience experimental.

Leia o guia para desenvolvedores sobre 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.

Não é desenvolvedor? Consulte a Visão geral da API Protected Audience.

O que é o leilão de anúncios da API Protected Audience?

Um leilão de anúncios da API Protected Audience é uma coleção de pequenos programas JavaScript que o navegador executa no dispositivo do usuário para escolher um anúncio. Para preservar a privacidade, todo o código do leilão de anúncios do vendedor e dos compradores é executado em worklets JavaScript isolados que não podem se comunicar com o mundo externo.

Seis etapas 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 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.

Quando o leilão acontece?

A API Protected Audience pode ser executada sozinha ou com leilões programáticos. Em um leilão programático com vários vendedores:

  1. O usuário visita um site participante.
  2. Um leilão programático é realizado por outro vendedor para encontrar um anúncio contextual para um slot de anúncio disponível.
  3. O leilão da API Protected Audience é executado.
  4. scoreAd()compara os lances do comprador com os resultados do primeiro leilão.

Os lances que não podem superar o vencedor contextual são rejeitados.

Quem realiza o leilão de anúncios da API Protected Audience?

Várias partes podem realizar um leilão para vender espaço publicitário.

Exemplo:

  • Editor de conteúdo: atua por conta própria para hospedar conteúdo de anúncios no site.
  • Plataforma de fornecimento (SSP): trabalha com o editor e oferece outros serviços.
  • Script de terceiros: atua em nome de um editor para permitir a participação em leilões de anúncios.

Com a API Protected Audience, um vendedor tem três tarefas:

  • Aplicar as regras do editor: quais compradores e lances são qualificados.
  • Executar a lógica do leilão: o JavaScript é executado em worklets para calcular uma pontuação de desejabilidade para cada lance.
  • Informe o resultado do leilão.

Essas tarefas são feitas programaticamente, em um código fornecido pelo vendedor quando ele inicia um leilão de anúncios chamando a função JavaScript navigator.runAdAuction().

Funções da API

runAdAuction()

O vendedor faz uma solicitação ao navegador do usuário para iniciar um leilão de anúncios chamando navigator.runAdAuction().

Exemplo:

const auctionConfig = {
  seller: 'https://ssp.example',
  decisionLogicUrl: ...,
  trustedScoringSignalsUrl: ...,
  interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
  auctionSignals: {...},
  sellerSignals: {...},
  sellerTimeout: 100,
  perBuyerSignals: {
    'https://dsp.example': {...},
    'https://another-buyer.example': {...},
    ...
  },
  perBuyerTimeouts: {
    'https://dsp.example': 50,
    'https://another-buyer.example': 200,
    '*': 150,
    ...
  },
  componentAuctions: [
    {
      'seller': 'https://some-other-ssp.example',
      'decisionLogicUrl': ...,
      ...
    },
    ...
  ]
};

try {
  const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
  // Handle error.
}

runAdAuction() retorna uma promessa que é resolvida para um URN (urn:uuid:<something>) que representa o resultado do leilão de anúncios. Isso só pode ser decodificado pelo navegador quando transmitido para um frame fechado para renderização: a página do editor não pode inspecionar o anúncio vencedor.

O script decisionLogicUrl considera cada anúncio individual, junto com o lance e os metadados associados, um por vez, e atribui uma pontuação de desejabilidade numérica.

auctionConfig propriedades

seller
Obrigatório
Exemplo: 'https://ssp.example'
Função: origem do vendedor.
decisionLogicUrl
Obrigatório
Exemplo: 'https://ssp.example/auction-decision-logic.js'
Função: URL para JavaScript do worklet de leilão.
trustedScoringSignalsUrl
Opcional
Exemplo: 'https://ssp.example/scoring-signals'
Função: URL do servidor confiável do vendedor.
interestGroupBuyers
Obrigatório
Exemplo: ['https://dsp.example', 'https://buyer2.example', ...]
Função: origens de todos os proprietários de grupos de interesse que foram solicitados a dar lances no leilão.
Observações: o vendedor pode especificar interestGroupBuyers: para permitir que todos os grupos de interesse deem lances. Os anúncios são aceitos ou rejeitados com base em outros critérios, além da inclusão do proprietário do grupo de interesse. Por exemplo, o vendedor pode analisar os criativos do anúncio para confirmar a conformidade com as políticas.
auctionSignals
Opcional
Exemplo: {...}
Função: informações do vendedor sobre o contexto da página, tipo de leilão etc.
sellerSignals
Opcional
Exemplo: {...}
Função: informações com base nas configurações da empresa jornalística, solicitação de anúncio contextual etc.
sellerTimeout
Opcional
Exemplo: 100
Função: tempo de execução máximo (ms) do script scoreAd() do vendedor.
perBuyerSignals
Opcional
Exemplo: 
{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ... }
Função: indicadores de contexto sobre a página para cada comprador específico, do servidor.
perBuyerTimeouts
Opcional
Exemplo: 50
Função: tempo de execução máximo (ms) dos scripts generateBid() de um comprador específico.
componentAuctions
Opcional
Exemplo: 
[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...]
Função: configurações adicionais para leilões de componentes.

decisionLogicUrl

O decisionLogicUrl é uma propriedade do objeto de configuração do leilão, transmitida para runAdAuction(). Esse URL precisa incluir um script para a função scoreAd(). Essa lógica é executada uma vez para cada anúncio para determinar a atratividade dele.

scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
  ...
  return desirabilityScoreForThisAd;
}

browserSignals

browserSignals é 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:

{
  topWindowHostname: 'publisher.example',
  interestGroupOwner: 'https://dsp.example',
  renderUrl: 'https://cdn.example/render',
  adComponents: ['https://cdn.com/ad-component-1', ...],
  biddingDurationMsec: 12,
  dataVersion: 1 /* DValue from the seller's Key/Value service response. */
}

Antes do início de um leilão, o vendedor encontra o melhor anúncio contextual para o espaço de anúncio disponível. Parte da lógica scoreAd() rejeita qualquer anúncio que não vença o vencedor contextual.

scoreAd()

scoreAd() usa os seguintes argumentos:

Argumento Papel
adMetadata Metadados arbitrários fornecidos pelo comprador.
auctionConfig O objeto de configuração do leilão foi transmitido para navigator.runAdAuction().
bid Um valor de lance numérico.
trustedScoringSignals Valores recuperados no leilão do servidor confiável do vendedor, representando a opinião do vendedor sobre o anúncio.

Perguntas frequentes

Como o vencedor do leilão é decidido e quem o escolhe?

O vendedor fornece a lógica de pontuação para determinar a pontuação de atratividade de cada anúncio, e o navegador seleciona o anúncio vencedor com a pontuação mais alta.

O vendedor inclui a lógica na função scoreAd(), e o navegador executa a função em um worklet com comunicação limitada com o código fora dele. O navegador não pontua os anúncios. O navegador é exclusivamente responsável por executar a lógica de pontuação e selecionar o lance com a maior pontuação.

Todas as referências da API Protected Audience

Os guias de referência da API estão disponíveis:

A explicação da API Protected Audience também fornece detalhes sobre o suporte e as restrições de recursos.