Guia do desenvolvedor para leilões de anúncios no dispositivo para veicular públicos-alvo personalizados e de remarketing sem rastreamento de terceiros entre sites.
Para quem ainda não conhece a API Protected Audience, leia a Visão geral da API Protected Audience (em inglês) para uma explicação de alto nível.
Esta postagem foi escrita para desenvolvedores como uma referência técnica para a iteração mais recente da API Protected Audience experimental. Está disponível uma demonstração de uma implantação básica da API Protected Audience, assim como as referências da API para compradores e vendedores de anúncios.
Status da implementação
- A proposta da API Protected Audience vai ser disponibilizada para todos os usuários. Faça perguntas e acompanhe a discussão.
- O status da API Protected Audience para recursos pendentes detalha mudanças e melhorias na API e nos recursos da API Protected Audience.
- Status de piscar
- Status da plataforma do Chrome da API Protected Audience: específico para a API Protected Audience no Chrome.
- Status da plataforma do Chrome na API Ads: um conjunto de APIs para facilitar a publicidade: API Protected Audience, Topics, Fenced Frames e Attribution Reporting.
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 atender a casos de uso de remarketing e de públicos-alvo personalizados, projetada para que não seja 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.
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ê estiver procurando métodos e parâmetros de API específicos:
- Guia do comprador para
joinAdInterestGroup()egenerateBid(). - Guia do vendedor da API Protected Audience
runAdAuction() - Guia do comprador para
reportWin()e guia do vendedor parareportResult() - Resolver problemas da API Protected Audience
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
Um tutorial da implantação básica da API Protected Audience nos sites de anunciantes e editores está disponível em Protect-audience-demo.web.app/.
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. - Defina sinalizações na linha de comando. A lista completa de sinalizações da API Protected Audience disponíveis pode ser encontrada na Pesquisa de código do Chromium.
Renderizar anúncios em iframes ou frames delimitados
Os anúncios podem ser renderizados em uma <iframe> ou em um <fencedframe>, dependendo de quais sinalizações são 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.
Recursos compatíveis
A API Protected Audience atrás de 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 a renderização e os lances de anúncios.
- Lances no dispositivo por compradores (DSP ou anunciante): com base em grupos de interesse armazenados e indicadores do vendedor.
- Seleção de anúncios no dispositivo pelo vendedor (SSP ou editor): com base em lances de leilão e metadados dos 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 renderização de anúncios.
Saiba mais sobre suporte e restrições de recursos 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 a chamada de
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 atualizar as políticas de permissões de iframe entre domínios, o plano será proibir chamadas de iframes de vários 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 extrair informações em tempo real com suporte ao leilão de anúncios dessa API. Essas informações podem ser usadas de várias maneiras:
- Talvez os compradores queiram calcular o orçamento restante de uma campanha publicitária.
- Pode ser que os vendedores tenham que verificar se os criativos dos anúncios estão em conformidade com as políticas do editor.
O código de serviço de chave-valor da API Protected Audience já está disponível. Confira a postagem do blog com o anúncio para saber a atualização de status.
Para os 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 que são executados em ambientes de execução confiáveis.
Consulte a postagem do blog sobre serviços da API Protected Audience (em inglês) para conferir as atualizações do cronograma. Enviaremos um aviso significativo para que os desenvolvedores comecem a testar e 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 a API Protected Audience funciona?
Neste exemplo, um usuário visita o site de uma fabricante de bicicletas personalizada, depois visita um site de notícias e vê um anúncio de uma nova bicicleta.
Os recursos da API Protected Audience vão ser adicionados ao longo do tempo à medida que o trabalho na implementação avançar.
1. Um usuário visita o site de um anunciante.
Imagine que um usuário visita o site de uma fabricante de bicicletas personalizada (o anunciante), neste exemplo, e passa algum tempo na página do produto de uma bicicleta de aço artesanal. Assim, o fabricante de bicicletas tem uma oportunidade de remarketing.
2. É solicitado que o navegador do usuário adicione um grupo de interesse
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 (nesse caso, a DSP) vai 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 nem com qualquer outra pessoa.
- Leia a explicação da API Protected Audience: Grupos de interesse de registro de navegadores (em inglês).
- Leia o guia da API: compradores e DSPs, aprendam a
joinAdInterestGroup()e gerar lances.
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() será chamado para cada grupo de interesse de que o navegador participa, se o proprietário do grupo 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
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
É 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 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 dos compradores do espaço publicitário e dos vendedores dos serviços de chave-valor.
- Leia a explicação da API Protected Audience: Vendedores realizam leilões no dispositivo
- Leia o guia da API: os vendedores podem saber mais sobre
runAdAuction()e as práticas recomendadas de latência do leilão de anúncios.
5. O vendedor e os compradores participantes solicitam dados em tempo real 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,
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 detrustedBiddingSignalsKeys.
A resposta a essa solicitação é um objeto JSON que fornece valores para cada uma das chaves.
- Leia a explicação da API Protected Audience: Como buscar dados em tempo real do serviço de chave-valor da API Protected Audience.
- Leia abrir o código do serviço de chave-valor da API Protected Audience.
6. O anúncio vencedor é exibido
A promessa retornada pelo runAdAuction() é resolvida em um objeto de configuração de frame isolado (FencedFrameConfig) quando a flag resolveToConfig está definida como true na configuração do leilão. A configuração é 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 de frames.
O objeto de configuração de frame isolado está disponível na versão M114 e mais recentes. Para saber mais sobre o objeto FencedFrameConfig, consulte o artigo do blog do Chrome.
- Leia a explicação da API Protected Audience: os navegadores renderizam o anúncio vencedor
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 geração 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(). Isso usa um único argumento: uma string
que representa um URL buscado após a conclusão do leilão e que codifica
as informações no nível do evento a serem informadas.
- Leia o guia da API: saiba mais sobre relatórios de vendedores e compradores
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.
Qual é a diferença entre a API Protected Audience e o TURTLEDOVE?
A API Protected Audience é o primeiro experimento a ser implementado no Chromium dentro da 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. Historicamente, para isso, o anunciante sempre consegue reconhecer uma pessoa específica enquanto ela navega nos sites, uma questão central de privacidade na Web.
O esforço do TURTLEDOVE consiste em oferecer uma nova API para lidar com esse caso de uso enquanto oferece alguns avanços importantes de privacidade:
- O navegador, não o anunciante, tem 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 (especificamente, quem ela é ou qual página está visitando).
A API Protected Audience surgiu do TURTLEDOVE e de 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") 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 e PARRROT da NextRoll descreviam os diferentes papéis que compradores e vendedores tinham no leilão no dispositivo. O fluxo de lances/pontuações de anúncios da API Protected Audience se baseia nesse trabalho.
- As modificações TURTLEDOVE com base em resultados e no nível do produto do RTB House melhoraram o modelo de anonimização e os recursos de personalização 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 dar suporte a trabalhos futuros para 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.
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ções contextuais 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 transmitida paranavigator.runAdAuction()userBiddingSignals, uma propriedade do objeto de configuração do grupo de interesse transmitido paranavigator.joinAdInterestGroup().
Configuração do 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 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 visitados. Assim como 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.
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 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. Ela é removida quando os usuários limpam os dados do site.
Os worklets da Protected Audience são armazenados em cache pelo navegador?
Os recursos que contêm os worklets de geração de lances e de relatórios do comprador, bem como os de pontuação de anúncio e relatório do vendedor, são armazenados em cache pelo navegador. Você pode usar o cabeçalho Cache-Control para controlar o comportamento de armazenamento em cache.
Interaja e compartilhe feedback
Receber suporte
Para fazer perguntas e receber suporte com a implementação, a demonstração ou a documentação:
- GitHub: leia a explicação, faça perguntas e acompanhe a discussão.
- Demonstração: informe um problema no repositório do código de demonstração.
- Suporte para desenvolvedores: faça perguntas e participe de discussões no repositório de suporte para desenvolvedores do Sandbox de privacidade. Selecione o modelo de problema da API Protected Audience.
- Implementação do Chrome: para bugs ou problemas com a implementação da API Protected Audience no Chrome, é possível conferir os problemas atuais ou informar um novo problema.
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 Developing Web Advertising Business Group (em inglês) do W3C.
Use o formulário de feedback do Sandbox de privacidade para a equipe do Chrome fora dos fóruns públicos.
Desativar
Quer desativar a API Protected Audience? Aprenda a bloquear o acesso à API Protected Audience como proprietário do site ou usuário individual.
Receber atualizações
- Para receber notificações de alterações de status da 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 API 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 [Progress in the Privacy Sandbox].
- Participe das chamadas programadas para a API Protected Audience (a cada segunda semana). Todos estão convidados a participar. Para participar, primeiro certifique-se de participar do WICG. Você pode participar ativamente ou apenas ouvir!