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 para a vida completa da API Protected Audience e confira a explicação sobre ela para conferir mais detalhes sobre como os vendedores realizam leilões no dispositivo.

Não é um 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 é um conjunto de pequenos programas JavaScript que o é executado no dispositivo do usuário para escolher um anúncio. Para preservar a privacidade, todas as código de leilão do vendedor e dos compradores é executado em JavaScript isolado worklets que não podem se comunicar com o ao mundo exterior.

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.

Quando ocorre o leilão?

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

  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 espaço de anúncio disponível.
  3. O leilão da API Protected Audience é realizado.
  4. scoreAd()compara os lances do comprador com os resultados do primeiro leilão.

Os lances que não puderem superar o vencedor contextual serão rejeitados.

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

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

Exemplo:

  • Editor de conteúdo: agindo por conta própria para hospedar o conteúdo do anúncio no próprio site.
  • Plataforma de fornecimento (SSP): trabalhar com o editor e oferecer outros serviços.
  • Script de terceiros: atuar para um editor, permitir a participação em leilões de anúncios.

Com a API Protected Audience, um vendedor tem três funções:

  • Aplicar regras do editor: quais compradores e lances estão qualificados.
  • Executar lógica de leilão: JavaScript executado em worklets para calcular uma o índice de atratividade para cada lance.
  • Informar o resultado do leilão.

Esses trabalhos são realizados de forma programática, no código fornecido pelo vendedor ao 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 em um URN (urn:uuid:<something>) que representa o do leilão de anúncios. Só pode ser decodificado pelo navegador quando transmitido para um frame isolado. 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 os e os metadados associados, um de cada vez, e atribui a ele um valor de atratividade.

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'
Papel: URL para JavaScript da 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 solicitaram 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 então aceitos ou rejeitados com base em critérios diferentes da inclusão do proprietário do grupo de interesse. Por exemplo, o vendedor pode revisar criativos de anúncios para confirmar a conformidade com as políticas.
auctionSignals
Opcional
Exemplo: {...}
Função: informações do vendedor sobre contexto da página, tipo de leilão etc.
sellerSignals
Opcional
Exemplo: {...}
Função: informações com base nas configurações do editor, fazendo uma solicitação de anúncio contextual etc.
sellerTimeout
Opcional
Exemplo: 100
Papel: 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 de cada comprador específico, do servidor.
perBuyerTimeouts
Opcional
Exemplo: 50
Papel: 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': ..., ...}, ...]
Papel: configurações adicionais para leilões de componentes.

decisionLogicUrl

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

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

browserSignals

browserSignals é um objeto construído pelo navegador, incluindo informações. que o navegador conhece e qual 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 os anúncios que não podem venceram 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 transmitido para navigator.runAdAuction().
bid Um valor de lance numérico.
trustedScoringSignals Valores recuperados no momento do leilão do servidor confiável do vendedor, representando a opinião do vendedor sobre o anúncio.

Perguntas frequentes

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

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

O vendedor inclui lógica na função scoreAd(), e o navegador executa a função em um worklet com comunicação limitada com código externo. O próprio 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 pontuação mais alta.

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.