Guia para desenvolvedores da API FLEDGE

Para quem este artigo é destinado?

Esta postagem é uma referência técnica para a iteração atual da API experimental Protected Audience.

O que é a API Protected Audience?

A API Protected Audience é uma proposta do Sandbox de privacidade para atender casos de uso de remarketing e público-alvo personalizado. Ela foi projetada para que não possa ser usada por terceiros para rastrear o comportamento de navegação do usuário entre sites. A API permite leilões no dispositivo pelo navegador para escolher anúncios relevantes para sites que o usuário já visitou.

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:

Ilustração com uma visão geral de cada estágio do ciclo de vida do FLEDGE
Ciclo de vida do FLEDGE.

Como posso testar a API Protected Audience?

Demonstração da API Protected Audience

Um tutorial de implantação básica da Protected Audience em sites de anunciantes e editores está disponível em protected-audience-demo.web.app.

O vídeo de demonstração explica como o código de demonstração funciona e mostra como usar as ferramentas do Chrome DevTools para depuração da API Protected Audience.

Participar 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 com as APIs Protected Audience, Topics e Attribution Reporting.

Para participar, solicite um token de teste de origem.

Depois de se inscrever no teste, você pode testar a API JavaScript Protected Audience em páginas que fornecem um token de teste válido. Por exemplo, para pedir ao navegador para participar de um ou mais grupos de interesse e, em seguida, fazer um leilão de anúncios para selecionar e mostrar um anúncio.

A demonstração da Protected Audience mostra um exemplo básico de implantação completa da Protected Audience.

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 no <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 forma 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 por um proprietário de grupo de interesse, precisa fornecer um token que corresponda à origem.

Detalhes propostos do primeiro teste de origem da Protected Audience fornece mais detalhes sobre as metas do primeiro teste e explica quais recursos são aceitos.

Testar esta API

É possível testar a API Protected Audience para um único usuário no Chrome Beta 101.0.4951.26 e versões mais recentes para computador:

  • Ativando todas as APIs de privacidade de anúncios em chrome://settings/adPrivacy
  • Definindo sinalizações na linha de comando.

Renderizar anúncios em iframes ou frames restritos

Os anúncios podem ser renderizados em um <iframe> ou um <fencedframe>, dependendo de quais flags estão definidas.

Para usar <fencedframe> para renderizar anúncios:

--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,FencedFrames

Para usar <iframe> para renderizar anúncios:

--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,AllowURNsInIframes --disable-features=FencedFrames

Inclua a flag BiddingAndScoringDebugReportingAPI para ativar os métodos temporários de relatórios de ganhos/perdas de depuração.

Executar o Chromium com flags explica como definir flags ao executar o Chrome e outros navegadores baseados no Chromium na linha de comando. A lista completa de flags da 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 Protected Audience está sendo disponibilizada atrás de flags de recurso 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 lances de anúncios e renderização.
  • Lances no dispositivo por compradores (DSP ou anunciante): com base em grupos de interesse e indicadores armazenados do vendedor.
  • Seleção de anúncios no dispositivo pelo vendedor (SSP ou editor): com base nos lances do leilão e nos metadados dos compradores.
  • Renderização de anúncios em uma versão temporariamente relaxada de frames restritos: com acesso à rede e registro permitidos para renderização de anúncios.

A explicação da API fornece 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 a chamada de joinAdInterestGroup() em qualquer lugar da página, mesmo em iframes entre domínios. No futuro, quando os proprietários de sites tiverem tempo para ajustar as políticas de permissões de iframes de vários domínios, o plano é 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 API 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 determina que esse servidor "não realiza geração de registros do evento e não tem 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 GitHub do Sandbox de privacidade. Esse serviço pode ser usado por desenvolvedores do Chrome e do Android. Confira a postagem do blog sobre o anúncio para ver a atualização de status. Saiba mais sobre o serviço chave-valor da Protected Audience na explicação da API e no modelo de confiança.

Para o teste inicial, o modelo "Traga seu próprio servidor" é usado. No longo prazo, as adtechs vão precisar usar os serviços de chave-valor de público-alvo protegido de código aberto em execução em ambientes de execução confiáveis para extrair dados em tempo real.

