API Protected Audience: guia para desenvolvedores

Guia do desenvolvedor para leilões de anúncios no dispositivo com o objetivo de veicular remarketing e públicos-alvo personalizados sem rastreamento de terceiros entre sites.

Para iniciantes, 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 para a 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 as referências da 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 projetada para atender a casos de uso de remarketing e público-alvo personalizado, 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 já visitou.

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

Teste a API Protected Audience

Referência da API disponível

Este documento serve como uma visão geral da API Protected Audience. Se você está procurando métodos e parâmetros de API específicos, faça o seguinte:

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

Demonstração da API Protected Audience

Confira um tutorial sobre a implantação básica da API Protected Audience nos sites de anunciantes e editores em Protecting-audience-demo.web.app/ (em inglês).

Assista a esta implantação completa 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

É 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:

Renderizar anúncios em iframes ou frames delimitados

Os anúncios podem ser renderizados em <iframe> ou <fencedframe>, dependendo de quais sinalizações estão 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 sinalização BiddingAndScoringDebugReportingAPI para ativar métodos temporários de geração de relatórios de perda/vitória de depuração.

Recursos compatíveis

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

  • Grupos de interesse: armazenados pelo navegador, com metadados associados para configurar a renderização e os lances de anúncios.
  • Lances no dispositivo por compradores (DSP ou anunciante): são baseados 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 de leilão e nos metadados dos compradores.
  • Renderização de anúncios em uma versão temporariamente relaxada de Fenced Frames: com acesso à rede e geração de registros permitidos para a renderização de anúncios.

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

Permissões do grupo de interesse

O padrão para a implementação atual da API Protected Audience é permitir chamar joinAdInterestGroup() de qualquer lugar da página, mesmo de iframes de vários domínios.

No futuro, quando os proprietários de sites tiverem tempo de atualizar as políticas de permissões de iframe entre domínios, o plano será proibir 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 compatíveis com o leilão de anúncios da API. Essas informações podem ser usadas de várias maneiras:

  • Talvez os compradores queiram calcular o orçamento restante em uma campanha publicitária.
  • Pode ser necessário que os vendedores verifiquem se os criativos dos anúncios estão de acordo com as políticas do editor.

O código de serviço de chave-valor da API Protected Audience já está disponível. Confira o anúncio no blog (em inglês) para saber mais sobre a atualização do status.

Para testes iniciais, foi introduzido um modelo "Traga seu próprio servidor". A longo prazo, as adtechs vão precisar 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 do blog de serviços da API Protected Audience para conferir as atualizações da linha do tempo. Vamos enviar avisos significativos para os desenvolvedores começarem os testes e a adoção antes dessa transição.

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

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

Os recursos da API Protected Audience vão ser adicionados ao longo do tempo conforme o progresso da implementação.

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

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

Imagine que um usuário visita 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 fornece ao fabricante de bicicletas uma oportunidade de remarketing.

2. O navegador do usuário precisa 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 de 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 o navegador faz parte.

Neste exemplo, o grupo é 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 associação ao 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.

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?

generateBid() é chamado para cada grupo de interesse de que o navegador participa, se o proprietário do grupo de interesse for convidado a dar lances.

Leia a documentação do desenvolvedor 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.

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 com lances em tempo real.

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

Uma pessoa visualiza 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 disponível.

É provável que o leilão de anúncios seja realizado pelo provedor de fornecimento (SSP, na sigla em inglês) do editor ou pelo próprio editor. O objetivo do leilão é selecionar o anúncio mais apropriado 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, assim como os dados dos compradores de espaço publicitário e dos 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 visualiza um site de notícias em um navegador no laptop. Está ocorrendo um leilão de anúncios usando a API Protected Audience e um participante 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 runAdAuction() é chamado, o navegador faz uma solicitação ao servidor confiável de cada comprador de anúncios. 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 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 visualiza um site de notícias em um navegador no laptop. Um anúncio com 20% de desconto em uma bicicleta é exibido em uma estrutura cercada por segurança.

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

O objeto de configuração de frame isolado está disponível a partir da versão M114. Para saber mais 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 de agregação privada.

Como um mecanismo temporário de relatórios no nível do 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, codificando as informações de evento a serem informadas.

8. Um clique no anúncio é registrado

Uma pessoa clica em um anúncio de uma bicicleta, incorporado a um quadro cercado, em um site de notícias. Os dados do relatório são enviados ao vendedor e aos compradores.

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 isolados.

Visão geral de cada etapa do 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 gerais de TURTLEDOVE. Parte da publicidade on-line é baseada na exibição de um anúncio a uma pessoa potencialmente interessada que já interagiu com o anunciante ou a rede de publicidade. Historicamente, esse método faz com que o anunciante reconheça uma pessoa específica enquanto ela navega em sites, uma questão importante de privacidade na Web atual.

O objetivo da iniciativa TURTLEDOVE é oferecer uma nova API para lidar com esse caso de uso, além de oferecer alguns avanços importantes na privacidade:

  • O navegador, não o anunciante, contém as informações sobre o que o anunciante acha que uma pessoa está interessada.
  • Os anunciantes podem veicular anúncios com base em interesses, mas não podem combinar esse interesse com outras informações sobre uma pessoa, especificamente, quem eles são ou qual página estão visitando.

A API Protected Audience surgiu com o TURTLEDOVE e uma coleção de propostas relacionadas de modificações para atender melhor os desenvolvedores que usam a API:

  • No SPARROW: a Criteo propôs a adição de um modelo de serviço ("Gatekeeper") em execução 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 geração de relatórios agregados.
  • As propostas TERN e PARRROT do NextRoll (link em inglês) 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 API Protected Audience é baseado nesse trabalho.
  • As modificações TURTLEDOVE com base 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
  • A PARAKEET é a proposta da Microsoft de um serviço de publicidade semelhante ao TURTLEDOVE que depende de um servidor proxy executado 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 poder 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ê. Com o tempo, esperamos modificar a API para que ela se torne mais particular.

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 tópico pode ser incluído nas seguintes propriedades:

  • auctionSignals, uma propriedade do objeto de configuração do leilão transmitido para o 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 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 vejam e gerenciem a lista de grupos de interesse a que foram adicionados nos sites que eles visitaram. Assim como acontece com as próprias tecnologias do Sandbox de privacidade, as configurações do usuário podem evoluir com o feedback de usuários, reguladores e outros.

Continuaremos 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 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, 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 API Protected Audience, ou seja, os worklets de geração de lances e relatórios do comprador e os de pontuação de anúncios e relatórios do vendedor, são armazenados em cache pelo navegador. Use o cabeçalho Cache-Control para controlar o comportamento do armazenamento em cache.

Interaja e compartilhe feedback

Receber suporte

Para fazer perguntas e receber suporte sobre 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 Grupo de negócios de Publicidade da Web (em inglês) do W3C.

Use o formulário de feedback do Sandbox de privacidade para compartilhar sua opinião de maneira 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