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