Qual é o público deste artigo?
Esta postagem é uma referência técnica à iteração atual da API Protected Audience experimental.
A API Protected Audience tem uma visão geral menos técnica da proposta e também tem um glossário.
A demonstração da API Protected Audience oferece um tutorial de uma implantação básica do FLEDGE.
O vídeo de demonstração da Protected Audience (em inglês) explica como o código de demonstração funciona e mostra como usar o Chrome DevTools para a depuração da API Protected Audience.
O que é a API Protected Audience?
A API Protected Audience é uma proposta do Sandbox de privacidade para atender a casos de uso de remarketing e públicos-alvo personalizados, projetada para que não possa ser usada por terceiros para rastrear o comportamento de navegação do usuário em sites. A API permite leilões no dispositivo pelo navegador para escolher anúncios relevantes para sites que o usuário visitou anteriormente.
A API Protected Audience é o primeiro experimento a ser implementado no Chromium na família de propostas TURTLEDOVE.
O diagrama abaixo mostra uma visão geral do ciclo de vida do FLEDGE:
Como posso testar a API Protected Audience?
Demonstração da API Protected Audience
Um tutorial de uma implantação básica da API Protected Audience nos sites de anunciantes e editores está disponível em Protectd-audience-demo.web.app.
O vídeo de demonstração explica como o código de demonstração funciona e mostra como usar o Chrome DevTools para depuração da API Protected Audience.
Participe de um teste de origem da Protected Audience
Um teste de origem de relevância e medição do Sandbox de privacidade foi disponibilizado no Chrome Beta 101.0.4951.26 e versões mais recentes para computadores para as APIs Protected Audience, Topics e Attribution Reporting.
Para participar, registre-se para receber um token de teste de origem.
Depois de se inscrever, você poderá testar a API Protected Audience JavaScript em páginas que fornecem um token de teste válido. Por exemplo, pedir ao navegador para participar de um ou mais grupos de interesse e realizar um leilão de anúncios para selecionar e mostrar um anúncio.
A demonstração da Protected Audience oferece um exemplo básico de uma implantação completa.
Forneça um token de teste para cada página em que você quer executar o código da API Protected Audience:
Como uma metatag em <head>:
<meta http-equiv="origin-trial" content="TOKEN_GOES_HERE">
Como um cabeçalho HTTP:
Origin-Trial: TOKEN_GOES_HERE
Ao fornecer um token de maneira programática:
const otMeta = document.createElement('meta'); otMeta.httpEquiv = 'origin-trial'; otMeta.content = 'TOKEN_GOES_HERE'; document.head.append(otMeta);
Um iframe que executa o código da API Protected Audience, como uma chamada navigator.joinAdInterestGroup()
feita pelo proprietário de um grupo de interesse, precisa fornecer um token que corresponda à origem.
Os primeiros detalhes propostos de teste de origem da API Protected Audience fornecem mais detalhes sobre as metas do primeiro teste e explicam quais recursos têm suporte.
Testar com chrome://flags
ou flags de recursos
É possível testar a API Protected Audience para um único usuário no Chrome Beta 101.0.4951.26 e versões mais recentes no computador:
* Ative chrome://flags/#privacy-sandbox-ads-apis
.
* Configurando sinalizações a partir da linha de comando.
Renderizar anúncios em iframes ou frames delimitados
Os anúncios podem ser renderizados em <iframe>
ou <fencedframe>
, dependendo das sinalizações definidas.
Se quiser usar <fencedframe>
para renderizar anúncios, faça o seguinte:
--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,FencedFrames
Se quiser usar <iframe>
para renderizar anúncios, faça o seguinte:
--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,AllowURNsInIframes --disable-features=FencedFrames
Inclua a sinalização BiddingAndScoringDebugReportingAPI
para ativar os métodos de relatório temporário de perda/ganho de depuração.
Executar o Chromium com sinalizações explica como definir sinalizações ao executar o Chrome e outros navegadores baseados no Chromium pela linha de comando. A lista completa de sinalizações da API Protected Audience está disponível na Pesquisa de código do Chromium.
Quais recursos são compatíveis com a versão mais recente do Chrome?
A API Protected Audience está sendo disponibilizada por trás de sinalizações de recursos no Chromium como um primeiro experimento para testar os seguintes recursos da proposta da Protected Audience:
- Grupos de interesse: armazenados pelo navegador, com metadados associados para configurar os lances e a renderização de anúncios.
- Lances no dispositivo por compradores (DSP ou anunciante): baseados em sinais e grupos de interesse armazenados do vendedor.
- Seleção de anúncios no dispositivo pelo vendedor (SSP ou editor): com base em lances de leilão e metadados de compradores.
- Renderização de anúncios em uma versão temporariamente simplificada de Fenced Frames: com acesso à rede e geração de registros permitidos para a renderização de anúncios.
A explicação da API dá mais detalhes sobre o suporte e as restrições de recursos.
Permissões do grupo de interesse
O padrão na implementação atual da Protected Audience é permitir chamar joinAdInterestGroup()
de
qualquer lugar da página, mesmo de iframes entre domínios. No futuro, assim que os proprietários dos sites tiverem tempo de ajustar as políticas de permissões de iframe entre domínios, o plano será proibir chamadas de iframes de vários domínios, conforme descrito na explicação.
Serviço de chave-valor
Como parte de um leilão de anúncios da Protected Audience, o navegador pode acessar um serviço de chave-valor que retorna pares simples de chave-valor para fornecer informações a um comprador de anúncios, como o orçamento restante da campanha. A proposta da Protected Audience manda que esse servidor "não realize a geração de registros no nível do evento e não tenha outros efeitos colaterais com base nessas solicitações".
O código de serviço de chave-valor da API Protected Audience agora está disponível em um repositório do Sandbox de privacidade do GitHub (link em inglês). Esse serviço pode ser usado por desenvolvedores do Chrome e do Android. Confira a postagem do blog com o anúncio para saber a atualização de status. Saiba mais sobre o serviço de chave-valor da API Protected Audience com a explicação da API e a explicação sobre o modelo de confiança.
Para o teste inicial, é usado o modelo "Traga seu próprio servidor". A longo prazo, as adtechs vão precisar usar os serviços de chave-valor de código aberto da Protected Audience em ambientes de execução confiáveis para recuperar dados em tempo real.
Para garantir que o ecossistema tenha tempo suficiente para os testes, não esperamos exigir o uso dos serviços de chave/valor de código aberto ou TEEs até algum momento após a descontinuação dos cookies de terceiros. Enviaremos um aviso substancial para que os desenvolvedores comecem a testar e a adotar antes que essa transição ocorra.
Detectar suporte a recursos
Antes de usar a API, verifique se ela é compatível com o navegador e está disponível no documento:
'joinAdInterestGroup' in navigator &&
document.featurePolicy.allowsFeature('join-ad-interest-group') &&
document.featurePolicy.allowsFeature('run-ad-auction') ?
console.log('navigator.joinAdInterestGroup() is supported on this page') :
console.log('navigator.joinAdInterestGroup() is not supported on this page');
Como desativo a API Protected Audience?
Você pode bloquear o acesso à API Protected Audience como proprietário do site ou usuário individual.
Como os sites podem controlar o acesso?
Em algum momento, a API Protected Audience vai exigir que os sites definam uma política de permissões para disponibilizar a funcionalidade da API. Isso ajudará a garantir que terceiros arbitrários não possam usar a API sem o conhecimento do site. No entanto, para facilitar o teste durante o primeiro teste de origem, esse requisito é renunciado por padrão. Os sites que quiserem desativar explicitamente a funcionalidade da API Protected Audience durante o período de teste podem usar a política de permissões relevante para bloquear o acesso.
Há duas políticas de permissões da API Protected Audience que podem ser definidas de forma independente:
* join-ad-interest-group
ativa/desativa a funcionalidade de adicionar um navegador a grupos de interesse.
* run-ad-auction
ativa/desativa a funcionalidade de realizar um leilão no dispositivo.
O acesso às APIs Protected Audience pode ser desativado completamente em contextos próprios especificando a seguinte política de permissões em um cabeçalho de resposta HTTP:
Permissions-Policy: join-ad-interest-group=(), run-ad-auction=()
É possível desativar o uso das APIs em um iframe adicionando o seguinte atributo allow
a um
elemento de iframe:
<iframe src="https://example.com" allow="join-ad-interest-group 'none'; run-ad-auction 'none'"></iframe>
A seção Permissões-Política de teste de origem do primeiro teste de público protegido proposto fornece mais detalhes.
Desativação do usuário
Um usuário pode bloquear o acesso à API Protected Audience e a outros recursos do Sandbox de privacidade usando um destes mecanismos:
- Desative os testes do Sandbox de privacidade nas configurações do Chrome: Configurações >
Segurança e privacidade > Sandbox de privacidade. Ele também pode ser acessado em
chrome://settings/adPrivacy
. - Desative os cookies de terceiros nas configurações do Chrome: Configurações > Segurança e privacidade.
- Defina Cookies e outros dados do site como "Bloquear cookies de terceiros" ou "Bloquear todos os cookies"
em
chrome://settings/cookies
. - Use o modo de navegação anônima.
A explicação da API Protected Audience oferece mais detalhes sobre os elementos de design da API e descreve como a API busca atender às metas de privacidade.
Depurar os worklets da API Protected Audience
No Chrome Canary 98.0.4718.0, é possível depurar os worklets de Protected Audience no Chrome DevTools.
A primeira etapa é definir pontos de interrupção com uma nova categoria no painel Event Listener Breakpoints no painel Sources.
Quando um ponto de interrupção é acionado, a execução é pausada antes da primeira instrução no nível superior do script de worklet. Você pode usar pontos de interrupção normais ou comandos de etapa para chegar à própria função de lances/pontuação/relatório.
Os scripts de worklet ativos também serão exibidos no painel "Threads".
Como alguns worklets podem ser executados em paralelo, várias linhas de execução podem acabar no estado "pausada". Você pode usar a lista de linhas de execução para alternar entre elas e retomá-las ou inspecioná-las com mais precisão conforme necessário.
Observar os eventos da API Protected Audience
No painel "Application" no Chrome DevTools, é possível observar o grupo de interesse da Protected Audience e os eventos de leilão.
Se você acessar o site de compras de demonstração da API Protected Audience
em um navegador com a API Protected Audience ativada, o DevTools exibirá informações sobre o evento join
.
Agora, se você acessar o site do editor de demonstração da API Protected Audience
em um navegador com a API Protected Audience ativada, o DevTools exibirá informações sobre os eventos bid
e win
.
Como a API Protected Audience funciona?
Neste exemplo, um usuário visita o site de um fabricante de bicicletas personalizada, depois visita um site de notícias e vê um anúncio de uma nova bicicleta dessa marca.
1. Um usuário visita o site de um anunciante.
Imagine que um usuário visita o site de uma montadora de bicicletas personalizadas (o anunciante neste exemplo) e passa algum tempo na página do produto de uma bicicleta de aço artesanal. Isso fornece ao fabricante de bicicletas uma oportunidade de remarketing.
2. É solicitado que o navegador do usuário adicione um grupo de interesse
Seção de explicação: Grupos de interesse que registram os navegadores
A plataforma de demanda (DSP, na sigla em inglês) do anunciante (ou o próprio anunciante) chama navigator.joinAdInterestGroup()
para solicitar que o navegador adicione um grupo de interesse à lista de grupos de que ele faz parte. Neste exemplo, o grupo é chamado de custom-bikes
e
o proprietário é dsp.example
. O proprietário do grupo de interesse (neste caso, a DSP) vai ser um
comprador no leilão de anúncios descrito na etapa 4.
A associação ao grupo de interesse é armazenada pelo navegador, no dispositivo do usuário e não é compartilhada com o
fornecedor do navegador ou qualquer outra pessoa.
joinAdInterestGroup()
requer permissão de:
* O site que está sendo visitado
* O proprietário do grupo de interesse
Por exemplo: não pode ser possível que malicious.example
chame
joinAdInterestGroup()
com dsp.example
como proprietário sem a permissão de
dsp.example
.
Permissão do site que está sendo visitado
Mesma origem: por padrão, a permissão é concedida implicitamente para chamadas joinAdInterestGroup()
da
mesma origem do site que está sendo visitado, ou seja, da mesma origem que o frame de nível superior da
página atual. Os sites podem usar uma diretiva join-ad-interest-group
do cabeçalho da política de permissões
da API Protected Audience para desativar chamadas joinAdInterestGroup()
.
Origem cruzada: chamar joinAdInterestGroup()
de origens diferentes da página atual só será bem-sucedido se o site que está sendo visitado tiver uma política de permissões que permita chamadas para joinAdInterestGroup()
a partir de iframes de origem cruzada.
Permissão do proprietário do grupo de interesse
A permissão de proprietário do grupo de interesse é concedida implicitamente chamando joinAdInterestGroup()
em um iframe com a mesma origem do proprietário do grupo. Por exemplo, um iframe dsp.example
pode chamar joinAdInterestGroup()
para grupos de interesse de propriedade de dsp.example
.
A proposta é que joinAdInterestGroup()
possa ser executado em uma página ou iframe no domínio do proprietário ou
ser delegado a outros domínios fornecidos usando uma lista em um URL .well-known
.
Usando navigator.joinAd InterestGroup()
Confira um exemplo de como a API pode ser usada:
const interestGroup = {
owner: 'https://dsp.example',
name: 'custom-bikes',
biddingLogicUrl: ...,
biddingWasmHelperUrl: ...,
dailyUpdateUrl: ...,
trustedBiddingSignalsUrl: ...,
trustedBiddingSignalsKeys: ['key1', 'key2'],
userBiddingSignals: {...},
ads: [bikeAd1, bikeAd2, bikeAd3],
adComponents: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2],
};
navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);
O objeto interestGroup
transmitido para a função não pode ter mais de 50 kiB. Caso contrário, a
chamada vai falhar. O segundo parâmetro especifica a duração do grupo de interesse, limitada a 30 dias. Chamadas sucessivas substituem os valores armazenados anteriormente.
Propriedades do grupo de interesse
Propriedade | Obrigatório | Exemplo | Papel |
---|---|---|---|
owner |
Obrigatório | 'https://dsp.example' |
Origem do proprietário do grupo de interesse. |
name |
Obrigatório | 'custom-bikes' |
Nome do grupo de interesse. |
biddingLogicUrl ** |
Opcional* | 'https://dsp.example/bid/custom-bikes/bid.js' |
URL para execução do JavaScript de lances no worklet. |
biddingWasmHelperUrl ** |
Opcional* | 'https://dsp.example/bid/custom-bikes/bid.wasm' |
URL do código WebAssembly gerado de biddingLogicUrl . |
dailyUpdateUrl ** |
Opcional | 'https://dsp.example/bid/custom-bikes/update' |
URL que retorna JSON para atualizar os atributos do grupo de interesse. Consulte Atualizar o grupo de interesse. |
trustedBiddingSignalsUrl ** |
Opcional | 'https://dsp.example/trusted/bidding-signals' |
URL de base para solicitações de chave-valor para o servidor confiável do bidder. |
trustedBiddingSignalsKeys |
Opcional | ['key1', 'key2' ...] |
Chaves para solicitações para um servidor confiável de chave-valor. |
userBiddingSignals |
Opcional | {...} |
Outros metadados que o proprietário pode usar durante os lances. |
ads |
Opcional* | [bikeAd1, bikeAd2, bikeAd3] |
Anúncios que podem ser renderizados para esse grupo de interesse. |
adComponents |
Opcional | [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2] |
Componentes para anúncios compostos por várias partes. |
* Todas as propriedades são opcionais, exceto owner
e name
. As propriedades biddingLogicUrl
e ads
são opcionais, mas obrigatórias para participar de um leilão. Pode haver casos de uso para criar um grupo de interesse sem essas propriedades. Por exemplo, um proprietário do grupo de interesse pode querer adicionar um navegador a um grupo para uma campanha que ainda não está em exibição, para algum outro uso futuro, ou pode ter ficado temporariamente sem orçamento de publicidade.
** Os URLs biddingLogicUrl
, biddingWasmHelperUrl
, dailyUpdateUrl
e trustedBiddingSignalsUrl
precisam ter a mesma origem do proprietário. Os URLs ads
e adComponents
não têm essa restrição.
Atualizar atributos do grupo de interesse
dailyUpdateUrl
especifica um servidor da Web que retorna JSON definindo as propriedades do grupo de interesse, correspondentes ao objeto do grupo de interesse transmitido para navigator.joinAdInterestGroup()
. Isso fornece um mecanismo para que o proprietário do grupo atualize periodicamente os atributos do grupo de interesse. Na implementação atual,
os seguintes atributos podem ser alterados:
biddingLogicUrl
biddingWasmHelperUrl
trustedBiddingSignalsUrl
trustedBiddingSignalsKeys
ads
priority
Nenhum campo especificado no JSON será substituído. Somente os campos especificados no JSON são atualizados, enquanto chamar navigator.joinAdInterestGroup()
substitui qualquer grupo de interesse atual.
As atualizações são feitas na medida do possível e podem falhar nas seguintes condições: * Tempo limite da solicitação de rede (atualmente 30 segundos). * Outra falha de rede. * Falha na análise de JSON.
As atualizações também poderão ser canceladas se muito tempo contíguo tiver sido atualizado, embora isso não imponha nenhuma limitação de taxa a atualizações canceladas (restantes). As atualizações têm limitação de taxa a no máximo uma por dia. As atualizações que falham devido a erros de rede são repetidas após uma hora, e as atualizações que falham devido à desconexão da Internet são refeitas imediatamente após a reconexão.
Atualizações manuais
As atualizações em grupos de interesse pertencentes à origem do frame atual podem ser acionadas manualmente usando
navigator.updateAdInterestGroups()
. A limitação de taxa impede que atualizações aconteçam com muita frequência:
chamadas repetidas para navigator.updateAdInterestGroups()
não fazem nada até que o período de limite de
taxa (atualmente um dia) tenha passado. O limite de taxa será redefinido se navigator.joinAdInterestGroup()
for chamado novamente para o mesmo grupo de interesse owner
e name
.
Atualizações automáticas
Todos os grupos de interesse carregados em um leilão são atualizados automaticamente após a conclusão do leilão,
sujeito aos mesmos limites de taxa das atualizações manuais. Para cada proprietário com pelo menos um grupo de interesse
que participa de um leilão, é como se navigator.updateAdInterestGroups()
fosse chamado de um
iframe com uma origem correspondente a esse proprietário.
Especificar anúncios para um grupo de interesse
Os objetos ads
e adComponents
incluem um URL para um criativo de anúncio e, opcionalmente, metadados arbitrários que podem ser usados no momento do lance. Exemplo:
{
renderUrl: 'https://cdn.example/.../bikeAd1.html',
metadata: bikeAd1metadata // optional
}
Como os compradores dão lances?
O script em biddingLogicUrl
fornecido pelo proprietário de um grupo de interesse precisa incluir uma função generateBid()
. Quando um vendedor do espaço publicitário chamar navigator.runAdAuction()
, a função generatedBid()
vai ser chamada uma vez para cada um dos grupos de interesse de que o navegador participa, se o proprietário do grupo for convidado a dar lances. Em outras palavras, generateBid()
é chamado uma vez para cada anúncio
candidato. O vendedor fornece uma propriedade decisionLogicUrl
no parâmetro de configuração do leilão transmitido
para navigator.runAdAuction()
. O código nesse URL precisa incluir uma função scoreAd()
, executada para cada bidder no leilão, para pontuar cada um dos lances retornados por generateBid()
.
O script em biddingLogicUrl
fornecido por um comprador de espaço publicitário precisa incluir uma função generateBid()
.
Essa função é chamada uma vez para cada anúncio-candidato. runAdAuction()
verifica individualmente cada anúncio com o lance e os metadados associados e atribui ao anúncio uma
pontuação de desejabilidade numérica.
generateBid(interestGroup, auctionSignals, perBuyerSignals,
trustedBiddingSignals, browserSignals) {
...
return {
ad: adObject,
bid: bidValue,
render: renderUrl,
adComponents: [adComponentRenderUrl1, ...]
};
}
generateBid()
usa os seguintes argumentos:
interestGroup
O objeto transmitido parajoinAdInterestGroup()
pelo comprador do anúncio. O grupo de interesse pode ser atualizado viadailyUpdateUrl
.auctionSignals
Uma propriedade do argumento configuração do leilão transmitida paranavigator.runAdAuction()
pelo vendedor do espaço publicitário. Ela fornece informações sobre o contexto da página (como o tamanho do anúncio e o ID do editor), o tipo de leilão (primeiro preço ou segundo preço) e outros metadados.perBuyerSignals
Assim como acontece comauctionSignals
, uma propriedade do argumento de configuração do leilão transmitida paranavigator.runAdAuction()
pelo vendedor. Isso pode fornecer indicadores contextuais do servidor do comprador sobre a página, se o vendedor for uma SSP que realiza uma chamada de lances em tempo real para os servidores do comprador e encaminhar a resposta ou se a página do editor entrar em contato diretamente com o servidor do comprador. Nesse caso, o comprador pode verificar uma assinatura criptográfica desses sinais dentro de generateBid() como proteção contra adulterações.trustedBiddingSignals
Um objeto cujas chaves são astrustedBiddingSignalsKeys
do grupo de interesse e cujos valores são retornados na solicitaçãotrustedBiddingSignals
.browserSignals
Um objeto criado pelo navegador, que pode incluir informações sobre o contexto da página (como ohostname
da página atual, que o vendedor poderia falsificar) e dados do próprio grupo de interesse (como um registro de quando o grupo venceu um leilão anteriormente, para permitir o limite de frequência no dispositivo).
O objeto browserSignals
tem as seguintes propriedades:
{
topWindowHostname: 'publisher.example',
seller: 'https://ssp.example',
joinCount: 3,
bidCount: 17,
prevWins: [[time1,ad1],[time2,ad2],...],
wasmHelper: ... /* WebAssembly.Module object based on interest group's biddingWasmHelperUrl. */
dataVersion: 1, /* Data-Version value from the buyer's Key/Value service response(s). */
}
Para calcular um valor bid
, o código em generateBid()
pode usar as propriedades dos parâmetros da função. Exemplo:
function generateBid(interestGroup, auctionSignals, perBuyerSignals,
trustedBiddingSignals, browserSignals) {
return {
...
bid: auctionSignals.is_above_the_fold ? perBuyerSignals.atf_value : perBuyerSignals.btf_value,
...
}
}
generateBid()
retorna um objeto com quatro propriedades:
ad
Metadados arbitrários sobre o anúncio, como as informações que o vendedor espera saber sobre esse lance ou criativo de anúncio. O vendedor](/privacy-sandbox/resources/glossary#ssp) usa essas informações no criativo de anúncio de leilão e de decisão. O vendedor usa essas informações na lógica de leilão e decisão.bid
Um lance numérico que vai entrar no leilão. O vendedor precisa estar em posição de comparar lances de diferentes compradores. Portanto, os lances precisam estar em uma unidade escolhida pelo vendedor (por exemplo, "USD por mil"). Se o lance for zero ou negativo, esse grupo de interesse não vai participar do leilão do vendedor. Com esse mecanismo, o comprador pode implementar regras de anunciantes para determinar onde os anúncios dele podem ou não ser exibidos.render
Um URL ou uma lista de URLs que serão usados para renderizar o criativo se o lance vencer o leilão. Consulte Anúncios compostos por várias partes na explicação da API. O valor precisa corresponder aorenderUrl
de um dos anúncios definidos para o grupo de interesse.adComponents
Uma lista opcional de até 20 componentes para anúncios compostos por várias partes, retirada da propriedadeadComponents
do argumento do grupo de interesse transmitido paranavigator.joinAdInterestGroup()
.
Como pedir para um navegador sair de um grupo de interesse
O proprietário do grupo de interesse pode solicitar que um navegador seja removido de um grupo. Em outras palavras, o navegador precisa remover o grupo de interesse da lista daqueles de que ele faz parte.
navigator.leaveAdInterestGroup({
owner: 'https://dsp.example',
name: 'custom-bikes'
});
Se um usuário retornar ao site que solicitou a adição de um grupo de interesse, o proprietário do grupo poderá chamar a função navigator.leaveAdInterestGroup()
para solicitar que o navegador remova o grupo.
O código de um anúncio também pode chamar essa função para o grupo de interesse correspondente.
3. O usuário visita um site que vende espaço publicitário
Mais tarde, o usuário visita um site que vende espaço publicitário, neste exemplo, um site de notícias. O site tem um inventário de anúncios, que é vendido programaticamente usando lances em tempo real.
4. Um leilão de anúncios é realizado no navegador
Seção explicativa: Os vendedores realizam leilões no dispositivo
É provável que o leilão de anúncios seja realizado pela SSP do editor ou pelo próprio editor. O objetivo do leilão é selecionar o anúncio mais adequado para um único espaço de anúncio disponível na página atual. O leilão considera os grupos de interesse de que o navegador faz parte, além dos dados de compradores do espaço publicitário e vendedores dos serviços de chave-valor.
O vendedor do espaço publicitário faz uma solicitação ao navegador do usuário para iniciar um leilão de anúncios chamando
navigator.runAdAuction()
.
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': ...,
...
},
...
]
};
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
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, o lance e os metadados associados, um por vez, e atribui uma pontuação de desejabilidade numérica.
auctionConfig
propriedades
Propriedade | Obrigatório | Exemplo | Papel |
---|---|---|---|
seller |
Obrigatório | 'https://ssp.example' |
Origem do vendedor. |
decisionLogicUrl |
Obrigatório | 'https://ssp.example/auction-decision-logic.js' |
URL para JavaScript do worklet de leilão. |
trustedScoringSignalsUrl |
Opcional | 'https://ssp.example/scoring-signals' |
URL do servidor confiável do vendedor. |
interestGroupBuyers* |
Obrigatório | ['https://dsp.example', 'https://buyer2.example', ...] |
Origens de todos os proprietários de grupos de interesse que pediram lances no leilão. |
auctionSignals |
Opcional | {...} |
Informações do vendedor sobre o contexto da página, o tipo de leilão etc. |
sellerSignals |
Opcional | {...} |
Informações com base nas configurações do editor, como fazer uma solicitação de anúncio contextual etc. |
sellerTimeout |
Opcional | 100 |
Ambiente de execução máximo (ms) do script scoreAd() do vendedor. |
perBuyerSignals |
Opcional | {'https://dsp.example': {...}, |
Indicadores de contexto sobre a página para cada comprador específico a partir do servidor. |
perBuyerTimeouts |
Opcional | 50 |
Ambiente de execução máximo (ms) dos scripts generateBid() de um comprador específico. |
componentAuctions |
Opcional | [{'seller': 'https://www.some-other-ssp.com', |
Outras configurações para leilões de componentes. |
* 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.
** additionalBids
não tem suporte na implementação atual da Protected Audience. Leia a seção Participantes do leilão na explicação da Protected Audience para mais informações.
Como os anúncios são selecionados?
O código em decisionLogicUrl
(uma propriedade do objeto de configuração do leilão transmitido para
runAdAuction()
) precisa incluir uma função scoreAd()
. Isso é executado uma vez para cada anúncio
para determinar se é dele.
scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
...
return desirabilityScoreForThisAd;
}
scoreAd()
aceita os seguintes argumentos:
* adMetadata
Metadados arbitrários fornecidos pelo comprador.
* bid
Um valor de lance numérico.
* auctionConfig
O objeto de configuração do leilão transmitido para navigator.runAdAuction()
.
* trustedScoringSignals
Valores recuperados do servidor confiável do vendedor no momento do leilão,
que representam a opinião dele sobre o anúncio.
* 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 /* Data-Version value 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()
é rejeitar qualquer anúncio que não possa vencer o vencedor contextual.
5. O vendedor e os compradores participantes recebem dados em tempo real do serviço de chave-valor.
Seção explicativa:como buscar dados em tempo real do serviço de chave-valor da API Protected Audience.
Durante um leilão de anúncios, o vendedor do espaço publicitário pode receber dados em tempo real sobre criativos de anúncios específicos
fazendo uma solicitação a um serviço de chave-valor usando a propriedade trustedScoringSignalsUrl
do argumento de
configuração do leilão transmitido para navigator.runAdAuction()
, além das chaves
das propriedades renderUrl
de todas as entradas nos campos ads
e adComponents
de todos
os grupos de interesse do leilão.
Da mesma forma, um comprador de espaço publicitário pode solicitar dados em tempo real do serviço de chave-valor usando as
propriedades trustedBiddingSignalsUrl
e trustedBiddingSignalsKeys
do argumento do grupo de interesse
transmitido para navigator.joinAdInterestGroup()
.
Quando runAdAuction()
é chamado, o navegador faz uma solicitação ao servidor confiável de cada comprador de anúncio. O URL da solicitação pode ter esta aparência:
https://kv-service.example/getvalues?hostname=publisher.example&keys=key1,key2
- O URL de base vem de
trustedBiddingSignalsUrl
. - O
hostname
é fornecido pelo navegador. - O valor
keys
é extraído detrustedBiddingSignalsKeys
.
A resposta a essa solicitação é um objeto JSON que fornece valores para cada uma das chaves.
6. O anúncio vencedor é exibido
Seção explicativa: Os navegadores renderizam o anúncio vencedor
Conforme descrito anteriormente: a promessa retornada por runAdAuction()
é resolvida em um URN,
que é transmitido a um frame isolado para renderização, e o site mostra
o anúncio vencedor.
7. O resultado do leilão é informado
Seção explicativa: Relatórios no nível do evento (por enquanto)
O vendedor informa o resultado
Seção explicativa: Relatórios do vendedor sobre a renderização
O JavaScript do vendedor fornecido em decisionLogicUrl
(que também forneceu scoreAd()
) pode
incluir uma função reportResult()
para informar o resultado do leilão.
reportResult(auctionConfig, browserSignals) {
...
return signalsForWinner;
}
Os argumentos passados para essa função são:
auctionConfig
O objeto de configuração do leilão transmitido paranavigator.runAdAuction()
.browserSignals
Um objeto criado pelo navegador que fornece informações sobre o leilão. Por exemplo:{ 'topWindowHostname': 'publisher.example', 'interestGroupOwner': 'https://dsp.example', 'renderUrl': 'https://cdn.example/url-of-winning-creative.wbn', 'bid:' <bidValue>, 'desirability': <winningAdScore> }
O valor de retorno dessa função é usado como o argumento sellerSignals
para a função reportWin()
do bidder vencedor.
O bidder vencedor gera relatórios sobre o resultado
Seção explicativa: Relatórios do comprador sobre eventos de renderização e de anúncio
O JavaScript do bidder vencedor (que também forneceu generateBid()
) pode incluir uma
função reportWin()
para informar o resultado do leilão.
reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
...
}
Os argumentos passados para essa função são:
auctionSignals
eperBuyerSignals
São os mesmos valores transmitidos paragenerateBid()
do bidder vencedor.sellerSignals
O valor de retorno dereportResult()
, que dá ao vendedor uma oportunidade de transmitir informações ao comprador.browserSignals
Um objeto criado pelo navegador que fornece informações sobre o leilão. Por exemplo:{ 'topWindowHostname': 'publisher.example', 'seller': 'https://ssp.example', 'interestGroupOwner': 'https://dsp.example', 'interestGroupName': 'custom-bikes', 'renderUrl': 'https://cdn.example/winning-creative.wbn', 'bid:' <bidValue> }
Implementação de relatórios temporários de perda/ganho
Existem dois métodos disponíveis temporariamente no Chrome para relatórios de leilão:
forDebuggingOnly.reportAdAuctionLoss()
forDebuggingOnly.reportAdAuctionWin()
Cada um desses métodos usa um único argumento: um URL a ser buscado após a conclusão do leilão. Eles podem
ser chamados várias vezes, em scoreAd()
e generateBid()
, com argumentos de URL diferentes.
O Chrome só envia relatórios de depuração de perda/vitória quando um leilão é concluído. Se um leilão for cancelado (por exemplo, devido a uma nova navegação), nenhum relatório será gerado.
Esses métodos ficam disponíveis por padrão no Chrome se a chrome://flags/#privacy-sandbox-ads-apis
estiver
ativada. No entanto, se você estiver executando o Chrome com sinalizações de linha de comando para ativar a Protected Audience, será necessário
ativar explicitamente os métodos incluindo a sinalização BiddingAndScoringDebugReportingAPI
. Se a sinalização não estiver ativada, os métodos ainda estarão disponíveis, mas não farão nada.
8. Um clique no anúncio é informado
Um clique em um anúncio renderizado em um frame isolado é informado. Para saber mais sobre como isso pode funcionar, consulte Relatórios de anúncios de frames cercados.
O diagrama abaixo descreve cada etapa de um leilão de anúncios da Protected Audience:
Qual é a diferença entre a Protected Audience e o TURTLEDOVE?
A API Protected Audience é o primeiro experimento a ser implementado no Chromium na família de propostas TURTLEDOVE.
A API Protected Audience segue os princípios gerais do TURTLEDOVE. Parte da publicidade on-line tem como base a exibição de um anúncio para uma pessoa potencialmente interessada que já interagiu com o anunciante ou a rede de publicidade. Isso sempre funcionava com o reconhecimento de uma pessoa específica enquanto ela navegava em sites, uma questão fundamental de privacidade na Web.
O objetivo do TURTLEDOVE é oferecer uma nova API para lidar com esse caso de uso e, ao mesmo tempo, oferecer alguns avanços importantes na privacidade:
- O navegador, não o anunciante, contém as informações sobre os interesses do anunciante.
- Os anunciantes podem veicular anúncios com base em um interesse, mas não podem combinar esse interesse com outras informações sobre uma pessoa, em particular, quem ela é ou qual página está visitando.
A API Protected Audience surgiu do TURTLEDOVE e uma coleção de propostas relacionadas para modificações a fim de atender melhor os desenvolvedores que usam a API:
- No SPARROW: a Criteo propôs a adição de um modelo de serviço ("Gatekeeper") executado em um ambiente de execução confiável (TEE). A API Protected Audience inclui um uso mais limitado de TEEs para pesquisa de dados em tempo real e relatórios agregados.
- As propostas TERN da NextRoll e as da Magnite PARRROT descreviam as diferentes funções que compradores e vendedores tinham no leilão no dispositivo. O fluxo de pontuação/lances de anúncios da Protected Audience é baseado nesse trabalho.
- As modificações TURTLEDOVE no nível do produto e com base em resultados da RTB House melhoraram os recursos de personalização e o modelo de anonimato do leilão no dispositivo
- A PARAKEET é a proposta da Microsoft para um serviço de publicidade semelhante ao TURTLEDOVE que depende de um servidor proxy em execução em um TEE entre o navegador e os provedores de adtech para anonimizar solicitações de anúncios e aplicar propriedades de privacidade. A API Protected Audience não adotou esse modelo de proxy. Estamos alinhando as APIs JavaScript para PARAKEET e Protected Audience para apoiar trabalhos futuros com o objetivo de combinar ainda mais os melhores recursos das duas propostas.
A API Protected Audience ainda não impede que a rede de publicidade de um site descubra quais anúncios uma pessoa vê. Esperamos modificar a API para que ela se torne mais particular ao longo do tempo.
Quais configurações de navegador estão disponíveis?
Os usuários podem ajustar a participação nos testes do Sandbox de privacidade no Chrome ativando ou desativando a configuração de nível superior em chrome://settings/adPrivacy. Durante os testes iniciais, as pessoas vão poder usar essa configuração de alto nível do Sandbox de privacidade para desativar a API Protected Audience. O Chrome planeja permitir que os usuários vejam e gerenciem a lista de grupos de interesse a que foram adicionados nos sites que acessaram. Assim como as tecnologias do Sandbox de privacidade, as configurações do usuário podem evoluir com o feedback de usuários, reguladores e outros.
Vamos continuar atualizando as configurações disponíveis no Chrome conforme a proposta da Protected Audience avança, com base em testes e feedback. No futuro, planejamos oferecer configurações mais granulares para gerenciar a API Protected Audience e os dados associados.
Os autores das chamadas de API não podem acessar a associação a grupos quando os usuários navegam no modo de navegação anônima. Além disso, a associação é removida quando os usuários limpam os dados do site.
Interaja e compartilhe feedback
- GitHub: leia a proposta, faça perguntas e acompanhe a discussão.
- W3C: discuta casos de uso do setor no grupo Como melhorar os negócios de publicidade na Web.
- Suporte ao desenvolvedor: faça perguntas e participe de discussões no repositório de suporte para desenvolvedores do Sandbox de privacidade.
- Lista de e-mails do FLEDGE: fledge-api-announce fornece anúncios e atualizações sobre a API.
- Participe das chamadas programadas para a Protected Audience (a cada segunda semana). Todos estão convidados a participar. Para participar, primeiro é necessário participar da WICG. Você pode participar ativamente ou apenas ouvir!
- Use o formulário de feedback do Sandbox de privacidade para a equipe do Chrome fora dos fóruns públicos.
Receber suporte
Para fazer uma pergunta sobre sua implementação, a demonstração ou a documentação: * Abra um novo problema no repositório privacy-sandbox-dev-support. Selecione o modelo de problema para a API Protected Audience. * Informe um problema no repositório de códigos de demonstração no GitHub. * Para perguntas mais gerais sobre como atender aos seus casos de uso com a API, registre um problema no repositório de propostas.
Para bugs e problemas com a implementação da API Protected Audience no Chrome: * Confira os problemas atuais relacionados para a API. * Informe um novo problema em crbug.com/new.
Receber atualizações
- Para receber notificações sobre mudanças de status na API, participe da lista de e-mails para desenvolvedores.
- Para acompanhar de perto todas as discussões em andamento sobre a API, clique no botão Assistir na página da proposta no GitHub. Para fazer isso, você precisa ter ou criar uma conta do GitHub.
- Para receber atualizações gerais sobre o Sandbox de privacidade, inscreva-se no feed RSS [Progresso no Sandbox de privacidade].
Saiba mais
- API Protected Audience: visão geral menos técnica da proposta.
- Demonstração da Protected Audience: tutorial de uma implantação básica da API.
- Vídeo de demonstração da Protected Audience: explica o código de demonstração e mostra como usar o Chrome DevTools para depuração da API Protected Audience.
- Explicação técnica da API Protected Audience
- Como analisar o Sandbox de privacidade
- Intenção de criar o protótipo
Foto de Ray Hennessy no Unsplash.