Configurar um leilão de anúncios na página do editor

Saiba como configurar um leilão da API Protected Audience.

Leilões no dispositivo realizados por vendedores

Um leilão da Protected Audience no dispositivo é realizado em um site que vende espaços publicitários, e nos referimos à parte que realiza o leilão como o vendedor. Muitas partes podem atuar como vendedores: um site pode gerar o próprio leilão de anúncios, incluir um script de terceiros para fazer o leilão ou usar uma SSP que combina a execução de um leilão no dispositivo com outras atividades de leilão de anúncios do lado do servidor. Os vendedores têm três tarefas básicas no leilão de anúncios no dispositivo:

1. Os vendedores decidem (a) de quais compradores podem participar e (b) quais dos lances dos grupos de interesse desses compradores estão qualificados para entrar no leilão. Isso permite que o vendedor aplique as regras do site sobre quais anúncios podem aparecer na página.
2. Os vendedores são responsáveis pela lógica de negócios do leilão: o código JavaScript, que considera o preço e os metadados de cada lance e calcula uma pontuação de desejabilidade. O lance com a maior pontuação de desejabilidade vence o leilão.
3. Os vendedores geram relatórios sobre o resultado do leilão, incluindo informações sobre liberação do preço e outros pagamentos. Os compradores vencedores e perdedores também podem fazer seus próprios relatórios.

Este documento explica como configurar e iniciar um leilão no dispositivo.

Configurar um leilão de anúncios da API Protected Audience

Para realizar um leilão de anúncios da API Protected Audience, a primeira etapa é configurar o leilão. Para isso, crie um objeto auctionConfig. Confira um exemplo dessa configuração:

const auctionConfig = {
  seller: 'https://seller.example',
  decisionLogicUrl: ...,
  trustedScoringSignalsUrl: ...,
  interestGroupBuyers: ['https://buyer-1.example', 'https://buyer-2.example', ...],
  auctionSignals: {...},
  sellerSignals: {...},
  sellerTimeout: 100,
  perBuyerSignals: {
    'https://buyer-1.example': {...},
    'https://buyer-2.example': {...},
    ...
  },
  perBuyerTimeouts: {
    'https://buyer-1.example': 50,
    'https://buyer-2.example': 200,
    '*': 150,
    ...
  },
  componentAuctions: [
    {
      'seller': 'https://component-seller.example',
      'decisionLogicUrl': ...,
      ...
    },
    ...
  ],
  resolveToConfig: [true|false],
};

AuctionConfig propriedades

Observação: additionalBids não tem suporte na implementação atual da API Protected Audience. Para mais informações, leia a seção Participantes do leilão na explicação da API Protected Audience.

Propriedades obrigatórias

As únicas propriedades obrigatórias para auctionConfigs são seller, decisionLogicUrl e interestGroupBuyers.

Propriedade	Exemplo	Papel
seller	https://seller.example	Origem do vendedor.
decisionLogicUrl	https://seller.example/decision-logic.js	URL do worklet de lógica de decisão JavaScript do leilão. Esse campo precisa ter a mesma origem que o campo do vendedor.
interestGroupBuyers	[https://buyer-1.example, https://buyer-2.example, ...]	Origens de todos os proprietários de grupos de interesse que pediram lances no leilão

Propriedades opcionais

As outras propriedades de auctionConfigs são opcionais.

Propriedade	Exemplo	Papel
trustedScoringSignalsUrl	https://seller.example/scoring-signals	URL do servidor de chave-valor do vendedor. Isso será consultado durante o processo de pontuação do anúncio usando o URL de renderização do criativo como a chave. Esse campo precisa ter a mesma origem que o campo do vendedor.
auctionSignals	{"category":"notícias"}	Objeto serializável JSON que representa os indicadores disponíveis para todos os compradores e vendedores participantes do leilão.
sellerSignals	{...}	Objeto serializável JSON que representa indicadores disponíveis apenas para os vendedores.
perBuyerSignals	{https://dsp.example: {...}, https://another-buyer.example: {...}, ... }	Indicadores disponíveis para um comprador específico. Os indicadores podem vir dos vendedores e também dos próprios compradores.
perBuyerTimeouts	{https://www.example-dsp.com: 50, https://www.another-buyer.com: 200, *: 150, ...},	Tempo de execução máximo, em milissegundos, do script generateBid() de um comprador específico. Um símbolo curinga será aplicado a cada comprador que não tiver um tempo limite específico definido.
sellerTimeout	100	Tempo de execução máximo em milissegundos do script scoreAd() de um vendedor.
componentAuctions	[{seller: https://www.some-other-ssp.com, decisionLogicUrl: ..., ...}, ...]	Configurações adicionais para leilões de componentes.
resolveToConfig	verdadeiro|falso	Um booleano que direciona a promessa retornada de runAdAuction() para resolver um FencedFrameConfig se verdadeiro (para uso em um <fencedframe>) ou para um URL urn:uuid opaco se for falso (para uso em um <iframe>). O padrão é falso.

Fornecer indicadores de forma assíncrona

Os valores de alguns indicadores (configurados pelos campos auctionSignals, sellerSignals, perBuyerSignals e perBuyerTimeouts) podem ser fornecidos não como valores concretos, mas como promessas. Isso permite que algumas partes do leilão, como o carregamento de scripts e indicadores confiáveis e o lançamento de processos isolados de worklet, sobreponham o cálculo (ou a recuperação de rede) desses valores. Os scripts de worklet só terão acesso aos valores resolvidos. Se alguma promessa for rejeitada, o leilão será cancelado, a menos que já consiga falhar ou seja cancelado de outras maneiras.

Configurar um leilão com vários vendedores

Em alguns casos, vários vendedores podem querer participar de um leilão, em que os vencedores de leilões separados são transmitidos para outro leilão realizado por outro vendedor. Esses leilões separados são chamados de leilões de componentes. Para facilitar esses leilões de componentes, o objeto componentAuctions pode conter outras configurações de leilão para o leilão de componentes de cada vendedor. O lance vencedor de cada um desses leilões de componentes será passado para o leilão de "nível superior", que é responsável pela determinação final do leilão. O auctionConfig dos leilões de componentes pode não ter o próprio componentAuctions. Quando componentAuctions não está vazio, interestGroupBuyers precisa estar vazio. Ou seja, para qualquer leilão específico da Protected Audience, haverá um único vendedor e nenhum leilão de componentes. Caso contrário, todos os lances vêm de leilões de componentes, e o leilão de nível superior só pode escolher entre os vencedores dos leilões de componentes.

Fazer o leilão

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

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

A chamada runAdAuction() retorna uma promessa que é resolvida com o anúncio. Não é possível que um código na página do editor inspecione o anúncio vencedor ou saiba mais sobre o conteúdo dele com o resultado de runAdAuction(). Se a sinalização resolveToConfig tiver sido definida como verdadeira em AuctionConfig, um objeto FencedFrameConfig será retornado, e ele só poderá ser renderizado em um frame delimitado. Se a flag tiver sido definida como falsa, um URN opaco vai ser retornado, que pode ser renderizado em um iframe. É possível que runAdAuction retorne um valor nulo, indicando que nenhum anúncio foi selecionado. Nesse caso, o vendedor pode optar por renderizar um anúncio segmentado por contexto.