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.

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:

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:

• 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.