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

Guia e referências da API do vendedor 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 conhecer todo o ciclo de vida da API Protected Audience e consulte a explicação da API para uma discussão detalhada sobre como os vendedores realizam leilões no dispositivo.

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

O que é um 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.

1. Um usuário acessa um site que mostra anúncios.
2. O código do vendedor executa navigator.runAdAuction(). Isso especifica qual espaço de anúncio está à venda e quem pode fazer 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 pontua cada lance e seleciona um vencedor. Essa lógica usa o valor do lance e outros dados para retornar a conveniência de um lance. Os anúncios que não conseguem superar 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 isolado. Nem o vendedor nem o editor poderão ver 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 de vários vendedores:

1. O usuário acessa 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 é 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?

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

Exemplo:

• Editor de conteúdo: age por conta própria para hospedar conteúdo de anúncio no site.
• Plataforma de fornecimento (SSP): trabalha com o publisher e oferece outros serviços.
• Script de terceiros: age 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 regras do publisher: quais compradores e lances são qualificados.
• Executar a lógica do leilão: JavaScript executado em worklets para calcular uma pontuação de conveniência para cada lance.
• Informe o resultado do leilão.

Esses trabalhos 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 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 resultado do leilão de anúncios. Isso só pode ser decodificado pelo navegador quando passado 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 o lance e os metadados associados, um de cada vez, e atribui a ele uma pontuação numérica de conveniência.

Propriedades de auctionConfig

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 o 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 fizeram lances no leilão.

Observações: o vendedor pode especificar interestGroupBuyers: para permitir que todos os grupos de interesse façam lances. Em seguida, os anúncios são aceitos ou rejeitados com base em critérios que não incluem o proprietário do grupo de interesse. Por exemplo, o vendedor pode analisar os criativos de anúncio para confirmar a conformidade com as políticas dele.

auctionSignals

Opcional

Exemplo: {...}

Função: informações do vendedor sobre o contexto da página, o 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

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 contextuais sobre a página para cada comprador específico, do servidor dele.

perBuyerTimeouts

Opcional

Exemplo: 50

Função: tempo de execução máximo (ms) de 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 conveniência 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 de um leilão começar, 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 superar o vencedor contextual.

scoreAd()

scoreAd() usa os seguintes argumentos:

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 conveniência 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 maior pontuação.

Todas as referências da API Protected Audience

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

• Guia do desenvolvedor da API Protected Audience.
• Guia do comprador de anúncios sobre grupos de interesse e geração de lances da API Protected Audience.
• Guia do vendedor de anúncios para leilões de anúncios da Protected Audience.
• Guia para gerar relatórios de resultados do leilão
• Práticas recomendadas para latência do leilão de anúncios da Protected Audience
• Resolver problemas da API Protected Audience

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