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.

Atualização:o FLEDGE foi renomeado como API Protected Audience. Para saber mais sobre a mudança do nome, confira a postagem do blog (link em inglês).

Importante:o teste de origem de relevância e medição do Sandbox de privacidade terminou em 20 de setembro de 2023, e as APIs já estão disponíveis para 99% dos usuários do Chrome, e as inscrições para esse teste foram encerradas. Para saber o percentual de usuários com que cada API está ativada, consulte os gráficos de status do Chrome.

Se você nunca usou a API Protected Audience, leia a visão geral da API Protected Audience. para uma explicação de alto nível sobre a API.

Esta postagem foi elaborada para desenvolvedores como uma referência técnica para os iteração recente da API Protected Audience experimental. Uma demonstração de um modelo A implantação da API Protected Audience está disponível, assim como Referências de 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 remarketing e o uso de públicos-alvo personalizados casos, desenvolvidos para que não possa ser usado por terceiros para rastrear o comportamento de navegação em sites. A API permite leilões no dispositivo 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 TURTLEDOVE de propostas.

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:

• Guia de compradores para joinAdInterestGroup() e generateBid().
• Guia do vendedor sobre a API Protected Audience runAdAuction()
• Guia de compradores para reportWin() e guia para vendedores sobre reportResult()
• 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 sobre a implantação básica da API Protected Audience entre anunciantes e editores sites estão disponíveis em protected-audience-demo.web.app/.

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

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

• Ative todas as APIs de privacidade de anúncios em chrome://settings/adPrivacy.
• Defina sinalizações na linha de comando. A lista completa de sinalizações disponíveis da API Protected Audience pode ser encontrada em Pesquisa de código do Chromium.

Renderizar anúncios em iframes ou frames delimitados

Os anúncios podem ser renderizados em um <iframe> ou <fencedframe>, dependendo as flags 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/ganha para depuração.

Observação:esta é uma versão em desenvolvimento da API Protected Audience para testes iniciais. Não deve ser considerada completa ou indicativa da implementação final. Progresso da API Protected Audience e o status são discutidos nas reuniões regulares da WICG. O cronograma do Sandbox de privacidade fornece os cronogramas de implementação da API Protected Audience e de outras APIs do Sandbox de privacidade.

Recursos compatíveis

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

• Grupos de interesse: armazenados pelo navegador, com metadados associados a configurar lances e renderização de anúncios.
• Lances no dispositivo por compradores (DSP ou anunciante): com base no valor grupos de interesse e indicadores do vendedor.
• Seleção de anúncios no dispositivo pelo vendedor (SSP ou editor): com base no lances de leilão e metadados de 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 sobre a API Protected Audience.

Permissões do grupo de interesse

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

No futuro, assim que os proprietários de sites tiverem tempo de atualizar as propriedades de vários domínios, as políticas de permissões do iframe, os é 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 Protected Audience. Isso 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 o teste inicial, uma instância "Traga seu próprio servidor" modelo foi introduzido. A longo prazo, as adtechs vão precisar usar a Serviços de chave-valor da API Protected Audience de código aberto em execução confiável e ambientes de teste.

Consulte a postagem do blog sobre os serviços da API Protected Audience (em inglês). para atualizações do cronograma. Vamos enviar avisos significativos para os desenvolvedores começarem a testes e 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');

Atenção:o suporte a recursos na página atual não garante o uso de uma API. O usuário pode ter desativado a API nas configurações do navegador ou ter outros problemas configurações que impedem o uso da API. Para proteger o usuário não há como verificar isso de maneira programática.

Como a API Protected Audience funciona?

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

Aviso:nem todos os recursos descritos nesta postagem foram implementados (ou totalmente implementada) na versão da API Protected Audience que está sendo testada no Chrome. O artigo Testar com flags de recursos explica quais são os recursos da API Protected Audience no momento. disponíveis para testes no Chrome são executados na linha de comando.

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

Imagine que um usuário visita o site de um fabricante de bicicletas personalizada (o anunciante) neste exemplo) e passa algum tempo na página de um produto de aço artesanal bicicleta. Isso fornece ao fabricante de bicicletas remarketing.

2. O navegador do usuário precisa adicionar um grupo de interesse

A plataforma de demanda (DSP) do anunciante (ou o próprio anunciante) chama navigator.joinAdInterestGroup() para pedir ao navegador para adicionar um grupo de interesse à lista de grupos dos quais o navegador é membro.

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 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 sobre a API Protected Audience: Navegadores registram grupos de interesse.
• Leia o guia da API: compradores e DSPs, saiba como joinAdInterestGroup() e gerar lances.

.

Observação:a origem do contexto de chamada para joinAdInterestGroup() precisa corresponder ao do proprietário do grupo de interesse. O joinAdInterestGroup() precisa ser chamado de um iframe de propriedade do proprietário do grupo de interesse (por exemplo, de uma DSP). Se a origem do documento atual for a mesma do proprietário do grupo de interesse (por exemplo, um site com grupos de interesse próprios), não será necessário usar um iframe.

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 associado ao navegador. de: se o proprietário do grupo de interesse for convidado a fazer um lance.

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ços publicitários. Neste exemplo, um site de notícias site. O site tem um inventário de anúncios que vende de maneira programática com lances em tempo real.

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

