Guia da API do vendedor e referências para o leilão de anúncios da API Protected Audience.
Neste artigo, você vai encontrar uma referência técnica para o leilão de anúncios, conforme usado na iteração atual da API experimental Protected Audience.
Leia o guia para desenvolvedores para conferir o ciclo de vida completo da API Protected Audience e consulte a explicação da API Protected Audience para conferir uma discussão mais detalhada sobre como os vendedores realizam leilões no dispositivo.
Não é um desenvolvedor? Consulte a visão geral da API Protected Audience.
O que é o leilão de anúncios da API Protected Audience?
Um leilão de anúncios da API Protected Audience é um conjunto de pequenos programas JavaScript que o navegador executa no dispositivo do usuário para escolher um anúncio. Para preservar a privacidade, todo o código do leilão de anúncios do vendedor e dos compradores é executado em worklets JavaScript isolados que não podem se comunicar com o mundo externo.
- Um usuário visita um site que exibe anúncios.
- O código do vendedor executa
navigator.runAdAuction()
. Ela especifica qual espaço publicitário está à venda e quem pode dar lances. Os vendedores também precisam incluir um script que pontua cada lance,scoreAd()
. - O código do comprador convidado é executado para gerar um lance, o URL de um criativo de anúncio relevante e outros dados. O script de lances pode consultar dados em tempo real, como o orçamento restante da campanha publicitária, no serviço de chave-valor do comprador.
- O código do vendedor pontua cada lance e seleciona o vencedor. Essa lógica usa o valor do lance, e outros dados retornam a atratividade de um lance. Os anúncios que não puderem vencer o vencedor contextual serão rejeitados. O vendedor pode usar o próprio serviço de chave-valor para dados em tempo real.
- O anúncio vencedor é retornado como um valor opaco, que é exibido em um frame isolado. O vendedor e o editor não podem conferir esse valor.
- O leilão é informado ao vendedor e aos compradores vencedores.
Quando ocorre o leilão?
A API Protected Audience pode ser executada por conta própria ou com leilões programáticos. Em um leilão programático com vários vendedores:
- O usuário visita um site participante.
- Um leilão programático é realizado por outro vendedor para encontrar um anúncio contextual para um espaço disponível.
- O leilão da API Protected Audience é realizado.
scoreAd()
compara os lances do comprador com os resultados do primeiro leilão.
Os lances que não conseguem superar o vencedor contextual são rejeitados.
Quem realiza o leilão de anúncios da API Protected Audience?
Existem várias partes que podem realizar um leilão para vender espaço publicitário.
Exemplo:
- Editor de conteúdo: agir por conta própria para hospedar conteúdo de anúncios no site.
- Plataforma de fornecimento (SSP, na sigla em inglês): trabalhar com o editor e fornecer outros serviços.
- Script de terceiros: atua em nome de um editor, para permitir a participação em leilões de anúncios.
Com a API Protected Audience, um vendedor tem três funções:
- Aplicar regras do editor: quais compradores e lances são qualificados.
- Execute a lógica do leilão: o JavaScript é executado em worklets para calcular uma pontuação de desejabilidade para cada lance.
- Informe o resultado do leilão.
Esses jobs são feitos de forma programática no código fornecido pelo vendedor quando ele
inicia um leilão de anúncios chamando a função JavaScript
navigator.runAdAuction()
.
Funções da API
runAdAuction()
O vendedor chama navigator.runAdAuction()
para fazer uma solicitação ao navegador do usuário para iniciar um leilão de anúncios.
Exemplo:
const auctionConfig = {
seller: 'https://ssp.example',
decisionLogicUrl: ...,
trustedScoringSignalsUrl: ...,
interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
auctionSignals: {...},
sellerSignals: {...},
sellerTimeout: 100,
perBuyerSignals: {
'https://dsp.example': {...},
'https://another-buyer.example': {...},
...
},
perBuyerTimeouts: {
'https://dsp.example': 50,
'https://another-buyer.example': 200,
'*': 150,
...
},
componentAuctions: [
{
'seller': 'https://some-other-ssp.example',
'decisionLogicUrl': ...,
...
},
...
]
};
try {
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
// Handle error.
}
runAdAuction()
retorna uma promessa que é resolvida em um URN (urn:uuid:<something>
) que representa o
resultado do leilão de anúncios. Ele só pode ser decodificado pelo navegador quando transmitido para um frame isolado
para renderização: a página do editor não pode inspecionar o anúncio vencedor.
O script decisionLogicUrl
considera cada anúncio individual, bem como o lance e os metadados associados, um por vez, e atribui uma pontuação de desejabilidade numérica.
auctionConfig
propriedades
seller
- Obrigatório
- Exemplo:
'https://ssp.example'
- Papel: origem do vendedor.
decisionLogicUrl
- Obrigatório
- Exemplo:
'https://ssp.example/auction-decision-logic.js'
- Papel: URL para JavaScript de worklet de leilão.
trustedScoringSignalsUrl
- Opcional
- Exemplo:
'https://ssp.example/scoring-signals'
- Papel: URL do servidor confiável do vendedor.
interestGroupBuyers
- Obrigatório
- Exemplo:
['https://dsp.example', 'https://buyer2.example', ...]
- Função: origens de todos os proprietários de grupos de interesse que pediram lances no leilão.
- Observação: o vendedor pode especificar
interestGroupBuyers:
para permitir que todos os grupos de interesse deem lances. Os anúncios são aceitos ou rejeitados com base em critérios diferentes da inclusão do proprietário do grupo de interesse. Por exemplo, o vendedor pode revisar os criativos de anúncios para confirmar a conformidade com as políticas. auctionSignals
- Opcional
- Exemplo:
{...}
- Papel: informações do vendedor sobre o contexto da página, tipo de leilão etc.
sellerSignals
- Opcional
- Exemplo:
{...}
- Papel: informações com base nas configurações do editor, fazendo uma solicitação de anúncio contextual etc.
sellerTimeout
- Opcional
- Exemplo:
100
- Papel: ambiente de execução máximo (ms) do script
scoreAd()
do vendedor. perBuyerSignals
- Opcional
- Exemplo:
{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ... }
- Papel: indicadores de contexto sobre a página para cada comprador específico, do servidor.
perBuyerTimeouts
- Opcional
- Exemplo:
50
- Papel: ambiente de execução máximo (ms) dos scripts
generateBid()
do comprador específico. componentAuctions
- Opcional
- Exemplo:
[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...]
- Papel: configurações adicionais para leilões de componentes.
decisionLogicUrl
O decisionLogicUrl
é uma propriedade do objeto de configuração do leilão,
transmitido para runAdAuction()
. Esse URL precisa incluir um script para a
função scoreAd()
. Essa lógica é executada uma vez para cada anúncio para
determinar a atratividade dele.
scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
...
return desirabilityScoreForThisAd;
}
browserSignals
browserSignals
é um objeto criado pelo navegador, incluindo informações
que o navegador conhece e que o script de leilão do vendedor pode querer
verificar:
{
topWindowHostname: 'publisher.example',
interestGroupOwner: 'https://dsp.example',
renderUrl: 'https://cdn.example/render',
adComponents: ['https://cdn.com/ad-component-1', ...],
biddingDurationMsec: 12,
dataVersion: 1 /* DValue from the seller's Key/Value service response. */
}
Antes do início de um leilão, o vendedor encontra o melhor anúncio contextual para o
espaço disponível. Parte da lógica scoreAd()
rejeita qualquer anúncio que não possa
vencer o vencedor contextual.
scoreAd()
scoreAd()
usa os seguintes argumentos:
Argumento | Papel |
---|---|
adMetadata |
Metadados arbitrários fornecidos pelo comprador. |
auctionConfig |
O objeto de configuração do leilão transmitido para navigator.runAdAuction() . |
bid |
Um valor de lance numérico. |
trustedScoringSignals |
Valores recuperados do servidor confiável do vendedor no momento do leilão, representando a opinião do vendedor sobre o anúncio. |
Perguntas frequentes
Como o vencedor do leilão será escolhido e quem os escolherá?
O vendedor fornece a lógica de pontuação para determinar a pontuação de atratividade de cada anúncio, e o navegador seleciona a pontuação mais alta como o anúncio vencedor.
O vendedor inclui lógica na função scoreAd()
, e o navegador executa a função em um worklet que tem comunicação limitada com o código fora dele. O navegador não pontua os anúncios. O navegador é o único responsável por executar a lógica de pontuação e selecionar o lance com a pontuação mais alta.
Todas as referências da API Protected Audience
Os guias de referência da API estão disponíveis:
- Guia do desenvolvedor da API Protected Audience.
- Guia do comprador de anúncios sobre grupos de interesse e geração de lances da API Protected Audience.
- Guia do vendedor de anúncios para leilões de anúncios da Protected Audience.
- Guia para gerar relatórios de resultados do leilão
- Práticas recomendadas para latência do leilão de anúncios da Protected Audience
- Resolver problemas da API Protected Audience
A explicação da API Protected Audience também fornece detalhes sobre o suporte e as restrições de recursos.