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