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 de 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 realizar o próprio leilão de anúncios ou incluir um script de terceiros para fazer isso, ou ainda 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 trabalhos básicos no leilão de anúncios no dispositivo:

  1. Os vendedores decidem (a) 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: 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 conveniência vence o leilão.
  3. Os vendedores geram relatórios sobre o resultado do leilão, incluindo informações sobre o preço de compensação e outros pagamentos. Os compradores vencedores e perdedores também podem gerar os 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. Isso é feito criando um objeto auctionConfig. Confira um exemplo de 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],
};

Propriedades de AuctionConfig

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 do campo "seller".
interestGroupBuyers [https://buyer-1.example,
https://buyer-2.example,
...]		 Origens de todos os proprietários de grupos de interesse que receberam um pedido de lance 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 chave. Esse campo precisa ter a mesma origem do campo "seller".
auctionSignals {"category":"news"} Objeto serializável em JSON que representa os indicadores disponíveis para todos os compradores e vendedores participantes do leilão.
sellerSignals {...} Objeto serializável em 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 dos próprios compradores.
perBuyerTimeouts {https://www.example-dsp.com: 50,
https://www.another-buyer.com: 200,
*: 150,
...},		 Tempo máximo de execução em milissegundos de um script generateBid() de um comprador específico. Um símbolo de caractere curinga será aplicado a todos os compradores que não tiverem um tempo limite específico definido.
sellerTimeout 100 Tempo máximo de execução em milissegundos de um script scoreAd() de um vendedor.
componentAuctions [{seller: https://www.some-other-ssp.com, decisionLogicUrl: ..., ...}, ...] Configurações adicionais para leilões de componentes.
resolveToConfig true|false Um booleano que direciona a promessa retornada de runAdAuction() para resolver um FencedFrameConfig se for verdadeiro (para uso em um <fencedframe>) ou um URL urn:uuid opaco se for falso (para uso em um <iframe>). O padrão é "false".

Fornecer indicadores de forma assíncrona

Os valores de alguns indicadores (configurados pelos campos auctionSignals, sellerSignals, perBuyerSignals e perBuyerTimeouts) podem ser fornecidos opcionalmente não como valores concretos, mas como Promises. Isso permite que algumas partes do leilão, como o carregamento de scripts e indicadores confiáveis, e o lançamento de processos de worklet isolados, se sobreponham à computação (ou recuperação de rede) desses valores. Os scripts do worklet só vão ver os valores resolvidos. Se alguma dessas promessas for rejeitada, o leilão será cancelado, a menos que já tenha falhado ou sido 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, e os vencedores de leilões separados são encaminhados para outro leilão, realizado por outro vendedor. Esses leilões separados que são transmitidos são chamados de leilões de componentes. Para facilitar esses leilões de componentes, o objeto componentAuctions pode conter configurações adicionais de leilão para cada leilão de componente do vendedor. O lance vencedor de cada um desses leilões de componentes será transmitido ao leilão de "nível superior", que faz a determinação final do leilão. Os auctionConfig dos leilões de componentes podem não ter um componentAuctions próprio. Quando componentAuctions não está vazio, interestGroupBuyers precisa estar vazio. Ou seja, para qualquer leilão de público-alvo protegido, há um único vendedor e nenhum leilão de componente, ou 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 para o anúncio. Nenhum código na página do editor pode inspecionar o anúncio vencedor ou saber o conteúdo dele com base no resultado de runAdAuction(). Se a flag resolveToConfig estiver definida como "true" no AuctionConfig, um objeto FencedFrameConfig será retornado, que só poderá ser renderizado em um frame isolado. Se a flag foi definida como "false", um URN opaco será retornado e poderá 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.