Os serviços de lances e leilões (B&A) são um conjunto de serviços para compradores e vendedores de anúncios executados em um ambiente de execução confiável (TEE) para facilitar um leilão de público-alvo protegido (PA). Este guia para desenvolvedores explica como um comprador pode fazer a integração com um leilão de PA de B&A para o Chrome.
Visão geral
Para participar de um leilão da Protected Audience com os serviços de B&A, o comprador atualiza o grupo de interesse (IG) para otimizar o payload e melhorar a latência do leilão.
As seguintes tarefas de otimização de payload são exigidas pelo comprador:
- Tarefas
joinAdInterestGroup()
- Tarefas
generateBid()
Grupo de interesse para perguntas e respostas
Confira a seguir um exemplo de configuração de grupo de interesse para um leilão de PA de B&A com otimização de payload aplicada:
navigator.joinAdInterestGroup({
name: 'example-ig',
owner: 'https://dsp.example',
// An ID is mapped to each render URL
ads: [
{
renderURL: 'https://dsp.example/ad.html',
adRenderId: '12345678' // 12 characters max,
buyerReportingId: 'brid123', // Optional
buyerAndSellerReportingId: 'bsrid123', // Optional
selectableBuyerAndSellerReportingId: ['sbsrid123', 'sbsrid456'], // Optional
},
],
adComponents: [
{
renderURL: 'https://dsp.example/ad-component.html',
adRenderId: 'abcdefgh'
},
],
// Flags are set to omit data in the B&A auction payload
auctionServerRequestFlags: ['omit-ads', 'omit-user-bidding-signals'],
// Data not included in the B&A auction payload can be fetched as trusted signals
// The following is an example of how the keys could look, but the actual
// implementation is up to the ad tech
trustedBiddingSignalsKeys: [
'exampleUserBiddingSignalsKey',
'exampleAdRenderIdKey',
'exampleAdMetadataKey',
'exampleAdReportingIdKey',
],
// Optionally, interest groups can be prioritized
priority: 0.0,
});
As diferenças entre as configurações do grupo de interesse no dispositivo e do B&A são as seguintes:
Campos | Perguntas e respostas do Instagram | IG no dispositivo | Incluído no payload do leilão de B&A |
auctionServerRequestFlags |
Usados | Não utilizado | Não |
userBiddingSignals |
Não recomendado | Usados | Não, se a flag omit-user-bidding-signals estiver definida |
adRenderId em ads e adComponents |
Usados | Não utilizado | Se a flag omit-ads estiver definida, o adRenderId em ads estará disponível apenas em browserSignals.prevWins do payload. O adRenderId definido em adComponents não é incluído no payload.Se a flag |
renderURL em ads e adComponents |
Usados | Usados | Não |
metadata em ads e adComponents |
Não utilizado | Usados | Não |
IDs de relatórios em ads |
Usados | Usados | Não |
- O campo
auctionServerRequestFlags
permite definir flags que informam ao navegador para omitir alguns dados na carga de dados do leilão de B&A. - O valor
userBiddingSignals
pode ser definido no grupo de interesse, mas é recomendável omitir esse valor usando a flagomit-user-bidding-signals
. Os indicadores omitidos podem ser fornecidos usando o serviço K/V. - O campo
adRenderId
é definido com orenderURL
associado, mas apenas oadRenderId
vai fazer parte do payload do leilão de B&A. O URL de renderização retornado degenerateBid()
mais tarde durante o leilão precisa corresponder ao URL de renderização definido no IG. - Os IDs de relatórios são definidos no IG de B&A, mas não são incluídos no payload do leilão de B&A. O ID de relatório retornado de
generateBid()
mais tarde durante o leilão precisa corresponder ao URL de renderização definido no IG. - O
ad.metadata
e os IDs de relatórios não são incluídos no payload do leilão de B&A. Em vez disso, esses dados ficam disponíveis pelo uso do serviço de chave-valor confiável.
Os renderURL
s e os IDs de relatórios em ads
ainda são definidos na configuração do grupo de interesse, mas não são incluídos no payload da solicitação de leilão porque o navegador verifica se o URL de renderização e os IDs de relatórios retornados da função generateBid()
do serviço de lances correspondem aos valores definidos no grupo de interesse.
joinAdInterestGroup()
tarefas
As tarefas a seguir precisam ser realizadas para a chamada joinAdInterestGroup()
.
Definir sinalizações de solicitação do servidor
O campo auctionServerRequestFlags
da configuração joinAdInterestGroup()
aceita as seguintes flags:
Sinalização | Descrição |
omit-user-bidding-signals |
A flag omit-user-bidding-signals omite o objeto userBiddingSignals no payload do leilão.
Se a flag não estiver definida, o valor |
omit-ads |
A flag omit-ads informa ao navegador para omitir os objetos ads e adComponents no payload do leilão.O Se a flag não estiver definida, os campos É altamente recomendável que os compradores escolham a flag |
Os dados omitidos são processados disponibilizando informações relevantes em trustedBiddingSignals
. As flags podem ser usadas individualmente e não precisam ser usadas juntas.
Exemplo de uso:
navigator.joinAdInterestGroup({
auctionServerRequestFlags: ['omit-user-bidding-signals', 'omit-ads'],
});
Definir IDs de renderização de anúncios
Para reduzir o tamanho do payload do leilão de B&A, os objetos ads
e adComponents
do grupo de interesse são omitidos e, por sua vez, não estão disponíveis na função generateBid()
executada no serviço de lances.
Para lidar com as informações de anúncios ausentes, o comprador mantém um identificador (adRenderId
e adComponentRenderId
) associado a cada anúncio na configuração do grupo de interesse. O identificador precisa ser um DOMString de 12 bytes ou menos. Se o identificador for codificado em Base64, o comprimento dele precisa ser de 12 bytes ou menos.
Exemplo de grupo de interesse com IDs de renderização de anúncios:
navigator.joinAdInterestGroup({
ads: [
{
renderURL: 'https://dsp.example/ad.html',
adRenderId: '12345678' // 12 characters max
},
],
adComponents: [
{
renderURL: 'https://dsp.example/ad-component.html',
adComponentRenderId: 'abcdefgh'
},
],
});
O adRenderId
associado aos anúncios vai ficar disponível em prevWins.browserSignals
em generateBid()
.
Embora o renderURL
não seja incluído no payload da solicitação, o URL de renderização retornado de generateBid()
precisa corresponder ao URL de renderização definido na configuração do grupo de interesse. As adtechs podem enviar metadados de anúncios e outras informações em trustedBiddingSignals
para que o URL de renderização do anúncio e o URL de renderização do componente do anúncio possam ser gerados para o lance durante a execução de generateBid()
.
Definir prioridades de grupos de interesse
O Chrome permite que os compradores priorizem grupos de interesse. Se o limite de tamanho do payload por comprador definido pelo vendedor for alcançado, os valores de prioridade do grupo de interesse serão usados para excluir os grupos de interesse de menor prioridade de um único comprador quando o payload do leilão de B&A for gerado para o vendedor. Para selecionar grupos de interesse entre compradores diferentes, o navegador decide com base no tamanho do payload serializado. Por padrão, cada comprador tem o mesmo tamanho. A priorização real ocorre nos servidores de B&A, e não quando o payload da solicitação é gerado.
A prioridade é calculada no momento do leilão usando os vetores de prioridade do comprador (priorityVector
) e os indicadores de prioridade do vendedor (prioritySignals
). O comprador pode substituir os indicadores de prioridade do vendedor.
Propriedade | Descrição |
Vetor de prioridade | O comprador fornece os vetores como o valor da chave priorityVector do serviço de chave-valor. |
Indicadores de prioridade | O vendedor fornece os indicadores definindo priority_signals da configuração do leilão. |
Modificações de indicadores prioritários | O comprador fornece a substituição no campo priority_signals_overrides do PerBuyerConfig na configuração do leilão. |
Durante o leilão, o navegador calcula o produto escalar das chaves correspondentes em priorityVector
e prioritySignals
para a prioridade. No diagrama a seguir, a prioridade é calculada por (4 * 2) + (3 * -1)
, que é reduzida para 8 + -3
. Portanto, a prioridade desse grupo de interesse no momento do leilão é 5
.

