API Protected Audience: guia para desenvolvedores

Guia para desenvolvedores sobre leilões de anúncios no dispositivo para veicular remarketing e públicos-alvo personalizados sem rastreamento entre sites de terceiros.

Para quem não conhece a API Protected Audience, leia a visão geral da API Protected Audience para uma explicação de alto nível da API.

Esta postagem foi escrita para desenvolvedores como uma referência técnica da iteração mais recente da API Protected Audience experimental. Uma demonstração de uma implantação básica da API Protected Audience está disponível, assim como referências de API para compradores e vendedores de anúncios.

Status da implementação

Para receber notificações sobre mudanças de status na API, participe da lista de e-mails para desenvolvedores.

O que é a API Protected Audience?

A API Protected Audience é uma API do Sandbox de privacidade criada para veicular 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.

Testar a API Protected Audience

Referência da API disponível

Este documento serve como uma visão geral da API Protected Audience. Se você estiver procurando métodos e parâmetros específicos da API:

Você também pode ler as práticas recomendadas de latência do leilão de anúncios da API Protected Audience.

Demonstração da API Protected Audience

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

Assista esta implantação de ponta a ponta para saber como funciona o código de demonstração da API Protected Audience e como usar o Chrome DevTools para depuração.

Testar esta API

Você pode testar a API Protected Audience para um único usuário no Chrome Beta 101.0.4951.26 e versões mais recentes em computadores:

Renderizar anúncios em iframes ou frames isolados

Os anúncios podem ser renderizados em um <iframe> ou um <fencedframe>, dependendo das flags definidas.

Para usar <fencedframe> na renderização de anúncios:

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

Para usar <iframe> na renderização de 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 perda/ganho de depuração.

Recursos compatíveis

A API Protected Audience por trás das flags de recursos no Chromium é um primeiro experimento para testar os seguintes recursos da API Protected Audience:

  • Grupos de interesse: armazenados pelo navegador, com metadados associados para configurar lances e renderização de anúncios.
  • Lances no dispositivo feitos 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 em lances de leilão e metadados de compradores.
  • Renderização de anúncios em uma versão temporariamente flexível do Fenced Frames: com acesso à rede e geração de registros permitidos para renderização de anúncios.

Leia mais sobre suporte a recursos e restrições na explicação da API Protected Audience.

Permissões de grupo de interesse

A implementação atual da API Protected Audience permite chamar joinAdInterestGroup() de qualquer lugar em uma página, até mesmo de iframes de vários domínios.

No futuro, quando os proprietários de sites tiverem tempo para atualizar as políticas de permissões de iframe entre domínios, o plano é não permitir chamadas de iframes entre domínios.

Serviço de chave-valor

Para oferecer suporte ao leilão de anúncios da API Protected Audience, o navegador pode acessar um serviço de chave/valor para recuperar informações em tempo real que oferecem suporte ao leilão de anúncios da API Protected Audience. Essas informações podem ser usadas de várias maneiras:

  • Os compradores podem querer calcular o orçamento restante em uma campanha publicitária.
  • Os vendedores podem precisar verificar os criativos de anúncio em relação às políticas do editor.

O código do serviço de chave/valor da API Protected Audience já está disponível. Confira a postagem do blog sobre o anúncio para ver a atualização de status.

Para o teste inicial, foi introduzido um modelo Traga seu próprio servidor. A longo prazo, as adtechs precisarão usar os serviços de chave/valor da API Protected Audience de código aberto em execução em ambientes de execução confiáveis.

Consulte a postagem no blog sobre os serviços da API Protected Audience para atualizações de cronograma. Vamos avisar os desenvolvedores com antecedência para que eles comecem a testar e adotar a mudança antes que ela aconteça.

Suporte ao recurso de detecção

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 a API Protected Audience funciona?

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

Os recursos da API Protected Audience serão adicionados ao longo do tempo à medida que o trabalho de implementação avançar.

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

Uma pessoa acessa o site de um fabricante de bicicletas personalizadas em um navegador no laptop.

Imagine que um usuário acessa o site de um fabricante de bicicletas personalizadas (o anunciante neste exemplo) e passa algum tempo na página do produto de uma bicicleta de aço feita à mão. Isso oferece ao fabricante de bicicletas uma oportunidade de remarketing.

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

Um usuário abre um navegador no laptop e visita um site. O código JavaScript para participar de grupos de interesse por anúncios está sendo executado no navegador.

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 de que ele faz parte.

Neste exemplo, o grupo se chama 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 da API Protected Audience. A participação no grupo de interesse é armazenada pelo navegador no dispositivo do usuário e não é compartilhada com o fornecedor ou qualquer outra pessoa.

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?

generateBid() é chamado para cada grupo de interesse de que o navegador faz parte, se o proprietário do grupo for convidado a fazer um lance.

Leia a documentação para desenvolvedores do generatedBid().

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

Uma pessoa acessa um site de notícias em um navegador no laptop. O site tem um espaço de anúncio vazio.

Depois, o usuário visita um site que vende espaço publicitário, neste exemplo, um site de notícias. O site tem inventário de anúncios, que vende de forma programática com lances em tempo real.

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

Uma pessoa acessa um site de notícias em um navegador no laptop. Um leilão de anúncios da API Protected Audience é realizado para escolher um anúncio para o espaço publicitário disponível.