Para garantir que o ecossistema tenha tempo suficiente para testar, não vamos exigir o uso dos serviços de chave-valor de código aberto ou dos TEEs até algum tempo após a descontinuação dos cookies de terceiros. Vamos enviar um aviso substancial para que os desenvolvedores comecem a testar e adotar o recurso antes que essa transição aconteça.

Detectar suporte a recursos

Antes de usar a API, verifique se ela tem suporte do 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 desativar a API Protected Audience?

É possível bloquear o acesso à API Protected Audience como proprietário do site ou como usuário individual.

Como os sites podem controlar o acesso?

A Protected Audience vai exigir que os sites definam uma política de permissões para que a funcionalidade Protected Audience esteja disponível. Isso ajuda a garantir que terceiros arbitrários não possam usar a API sem o conhecimento do site. No entanto, para facilitar os testes durante o primeiro teste de origem, esse requisito é excluído por padrão. Os sites que quiserem desativar explicitamente a funcionalidade da 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 para adicionar um navegador a grupos de interesse
  • run-ad-auction ativa/desativa a funcionalidade para executar 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=()

Para desativar o uso das APIs em um iframe, adicione o seguinte atributo allow a um elemento iframe:

<iframe src="https://example.com" allow="join-ad-interest-group 'none'; run-ad-auction 'none'"></iframe>

A seção Política de permissões proposta para o primeiro teste de origem da Protected Audience tem 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 dos seguintes mecanismos:

  • Desative os testes do Sandbox de privacidade nas configurações do Chrome: Configurações > Segurança e privacidade > Sandbox de privacidade. Também é possível acessar esse recurso 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 ela busca atender às metas de privacidade.

Depurar worklets da API Protected Audience

No Chrome Canary 98.0.4718.0, é possível depurar worklets da Protected Audience no Chrome DevTools.

A primeira etapa é definir pontos de interrupção usando uma nova categoria no painel Event Listener Breakpoints no painel Sources.

Captura de tela das DevTools no Chrome Canary, destacando o painel &quot;Event Listener Breakpoints&quot; no painel &quot;Sources&quot;. A opção &quot;Início da fase de lances do bidder&quot; está selecionada no worklet de leilão de anúncios.

Quando um ponto de interrupção é acionado, a execução é pausada antes da primeira instrução no nível superior do script do worklet. Você pode usar pontos de interrupção regulares ou comandos de etapa para acessar a função de lance/pontuação/relatório.

Os scripts de worklet em tempo real também vão aparecer no painel "Threads".

Captura de tela das Ferramentas do desenvolvedor no Chrome Canary, destacando o painel &quot;Threads&quot; no painel &quot;Sources&quot;, mostrando o script de worklet atual que foi pausado.

Como alguns worklets podem ser executados em paralelo, várias linhas de execução podem ficar no estado "pausado". Você pode usar a lista de linhas de execução para alternar entre elas e retomar ou inspecionar mais de perto, conforme necessário.

Observar eventos da API Protected Audience

No painel "Application" do Chrome DevTools, é possível observar os eventos de leilão e do grupo de interesse da API Protected Audience.

Se você visitar o site de compras de demonstração da Protected Audience em um navegador com a Protected Audience ativada, as Ferramentas do desenvolvedor vão mostrar informações sobre o evento join.

O painel de aplicativos do DevTools no Chrome Canary, mostrando informações sobre um evento de associação de grupo de interesse da Protected Audience.

Agora, se você visitar o site do editor de demonstração da Protected Audience em um navegador com a Protected Audience ativada, o DevTools vai mostrar informações sobre os eventos bid e win.

Painel de aplicativos do DevTools no Chrome Canary, mostrando informações sobre lances de leilão e eventos de vitória da Protected Audience.

Como a API Protected Audience funciona?

Neste exemplo, um usuário navega no site de um fabricante de bicicletas personalizadas, depois visita um site de notícias e recebe um anúncio de uma nova bicicleta do fabricante.

1. Um usuário visita o site de um anunciante

Ilustração mostrando uma pessoa acessando o site de um fabricante de bicicletas personalizadas em um navegador no laptop.

Imagine que um usuário acesse o site de um fabricante de bicicletas personalizadas (o anunciante neste exemplo) e passe algum tempo na página de produto de uma bicicleta de aço artesanal. Isso oferece ao fabricante de bicicletas uma oportunidade de remarketing.

2. O navegador do usuário é solicitado a adicionar um grupo de interesse