Outros indicadores também estão disponíveis para priorização em perguntas e respostas:
Sinal | Descrição |
deviceSignals.one |
O valor é sempre 1 e é útil para adicionar uma constante ao produto escalar. |
deviceSignals.ageInMinutes |
O valor descreve a idade do grupo de interesse (o tempo desde a adesão mais recente) em minutos como um número inteiro entre 0 e 43.200. |
deviceSignals.ageInMinutesMax60 |
O valor descreve o mesmo que o indicador ageInMinutes , mas tem o limite máximo de 60. Se o grupo tiver mais de uma hora, o valor retornado será 60. |
deviceSignals.ageInHoursMax24 |
O valor descreve a idade do grupo de interesse em horas, com um máximo de 24 horas. Se o grupo tiver mais de um dia, o valor 24 será retornado. |
deviceSignals.ageInDaysMax30 |
O valor descreve a idade do grupo de interesse em dias, com um máximo de 30 dias. Se o grupo tiver mais de 30 dias, o valor 30 será retornado. |
Para saber mais, acesse a explicação no GitHub.
Configurar indicadores de lances confiáveis
Como alguns dados serão omitidos do payload do leilão de B&A, use o serviço de chave-valor para fornecer os dados omitidos como indicadores de lances confiáveis para a função generateBid()
.
Os seguintes dados omitidos podem ser fornecidos pelo serviço de K/V:
userBiddingSignals
se usado pelo compradormetadata
associado a cada anúncioadRenderId
associado a cada anúncio- Código do relatório