O leilão de anúncios provavelmente será realizado pelo provedor do lado da oferta (SSP) do editor ou pelo próprio editor. O objetivo do leilão é selecionar o anúncio mais adequado para um único espaço disponível na página atual. O leilão considera os grupos de interesse de que o navegador faz parte, além de dados de compradores de espaço de publicidade e vendedores dos serviços de chave-valor.

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

O usuário acessa um site de notícias em um navegador no notebook. Um leilão de anúncios usando a API Protected Audience está em andamento, e um participante está recebendo dados do serviço de chave-valor.

Durante um leilão de anúncios, o vendedor pode solicitar dados em tempo real sobre criativos de anúncios específicos fazendo uma solicitação ao serviço de chave/valor. O vendedor pode solicitar essas informações durante runAdAuction() pela propriedade trustedScoringSignalsUrl, 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.

Um comprador 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 a runAdAuction() é chamada, o navegador faz uma solicitação ao servidor confiável de cada comprador de anúncios. O URL da solicitação pode ser assim:

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

Uma pessoa acessa um site de notícias em um navegador no laptop. Um anúncio de uma bicicleta com 20% de desconto é exibido em um quadro seguro com cerca.

A promessa retornada por runAdAuction() é resolvida em um objeto de configuração de frame isolado (FencedFrameConfig) quando a flag resolveToConfig é definida como true na configuração do leilão. A configuração de frame é usada por um frame isolado para navegar até o anúncio vencedor, mas o URL do anúncio não fica visível para o incorporador do frame.

O objeto de configuração de frame isolado está disponível a partir do M114. Para mais informações sobre o objeto FencedFrameConfig, consulte o artigo do blog do Chrome.

7. O resultado do leilão é informado

O plano de longo prazo é permitir que o navegador informe os resultados do leilão para o vendedor e os compradores usando as APIs Private Aggregation.

Como um mecanismo temporário de relatórios a nível de evento, o código que implementa reportResult() para o vendedor e reportWin() para o bidder vencedor pode chamar a função sendReportTo(). Ele usa um único argumento: uma string que representa um URL buscado após a conclusão do leilão e codifica informações no nível do evento a serem informadas.

8. Um clique no anúncio é informado

Uma pessoa clica em um anúncio de uma bicicleta, incorporado com um frame isolado, em um site de notícias. Os dados do relatório são enviados para vendedores e compradores.

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

Uma visão geral de cada estágio de um leilão de anúncios da API Protected Audience
Este diagrama descreve cada etapa de um leilão da API Protected Audience.

Qual é a diferença entre a API 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 de alto nível do TURTLEDOVE. Algumas publicidades on-line se baseiam em mostrar um anúncio para uma pessoa potencialmente interessada que já interagiu com o anunciante ou a rede de publicidade. Historicamente, isso funcionava quando o anunciante reconhecia uma pessoa específica enquanto ela navegava em sites, o que é uma preocupação central de privacidade na Web atual.

O objetivo do TURTLEDOVE é oferecer uma nova API para resolver esse caso de uso e oferecer alguns avanços importantes em privacidade:

  • O navegador, e não o anunciante, retém 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, principalmente quem ela é ou qual página está visitando.

A API Protected Audience surgiu do TURTLEDOVE e de uma coleção de propostas relacionadas para modificações que atendessem melhor aos 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 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 PARRROT da Magnite descreveram as diferentes funções 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 baseadas em resultados e no nível do produto da RTB House no TURTLEDOVE melhoraram o modelo de anonimato e os recursos de personalização do leilão no dispositivo.
  • O PARAKEET é a proposta da Microsoft para um serviço de anúncios semelhante ao TURTLEDOVE que depende de um servidor proxy executado em um TEE entre o navegador e os provedores de tecnologia de publicidade 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 o trabalho futuro 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 saiba quais anúncios uma pessoa vê. Esperamos modificar a API para que ela se torne mais privada com o tempo.

A API Topics pode ser usada com a API Protected Audience?

Sim. Um tema observado para o usuário atual, fornecido pela API Topics, pode ser usado como informação contextual por um vendedor ou bidder. Um tema pode ser incluído nas seguintes propriedades:

  • auctionSignals, uma propriedade do objeto de configuração do leilão transmitida para navigator.runAdAuction()
  • userBiddingSignals, uma propriedade do objeto de configuração do grupo de interesse transmitido para navigator.joinAdInterestGroup()

Configuração de navegador 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 o teste inicial, as pessoas poderão usar essa configuração de alto nível do Sandbox de privacidade para recusar 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 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 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 de chamadas da 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.

Os worklets da API Protected Audience são armazenados em cache pelo navegador?

Os recursos que contêm os worklets da Protected Audience (geração de lances e relatórios do comprador e pontuação e relatórios de anúncios do vendedor) são armazenados em cache pelo navegador. É possível usar o cabeçalho Cache-Control para controlar o comportamento de armazenamento em cache.

Engajamento e como compartilhar feedback

Receber suporte

Para fazer perguntas e receber suporte com a implementação, a demonstração ou a documentação:

Para perguntas mais gerais sobre como atender às suas necessidades com a API Protected Audience, registre um problema no repositório da API. Você também pode discutir casos de uso do setor no Improving Web Advertising Business Group (link em inglês) da W3C.

Use o formulário de feedback do Sandbox de privacidade para compartilhar feedback de forma particular com a equipe do Chrome fora dos fóruns públicos.

Desativar

Quer desativar a API Protected Audience? Saiba como bloquear o acesso à API Protected Audience, como proprietário do site ou usuário individual.

Receber atualizações