Ilustração mostrando uma pessoa acessando um site em um navegador no laptop. O código JavaScript joinAdInterestGroup() está sendo executado no navegador.

Seção explicativa: grupos de interesse de registro de navegadores

A plataforma de demanda (DSP) do anunciante (ou o próprio anunciante) chama navigator.joinAdInterestGroup() para pedir que o navegador adicione um grupo de interesse à lista de grupos dos quais o navegador faz parte. Neste exemplo, o grupo é chamado custom-bikes e o proprietário é dsp.example. O proprietário do grupo de interesse (neste caso, a DSP) será um comprador no leilão de anúncios descrito na etapa 4. A participação no grupo de interesse é armazenada pelo navegador no dispositivo do usuário e não é compartilhada com o fornecedor do navegador ou com qualquer outra pessoa.

joinAdInterestGroup() precisa da permissão de:

  • O site que está sendo visitado
  • O proprietário do grupo de interesse

Por exemplo, não é 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 do frame de nível superior da página atual. Os sites podem usar uma diretiva join-ad-interest-group do cabeçalho de política de permissões da API Protected Audience para desativar as chamadas joinAdInterestGroup().

Origem cruzada: chamar joinAdInterestGroup() de origens diferentes da página atual só pode ser bem-sucedido se o site visitado tiver definido uma política de permissões que permita chamadas para joinAdInterestGroup() de iframes entre origens.

Permissão do proprietário do grupo de interesse

A permissão do proprietário do grupo de interesse é concedida implicitamente chamando joinAdInterestGroup() de um iframe com a mesma origem do proprietário do grupo de interesse. Por exemplo, um iframe dsp.example pode chamar joinAdInterestGroup() para grupos de interesse 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.

Como usar navigator.joinAdInterestGroup()

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 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 JavaScript de lances executado em worklet.
biddingWasmHelperUrl** Opcional* 'https://dsp.example/bid/custom-bikes/bid.wasm' URL do código do WebAssembly gerado por 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 proponente.
trustedBiddingSignalsKeys Opcional ['key1', 'key2' ...] Chaves para solicitações ao servidor confiável de chave-valor.
userBiddingSignals Opcional {...} Metadados adicionais 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 de várias partes.

* Todas as propriedades são opcionais, exceto owner e name. As propriedades biddingLogicUrl e ads são opcionais, mas necessárias para participar de um leilão. Talvez haja casos de uso para criar um grupo de interesse sem essas propriedades: por exemplo, um proprietário de grupo de interesse pode querer adicionar um navegador a um grupo de interesse para uma campanha que ainda não está em execução ou para algum outro uso futuro, ou pode ter ficado sem orçamento de publicidade temporariamente.

** 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 propriedades do grupo de interesse, correspondendo ao objeto do grupo de interesse transmitido para navigator.joinAdInterestGroup(). Isso oferece um mecanismo para que o proprietário do grupo atualize periodicamente os atributos do grupo de interesse. Na implementação atual, é possível alterar os seguintes atributos:

  • biddingLogicUrl
  • biddingWasmHelperUrl
  • trustedBiddingSignalsUrl
  • trustedBiddingSignalsKeys
  • ads
  • priority

Qualquer campo não especificado no JSON não será substituído. Somente os campos especificados no JSON serão atualizados. Já a chamada navigator.joinAdInterestGroup() substitui qualquer grupo de interesse existente.

As atualizações são de melhor esforço e podem falhar nas seguintes condições:

  • Tempo limite de solicitação de rede (atualmente 30 segundos).
  • Outra falha de rede.
  • Falha na análise JSON.

As atualizações também podem ser canceladas se muito tempo contíguo for gasto atualizando, embora isso não imponha nenhuma limitação de taxa nas atualizações canceladas (restantes). As atualizações são limitadas a 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 repetidas imediatamente na reconexão.

Atualizações manuais

As atualizações dos grupos de interesse pertencentes à origem do frame atual podem ser acionadas manualmente usando navigator.updateAdInterestGroups(). A limitação de taxa impede que as atualizações aconteçam com muita frequência: as chamadas repetidas para navigator.updateAdInterestGroups() não fazem nada até que o período de limitação 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 para um leilão são atualizados automaticamente após a conclusão dele, sujeito aos mesmos limites de taxa das atualizações manuais. Para cada proprietário com pelo menos um grupo de interesse participando de um leilão, é como se navigator.updateAdInterestGroups() fosse chamado de um iframe com 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 fazem lances?

