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 com Protected Audience no dispositivo é realizado em um site que vende espaços publicitários, e nós a parte que realiza o leilão é o vendedor. Muitas partes podem agir vendedores: um site pode realizar o próprio leilão de anúncios ou incluir um terceiro script para gerar 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) quais compradores podem participar e (b) quais dos lances dos compradores grupos de interesse se qualificam para participar do leilão. Isso permite o vendedor aplica as regras do site sobre quais anúncios podem aparecer no página.
2. Os vendedores são responsáveis pela lógica de negócios do leilão: JavaScript. que considera o preço e os metadados de cada lance e calcula um "adequação" de qualidade. O lance com a maior pontuação de atratividade ganha 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 para 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. Isso é feito criando 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 do a API Protected Audience. Leia a seção Participantes do leilão na seção Explicação sobre a API Audience para mais informações.

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 para o 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 receberam pedidos de lance no leilão

Propriedades opcionais

As propriedades restantes de auctionConfigs são opcionais.

Propriedade	Exemplo	Papel
trustedScoringSignalsUrl	https://seller.example/scoring-signals	URL do servidor de chave-valor do vendedor. Ela será consultada 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 que o campo do vendedor.
auctionSignals	{"category":"news"}	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 somente 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 determinado comprador. 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 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 for verdadeiro (para uso em um <fencedframe>) ou para 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 por auctionSignals, sellerSignals, perBuyerSignals e perBuyerTimeouts) pode ser fornecidas opcionalmente não como valores concretos, mas como promessas. Isso permite algumas partes do leilão, como carregamento de scripts e indicadores de confiança, lançamento de processos isolados do worklet, para se sobrepor à computação recuperação) desses valores. Os scripts do worklet só verão as respostas valores se alguma Promessa for rejeitada, o leilão será cancelado, a menos que já conseguiu falhar ou foi abortada de outras maneiras.

Configurar um leilão com vários vendedores

Em alguns casos, vários vendedores podem querer participar de um leilão, com o vencedores de leilões separados repassados para outro leilão, realizado por outro vendedor. Esses leilões separados que estão sendo ignorados são chamados de leilões de componentes. Para facilitar esses leilões de componentes, o objeto componentAuctions pode conter configurações de leilão adicionais para cada leilão de componentes do vendedor. A o lance vencedor de cada um desses leilões componentes serão passados para o "nível superior" que toma a decisão final do leilão. A auctionConfig dos leilões de componentes não podem ter os próprios componentAuctions. Quando componentAuctions não estiver vazio, interestGroupBuyers precisa estar vazio. Ou seja, para domínios de proteção específicos, leilão de público-alvo, ou seja, um único vendedor e nenhum leilão de componentes, ou caso contrário, todos os lances serão provenientes de leilões de componentes, e o leilão de nível superior só poderá escolher entre os leilões de componentes vencedores.

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. Não é qualquer código na página do editor inspecionar o anúncio vencedor ou Saiba mais sobre o conteúdo usando o resultado de runAdAuction(). Se o A sinalização resolveToConfig foi definida como verdadeira em AuctionConfig, uma O objeto FencedFrameConfig é retornado, e só pode ser renderizado em um contêiner frame. Se o flag for definido como falso, será retornado um URN opaco que pode ser renderizados em um iframe. É possível que runAdAuction retorne um valor nulo, indicando que nenhum anúncio foi selecionado. Nesse caso, o vendedor pode optar processar um anúncio segmentado por contexto.