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 experimental Protected Audience.

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 conferir uma discussão mais detalhada 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 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 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.

Quando ocorre o leilão?

A API Protected Audience pode ser executada por conta própria 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 espaço 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 conseguem superar o vencedor contextual são rejeitados.

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

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

Exemplo:

  • Editor de conteúdo: agir por conta própria para hospedar conteúdo de anúncios no site.
  • Plataforma de fornecimento (SSP, na sigla em inglês): trabalhar com o editor e fornecer 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 funções:

  • Aplicar regras do editor: quais compradores e lances são qualificados.
  • Execute 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.

Esses jobs são feitos de forma programática no 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 chama navigator.runAdAuction() para fazer uma solicitação ao navegador do usuário para iniciar um leilão de anúncios.

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 resultado do leilão de anúncios. Ele 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, bem como 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'
Papel: origem do vendedor.
decisionLogicUrl
Obrigatório
Exemplo: 'https://ssp.example/auction-decision-logic.js'
Papel: URL para JavaScript de worklet de leilão.
trustedScoringSignalsUrl
Opcional
Exemplo: 'https://ssp.example/scoring-signals'
Papel: 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 pediram lances no leilão.
Observação: 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 critérios diferentes da inclusão do proprietário do grupo de interesse. Por exemplo, o vendedor pode revisar os criativos de anúncios para confirmar a conformidade com as políticas.
auctionSignals
Opcional
Exemplo: {...}
Papel: informações do vendedor sobre o contexto da página, tipo de leilão etc.
sellerSignals
Opcional
Exemplo: {...}
Papel: informações com base nas configurações do editor, fazendo uma solicitação de anúncio contextual etc.
sellerTimeout
Opcional
Exemplo: 100
Papel: ambiente de execução máximo (ms) do script scoreAd() do vendedor.
perBuyerSignals
Opcional
Exemplo: 
{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ... }
Papel: indicadores de contexto sobre a página para cada comprador específico, do servidor.
perBuyerTimeouts
Opcional
Exemplo: 50
Papel: ambiente de execução máximo (ms) dos scripts generateBid() do 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 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 criado 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 disponível. Parte da lógica scoreAd() rejeita qualquer anúncio que não possa vencer 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 do servidor confiável do vendedor no momento do leilão, representando a opinião do vendedor sobre o anúncio.

Perguntas frequentes

Como o vencedor do leilão será escolhido e quem os escolherá?

O vendedor fornece a lógica de pontuação para determinar a pontuação de 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 que tem comunicação limitada com o código fora dele. O navegador não pontua os anúncios. O navegador é o único 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.