O script em biddingLogicUrl fornecido por um proprietário de grupo de interesse precisa incluir uma função generateBid(). Quando um vendedor de espaço de anúncio chama navigator.runAdAuction(), a função generatedBid() é chamada uma vez para cada um dos grupos de interesse dos quais o navegador é membro, se o proprietário do grupo de interesse for convidado a dar lances. Em outras palavras, generateBid() é chamado uma vez para cada candidato do anúncio. 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(), que é executada para cada proponente no leilão, para avaliar 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, junto com o lance e os metadados associados, e atribui a ele uma pontuação numérica de atratividade.

generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  ...
  return {
    ad: adObject,
    bid: bidValue,
    render: renderUrl,
    adComponents: [adComponentRenderUrl1, ...]
   };
}

generateBid() usa os seguintes argumentos:

  • interestGroup
    O objeto transmitido para joinAdInterestGroup() pelo comprador de anúncios. O grupo de interesse pode ser atualizado por dailyUpdateUrl.

  • auctionSignals
    Uma propriedade do argumento auction config transmitido para navigator.runAdAuction() pelo vendedor do espaço de anúncio. Isso 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 (de primeiro ou segundo preço) e outros metadados.

  • perBuyerSignals
    Como em auctionSignals, uma propriedade do argumento configuração do leilão transmitida para navigator.runAdAuction() pelo vendedor. Isso pode fornecer indicadores contextuais do servidor do comprador sobre a página, se o vendedor for um SSP que realiza uma chamada de lance em tempo real para os servidores do comprador e encaminha a resposta de volta ou se a página do editor entrar em contato diretamente com o servidor do comprador. Nesse caso, o comprador pode querer verificar uma assinatura criptográfica desses indicadores dentro de generateBid() como proteção contra adulteração.

  • trustedBiddingSignals
    Um objeto com chaves trustedBiddingSignalsKeys para o grupo de interesse e valores retornados na solicitação trustedBiddingSignals.

  • browserSignals
    Um objeto criado pelo navegador, que pode incluir informações sobre o contexto da página (como o hostname da página atual, que o vendedor poderia falsificar) e dados para o próprio grupo de interesse (como um registro de quando o grupo ganhou 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 informações que o vendedor espera saber sobre o lance ou o criativo do anúncio. O vendedor](/resources/glossary#ssp) usa essas informações no leilão e no criativo do anúncio 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 condições de comparar lances de diferentes compradores. Portanto, os lances precisam estar em alguma 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 qualquer regra do anunciante para definir onde os anúncios podem ou não aparecer.

  • render
    Um URL ou uma lista de URLs que será usada para renderizar o criativo se esse lance vencer o leilão. Consulte Anúncios compostos de várias partes no explicador da API. O valor precisa corresponder ao renderUrl de um dos anúncios definidos para o grupo de interesse.

  • adComponents
    Uma lista opcional de até 20 componentes para anúncios compostos de várias partes, extraídos da propriedade adComponents do argumento do grupo de interesse transmitido para navigator.joinAdInterestGroup().

Pedir para um navegador sair de um grupo de interesse

O proprietário do grupo de interesse pode solicitar a remoção de um navegador. Em outras palavras, o navegador precisa remover o grupo de interesse da lista de grupos de que ele faz parte.

navigator.leaveAdInterestGroup({
  owner: 'https://dsp.example',
  name: 'custom-bikes'
});

Se um usuário retornar ao site que pediu ao navegador para adicionar um grupo de interesse, o proprietário do grupo poderá chamar a função navigator.leaveAdInterestGroup() para solicitar que o navegador remova o grupo de interesse. O código de um anúncio também pode chamar essa função para o grupo de interesse.

3. O usuário visita um site que vende espaço publicitário

Ilustração mostrando uma pessoa acessando um site de notícias em um navegador no laptop. O site tem um espaço de anúncio vazio.

Mais tarde, o usuário visita um site que vende espaço para anúncios, neste exemplo, um site de notícias. O site tem inventário de anúncios, que é vendido de forma programática usando lances em tempo real.

4. Um leilão de anúncios é executado no navegador

Ilustração mostrando uma pessoa acessando um site de notícias em um navegador no laptop. Um leilão de anúncios usando a API Protected Audience está acontecendo.

Seção explicativa:os vendedores executam leilões no dispositivo

O leilão de anúncios provavelmente será executado pelo 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 dos quais o navegador faz parte, além de dados de compradores de espaço publicitário e dos vendedores dos serviços de chave-valor.

O vendedor de 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 para um URN (urn:uuid:<something>) que representa o resultado do leilão de anúncios. Isso só pode ser decodificado pelo navegador quando transmitido para um frame fechado para renderização: a página do editor não pode inspecionar o anúncio vencedor.

O script decisionLogicUrl considera cada anúncio individualmente, junto com o lance e os metadados associados, um de cada vez, e atribui uma pontuação numérica de atratividade.

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 do 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 foram solicitados a dar 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, na solicitação de anúncio contextual etc.
sellerTimeout Opcional 100 Tempo de execução máximo (ms) do script scoreAd() do vendedor.
perBuyerSignals Opcional {'https://dsp.example': {...},
  'https://another-buyer.example': {...},
...}		 Indicadores contextuais sobre a página para cada comprador específico, do servidor.
perBuyerTimeouts Opcional 50 Tempo de execução máximo (ms) dos scripts generateBid() de um comprador específico.
componentAuctions Opcional [{'seller': 'https://www.some-other-ssp.com',
  'decisionLogicUrl': ..., ...},
  ...]		 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 outros critérios, além da inclusão do proprietário do grupo de interesse. Por exemplo, o vendedor pode analisar os criativos do anúncio para confirmar a conformidade com as políticas.

** additionalBids não é compatível com a implementação atual da Protected Audience. Leia a seção Participantes do leilão no explicador da audiência protegida 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 transmitida para runAdAuction()) precisa incluir uma função scoreAd(). Isso é executado uma vez para cada anúncio para determinar a atratividade dele.

scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
  ...
  return desirabilityScoreForThisAd;
}

scoreAd() usa 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 foi transmitido para navigator.runAdAuction().
  • trustedScoringSignals
    Valores recuperados no leilão do servidor confiável do vendedor, representando a opinião do vendedor sobre o anúncio.
  • browserSignals
    Um objeto construído 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 de anúncio disponível. Parte da lógica da scoreAd() é rejeitar qualquer anúncio que não vença o vencedor contextual.

5. O vendedor e os compradores participantes recebem dados em tempo real do serviço de chave-valor.

Ilustração mostrando uma pessoa acessando um site de notícias em um navegador no laptop. Um leilão de anúncios usando a API Protected Audience está acontecendo, e um participante está recebendo dados 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 de espaço publicitário pode receber dados em tempo real sobre criativos de anúncios específicos fazendo uma solicitação para um serviço de chave-valor usando a propriedade trustedScoringSignalsUrl do argumento configuração do leilão transmitido para navigator.runAdAuction(), junto com as chaves das propriedades renderUrl de todas as entradas nos campos ads e adComponents de todos os grupos de interesse no leilão.

Da mesma forma, um comprador de espaço publicitário pode solicitar dados em tempo real do serviço 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 para o servidor confiável de cada comprador de anúncios. O URL da solicitação pode ser parecido com este:

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 de trustedBiddingSignalsKeys.

A resposta a essa solicitação é um objeto JSON que fornece valores para cada uma das chaves.

6. O anúncio vencedor é exibido

Ilustração mostrando uma pessoa acessando um site de notícias em um navegador no laptop. Um anúncio de uma bicicleta (com 20% de desconto) é exibido com um cadeado acima para mostrar que o anúncio é mostrado em um frame cercado.

Seção explicativa:os navegadores renderizam o anúncio vencedor

Conforme descrito anteriormente, a promessa retornada por runAdAuction() é resolvida para um URN, que é transmitido para um frame limitado para renderização, e o site exibe 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 no Render

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 transmitidos para essa função são:

  • auctionConfig
    O objeto de configuração do leilão foi transmitido para navigator.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 proponente vencedor.

O licitante vencedor informa o resultado

Seção explicativa:Relatórios do comprador sobre eventos de renderização e de anúncios

O JavaScript do licitante 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 transmitidos para essa função são:

  • auctionSignals e perBuyerSignals
    Os mesmos valores transmitidos para generateBid() para o proponente vencedor.
  • sellerSignals
    O valor de retorno de reportResult(), que dá ao vendedor a 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 temporária de relatórios de perda/ganho