O leilão de anúncios provavelmente será realizado pelo fornecedor de fornecimento do editor. (SSP) ou pelo próprio editor. O objetivo do leilão é selecionar o anúncio mais apropriado para um único espaço de anúncio disponível na página atual. A o leilão considera os grupos de interesse de que o navegador faz parte, junto com dados de compradores de espaços publicitários e vendedores dos Serviços de chave-valor.

• Leia a explicação sobre a API Protected Audience: Os vendedores realizam leilões no dispositivo
• Leia o guia de APIs: 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 um anúncio específico criativos 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 no 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 o argumento do grupo de interesse transmitido para navigator.joinAdInterestGroup().

Quando runAdAuction() é chamado, o navegador faz uma solicitação para cada anúncio servidor confiável do comprador. 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 um dos 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 Como abrir o código do serviço de chave-valor da API Protected Audience.

.

Importante:ainda na fase inicial de teste da API Protected Audience, trustedBiddingSignalsUrl precisa ter a mesma origem que o grupo de interesse proprietário. Saiba mais em Traga seu próprio servidor.

6. O anúncio vencedor é exibido

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.

Observação:o objeto FencedFrameConfig é retornado somente quando a flag resolveToConfig está definida como true na configuração do leilão. Se a flag não estiver definida ou for false, será retornado um URN opaco que só pode ser renderizado em um iframe.

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.

• 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 compradores usando as APIs de agregação particular.

Como 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, podem chame a função sendReportTo(). Esse argumento aceita um único argumento: uma string representando um URL buscado após a conclusão do leilão, codificando as informações no nível do evento que serão informadas.

• Leia o guia de API: saiba mais sobre relatórios de vendedores e compradores

8. Um clique no anúncio é registrado

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

---

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 TURTLEDOVE de propostas.

A API Protected Audience segue os princípios gerais de TURTLEDOVE. Parte da publicidade on-line tem é baseado na exibição de um anúncio a uma pessoa potencialmente interessada que que interagiram anteriormente com o anunciante ou com a rede de anúncios. Historicamente, isso tem foi trabalhado pelo anunciante, reconhecendo uma pessoa específica enquanto ela navega sites, uma questão de privacidade na Web atual.

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

• O navegador, não o anunciante, detém as informações sobre o que o o anunciante pensa que tem interesse de uma pessoa.
• Os anunciantes podem veicular anúncios com base em interesses, mas não podem combinar isso interesse por outras informações sobre uma pessoa, em particular, quem ela ou qual página eles estão visitando.

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

• Em 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 geração de relatórios agregados.
• TERN e PARRROT de Magnite propostas descreviam as diferentes funções que compradores e vendedores tinham na leilão no dispositivo. O fluxo de pontuação/lances de anúncios da API Protected Audience é baseado nesse trabalho.
• Com base em resultados da RTB House e no nível do produto As modificações do TURTLEDOVE melhoraram o modelo de anonimato e a personalização do leilão no dispositivo
• PARAKEET é A proposta da Microsoft para um serviço de publicidade do tipo TURTLEDOVE que depende de um proxy em execução em um TEE entre o navegador e os provedores de adtech, para anonimizar solicitações de anúncios e garantir a privacidade; propriedades. A API Protected Audience não adotou esse modelo de proxy. Estamos trazendo as APIs JavaScript para PARAKEET e a API Protected Audience alinhadas, em suporte à trabalho futuro para combinar ainda mais os melhores recursos de ambas as 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ções contextuais por um vendedor ou proponente. Um tópico pode ser incluído as seguintes propriedades:

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

Configuração de navegador disponível

Os usuários podem ajustar a participação em testes do Sandbox de privacidade no Chrome: ativar ou desativar a configuração de nível superior chrome://settings/adPrivacy:

Durante os testes iniciais, as pessoas poderão usar esse recurso de privacidade Configuração do sandbox para desativar a API Protected Audience. O Chrome planeja permitir que os usuários vejam e gerenciar a lista de grupos de interesse aos quais eles foram adicionados em toda a web sites visitados. Assim como acontece com as 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 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 o documentação:

• GitHub: leia explicação, fazer perguntas e acompanhar a discussão.
• Demonstração: informe um problema no repositório de códigos de demonstração.
• Suporte ao desenvolvedor: faça perguntas e participe de discussões no Suporte ao desenvolvedor do Sandbox de privacidade repositório. Selecione o modelo de problema para a API Protected Audience.
• Implementação do Chrome: para bugs ou problemas com a implementação do Chrome a API Protected Audience, é possível conferir os problemas atuais ou informe 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 W3C Melhoria do grupo de locais da empresa de publicidade na Web.

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

Desativar

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

Receber atualizações

• Para notificações de alterações de status da API, participe do lista de e-mails para desenvolvedores.
• Para acompanhar todas as discussões em andamento sobre a API, clique no botão Assistir na página da API em GitHub. Isso requer que você tenha ou crie um padrão.
• Para receber atualizações gerais sobre o Sandbox de privacidade, inscreva-se no feed RSS [Progresso no Sandbox de privacidade].
• Participe das chamadas programadas da API Protected Audience (na segunda semana). Todos estão convidados a participar — para participar, primeiro, participe da WICG. Você possam participar ativamente ou apenas ouvir!