Uma abordagem possível é incluir um identificador exclusivo nas chaves de indicadores de lances confiáveis e enviar os dados associados ao servidor para que eles possam ser carregados no serviço de chave/valor. No entanto, a implementação real depende da adtech, e a API não é prescritiva.
O exemplo a seguir descreve uma abordagem que pode ser implementada:
const ad1RenderURL = 'https://dsp.example/ad-1.html';
const ad2RenderURL = 'https://dsp.example/ad-2.html';
const ad1RenderId = 'render-id-1';
const ad2RenderId = 'render-id-2';
const ad1ReportingId = 'reporting-id-1';
const ad2ReportingId = 'reporting-id-2';
// Generate a unique identifier
const id = crypto.randomUUID();
// Define the keys with the unique ID
const trustedSignalsKeyForIG = `interest-group-${id}`
// Set the keys in the interest group
navigator.joinAdInterestGroup({
// …
ads: [
{
renderURL: ad1RenderURL,
adRenderId: ad1RenderId,
buyerReportingId: ad1ReportingId
},
{
renderURL: ad2RenderURL,
adRenderId: ad2RenderId,
buyerReportingId: ad2ReportingId
},
],
trustedBiddingSignalsKeys: [
trustedSignalsKeyForIG
]
});
// Send the associated data to your server to be loaded into the Key/Value Service
fetch('https://dsp.example/kv/load', {
method: 'POST',
body: JSON.stringify({
id,
[trustedSignalsKeyForIG]: {
userBiddingSignals: {
favoriteColor: 'blue'
},
ads: [
{
renderURL: ad1RenderURL,
adRenderId: ad1RenderId,
buyerReportingId: ad1ReportingId,
metadata: {
color: 'red'
}
},
{
renderURL: ad2RenderURL,
adRenderId: ad2RenderId,
buyerReportingId: ad2ReportingId,
metadata: {
color: 'blue'
}
},
]
}
})
});
No exemplo, um identificador exclusivo é definido para um IG e passa a fazer parte da chave de indicadores confiáveis. A chave do IG e os valores associados são enviados ao servidor para serem carregados no serviço de chave-valor. Mais tarde, durante o leilão, o navegador busca os indicadores confiáveis e os disponibiliza na função generateBid()
do comprador.
Se necessário, retorne o indicador de atualização do grupo de interesse do K/V
A chave updateIfOlderThanMs
para os indicadores confiáveis é usada para atualizar o grupo de interesse antes do intervalo diário normal. Se o grupo de interesse não tiver sido adicionado ou atualizado em um período que exceda o valor de milissegundos retornado para a chave updateIfOlderThanMs
, ele será atualizado com o mecanismo updateURL
. O Chrome não atualiza os grupos de interesse com mais frequência do que uma vez a cada 10 minutos.
Se o leilão de B&A retornar um anúncio vencedor que não corresponde a um dos anúncios definidos no grupo de interesse armazenado no navegador, o leilão será cancelado. O mecanismo updateIfOlderThanMs
pode ser útil para garantir que o navegador e o leilão de B&A concordem com o conjunto de anúncios no grupo de interesse.
Acesse o texto explicativo para saber mais.
generateBid()
tarefas
As tarefas a seguir precisam ser realizadas para a chamada generateBid()
.
Ler sinais do navegador
O objeto browserSignals
transmitido para a chamada generateBid()
de B&A tem esta aparência:
{
topWindowHostname: 'advertiser.example',
seller: 'https://ssp.example',
topLevelSeller: 'https://ssp-top.example',
joinCount: 5,
bidCount: 24,
recency: 1684134092,
// prevWins is [timeInSeconds, adRenderId]
prevWins: [
[9342, 'render-id-1'],
[1314521, 'render-id-2']
],
// Compiled WebAssembly code
wasmHelper: WebAssembly.Module
// Data-Version value from K/V response, if available
dataVersion: 1,
}
As seguintes propriedades modificadas ou novas estão disponíveis em browserSignals
:
Propriedade | Descrição |
prevWins |
prevWins é uma matriz de tuplas de tempo e anúncio. O tempo representa os segundos decorridos desde a vitória anterior do anúncio associado nos últimos 30 dias.Ele foi modificado para fornecer o |
wasmHelper |
Objeto compilado do código fornecido por biddingWasmHelperURL . |
dataVersion |
Um servidor confiável pode incluir um cabeçalho de resposta Data-Version numérico que fica disponível em generateBid() .Leia a explicação no GitHub para saber mais. |
Retornar o URL de renderização de generateBid()
Como o objeto ads
é omitido no payload do leilão de B&A, o URL de renderização retornado de generateBid()
precisa ser recriado. A forma como o URL de renderização é recriado é determinada pela sua implementação, e o URL retornado precisa corresponder ao URL de renderização definido no grupo de interesse.
Uma abordagem possível é manter um URL base e preencher o modelo com as informações de interestGroup
e trustedBiddingSignals
.
Neste exemplo, estamos definindo quatro anúncios com base na cor e no produto:
await navigator.joinAdInterestGroup({
ads: [
{ renderURL: 'https://dsp.example/red-shirt-ad.html', adRenderId: 'arid1'},
{ renderURL: 'https://dsp.example/blue-shirt-ad.html', adRenderId: 'arid2'},
{ renderURL: 'https://dsp.example/red-pants-ad.html', adRenderId: 'arid3'},
{ renderURL: 'https://dsp.example/blue-pants-ad.html', adRenderId: 'arid4'},
],
trustedBiddingSignalKeys: [
'userBiddingSignals-someUniqueId',
// ...and more
]
})
Em seguida, enviamos a cor favorita do usuário e as informações do produto para serem carregadas no serviço de chave-valor:
fetch('https://dsp.example/kv/load', {
body: JSON.stringify({
'userBiddingSignals-someUniqueId': {
favoriteColor: 'blue',
favoriteProduct: 'shirt'
}
})
})
Mais tarde, quando o leilão for realizado, os indicadores de lances confiáveis vão ficar disponíveis em generateBid()
, e essas informações poderão ser usadas para reconstruir o URL:
function generateBid(..., trustedBiddingSignals, browserSignals) {
const { userBiddingSignals } = trustedBiddingSignals
const { favoriteColor, favoriteProduct } = userBiddingSignals
return {
bid: 1,
render: `https://dsp.example/${favoriteColor}-${favoriteProduct}-ad.html`
}
}
Retornar IDs de relatórios de generateBid()
Como os IDs de relatórios não estão incluídos no payload do leilão de B&A, o ID fica disponível para generateBid()
por meio de indicadores de lances confiáveis. Depois que o ID do relatório a ser usado é determinado, o ID escolhido é retornado de generateBid()
. Os IDs retornados precisam corresponder aos IDs definidos no grupo de interesse.
Neste exemplo, o anúncio 1 é escolhido, e o ID de renderização associado a ele é retornado de generateBid()
:
generateBid(..., trustedBiddingSignals, …) {
const { ad1ReportingId, ad2reportingId } = trustedBiddingSignals;
// ...
return {
bid: 1,
render: 'https://dsp.example/ad-1.html'
buyerReportingId: ad1reportingId
}
}
O ID de relatório retornado fica disponível em reportWin()
até buyerReportingSignals
:
reportWin(..., buyerReportingSignals) {
const { buyerReportingId } = buyerReportingSignals;
}
Se buyerReportingId
não for retornado de generateBid()
, o valor interestGroupName
estará disponível em buyerReportingSignals
em vez de buyerReportingId
.
Acesse o guia do ID de relatório para saber mais.
Próximas etapas
Os recursos a seguir estão disponíveis para você
Saiba mais
- Saiba mais sobre as configurações de leilões de B&A no Chrome.
- Teste a API Protected Audience com B&A seguindo o codelab de teste local de ponta a ponta.
Dúvidas?
- Se você tiver dúvidas sobre os serviços de lances e leilões, abra um problema no repositório de serviços de lances e leilões.
- Se você tiver dúvidas sobre o Sandbox de privacidade em geral, abra um problema no repositório privacy-sandbox-dev-support .