Guia para desenvolvedores sobre leilões de anúncios no dispositivo para veicular públicos-alvo de remarketing e personalizados sem o rastreamento de terceiros entre sites.
Para quem não conhece a API Protected Audience, leia a Visão geral da API Protected Audience para uma explicação geral 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
- 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 projetada para atender casos de uso de remarketing e público-alvo personalizado, de modo 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:
- Guia para compradores sobre
joinAdInterestGroup()egenerateBid(). - Guia do vendedor para a API Protected Audience
runAdAuction() - Guia para compradores de
reportWin()e guia para vendedores dereportResult() - Resolver problemas da API Protected Audience
Também é possível 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 implantação básica da API Protected Audience em sites de anunciantes e editores está disponível em protected-audience-demo.web.app/.
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:
- Ative todas as APIs de privacidade de anúncios em
chrome://settings/adPrivacy. - Defina flags na linha de comando. A lista completa de flags da API Protected Audience está disponível na Pesquisa de código do Chromium.
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
métodos temporários de geração de relatórios de ganhos/perdas de depuração.
Recursos compatíveis
A API Protected Audience com flags de recurso 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 de anúncios e renderização.
- 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 frames restritos: com acesso à rede e geração de registros permitidos para 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 a chamada de
joinAdInterestGroup()
em qualquer lugar da página, até mesmo em 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 iframes de vários domínios, o plano será impedir 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 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úncios em relação às 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 sobre o anúncio para ver a atualização de status.
Para os testes iniciais, foi introduzido um modelo BYOS. 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 sobre os serviços da API Protected Audience para atualizações da linha do tempo. Vamos enviar um aviso substancial para que os desenvolvedores comecem a testar e adotar o recurso antes que essa transição ocorra.
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 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.
Os recursos da API Protected Audience serão adicionados ao longo do tempo conforme o trabalho de implementação avança.
1. Um usuário visita o site de um anunciante
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 de produtos 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
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, o 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 do navegador ou qualquer outra pessoa.
- Leia a explicação da API Protected Audience: Grupos de interesse registrados pelos navegadores.
- Leia o guia da API: compradores e DSPs, aprenda a
joinAdInterestGroup()e gere 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 fazem lances?
generateBid() é chamado para cada grupo de interesse do qual o navegador é membro,
se o proprietário do grupo de interesse for convidado a dar lances.
Leia a documentação para desenvolvedores de 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 de anúncios, neste exemplo, um site de notícias. O site tem inventário de anúncios, que é vendido de forma programática com lances em tempo real.
4. Um leilão de anúncios é executado no navegador
O leilão de anúncios provavelmente será executado pelo provedor de fornecimento (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, junto com os dados dos compradores de espaço publicitário e dos vendedores dos serviços de chave-valor.
- Leia a explicação da API Protected Audience: Os vendedores executam 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
específicos fazendo uma solicitação para o serviço de chave-valor.
O vendedor pode solicitar essas informações durante o
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 para cada servidor
confiável do comprador de anúncios. O URL da solicitação pode ser semelhante a 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 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 chave-valor da API Protected Audience.
- Leia o código aberto do serviço chave/valor da API Protected Audience.
6. O anúncio vencedor é exibido
A promessa retornada por runAdAuction() é resolvida para um objeto de configuração de frame cercado (FencedFrameConfig) quando a flag resolveToConfig é definida como true na configuração do leilão. A configuração do frame é usada por um frame fechado 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 de cerca está disponível a partir da M114. Para mais informações sobre o objeto FencedFrameConfig, consulte o artigo do blog do Chrome.
- Leia o explicativo 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 Private Aggregation.
Como um mecanismo temporário de geração de relatórios de eventos, o código que implementa
reportResult() para o vendedor e reportWin() para o proponente 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, que codifica
informações no nível do evento para serem relatadas.
- Leia o guia da API: saiba mais sobre relatórios de vendedores e compradores.
8. Um clique no anúncio é denunciado
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.
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 na exibição de um anúncio para uma pessoa com interesse em potencial que já interageu com o anunciante ou a rede de publicidade. Historicamente, isso funcionava porque o anunciante reconhecia uma pessoa específica enquanto ela navegava por 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 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 foi criada a partir do TURTLEDOVE e de uma coleção de propostas relacionadas a modificações para atender 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 os diferentes papéis que compradores e vendedores tiveram 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 executado em um TEE entre o navegador e os provedores de adtech para tornar as solicitações de anúncios anônimas e aplicar as propriedades de privacidade. A API Protected Audience não adotou esse modelo de proxy. Estamos alinhando as APIs JavaScript para PARAKEET e a API Protected Audience para trabalhos futuros que combinem 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.
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 proponente. 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 transmitida paranavigator.joinAdInterestGroup()
Configurações disponíveis do navegador
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 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 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.
Os worklets da API Protected Audience são armazenados em cache pelo navegador?
Os recursos que contêm os worklets da API Protected Audience, como os worklets de geração de lances e relatórios do comprador e os worklets de pontuação e relatórios do anunciante, 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 compartilhamento de 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: registre um problema no repositório de código de demonstração.
- Suporte para desenvolvedores: faça perguntas e participe das discussões no repositório de suporte para desenvolvedores do Sandbox de privacidade. Selecione o modelo de problema para a API Protected Audience.
- Implementação do Chrome: para bugs ou problemas com a implementação da API Protected Audience do Chrome, confira os problemas atuais ou crie um novo problema.
Para perguntas mais gerais sobre como atender às suas necessidades com a API Protected Audience, envie um problema no repositório da API. Você também pode discutir casos de uso do setor no Improving Web Advertising Business Group do W3C.
Use o formulário de feedback do Sandbox de privacidade para compartilhar feedback 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
- Para receber notificações sobre mudanças no 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 Watch na página da API no GitHub (link em inglês). Para 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 da API Protected Audience (a cada duas semanas). Todos podem participar. Para participar, primeiro entre para o WICG. Você pode participar ativamente ou apenas ouvir.