Há dois métodos disponíveis temporariamente no Chrome para gerar relatórios de leilão:

  • forDebuggingOnly.reportAdAuctionLoss()
  • forDebuggingOnly.reportAdAuctionWin()

Cada um desses métodos recebe um único argumento: um URL a ser buscado após o término do leilão. Eles podem ser chamados várias vezes, em scoreAd() e generateBid(), com diferentes argumentos de URL.

O Chrome só envia relatórios de vitória/derrota de depuração 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 estão disponíveis por padrão no Chrome. Para testar os métodos, ative todas as APIs de privacidade de anúncios em chrome://settings/adPrivacy. Se você estiver executando o Chrome com flags de linha de comando para ativar a API Protected Audience, será necessário ativar explicitamente os métodos incluindo a flag BiddingAndScoringDebugReportingAPI. Se a flag não estiver ativada, os métodos ainda estarão disponíveis, mas não farão nada.

8. Um clique no anúncio é denunciado

Ilustração mostrando uma pessoa clicando em um anúncio de uma bicicleta, dentro de um quadro cercado, em um site de notícias, com dados de relatório sendo enviados para o vendedor e os compradores.

Um clique em um anúncio renderizado em um frame restrito é informado. Para saber mais sobre como isso funciona, consulte Relatórios de anúncios de molduras delimitadas.


O diagrama abaixo descreve cada etapa de um leilão de anúncios da Protected Audience:

Ilustração com uma visão geral de cada etapa de um leilão de anúncios da API Protected Audience


Qual é a diferença entre a API Protected Audience e a TURTLEDOVE?

A Protected Audience é o primeiro experimento a ser implementado no Chromium na família de propostas TURTLEDOVE.

A Protected Audience segue os princípios gerais do TURTLEDOVE. Algumas publicidades on-line são baseadas na exibição de um anúncio para uma pessoa com interesse em potencial que já interagiu com o anunciante ou a rede de publicidade. Historicamente, isso funcionou porque o anunciante reconhecia uma pessoa específica enquanto ela navegava pelos sites, uma preocupação fundamental de privacidade na Web atual.

O esforço TURTLEDOVE tem como objetivo oferecer uma nova API para lidar com esse caso de uso e oferecer alguns avanços importantes em termos de privacidade:

  • O navegador, e não o anunciante, armazena as informações sobre o que o anunciante acha que uma pessoa tem interesse.
  • 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 ela está visitando.

A API Protected Audience surgiu da TURTLEDOVE e de uma coleção de propostas relacionadas a modificações para atender melhor os desenvolvedores que usariam 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 Protected Audience inclui um uso mais limitado de TEEs para pesquisa de dados em tempo real e relatórios agregados.
  • As propostas da TERN da NextRoll e da PARRROT da Magnite descreveram os diferentes papéis que compradores e vendedores tinham no leilão no dispositivo. O fluxo de lances/pontuação de anúncios da API Protected Audience é baseado nesse trabalho.
  • As modificações TURTLEDOVE baseadas em resultados e no nível do produto da RTB House melhoraram o modelo de anonimato e os recursos de personalização do leilão no dispositivo.
  • 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 Protected Audience não adotou esse modelo de proxy. Estamos alinhando as APIs JavaScript para PARAKEET e Protected Audience para apoiar o trabalho futuro e 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 saiba quais anúncios uma pessoa vê. Esperamos modificar a API para que ela se torne mais privada ao longo do tempo.

Qual configuração de navegador está disponível?

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 poderão 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 acessem e gerenciem a lista de grupos de interesse a que foram adicionados nos sites que visitaram. 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 à medida que a proposta da Protected Audience avança, com base em testes e feedback. No futuro, planejamos oferecer configurações mais detalhadas para gerenciar a API Protected Audience e os dados associados.

Os autores de chamadas de API não podem acessar a associação a grupos quando os usuários navegam no modo de navegação anônima, e a associação é removida quando os usuários limpam os dados do site.



Engajamento e compartilhamento de feedback

Receber suporte

Para fazer uma pergunta sobre sua implementação, a demonstração ou a documentação:

Para bugs e problemas com a implementação da API Protected Audience no Chrome: * Confira os problemas atuais informados para a API. * Apresente um novo problema em crbug.com/new.

Receber atualizações

Saiba mais

Foto de Ray Hennessy no Unsplash.