Esta página foi traduzida pela API Cloud Translation.

Definir dados do público-alvo

Aprenda a definir um público-alvo criando um grupo de interesse usando a API Protected Audience. Leia o guia para desenvolvedores com o ciclo de vida completo da API Protected Audience e confira a explicação sobre ela para conferir uma proposta detalhada de como os navegadores registram grupos de interesse.

Não é um desenvolvedor? Consulte a visão geral da API Protected Audience.

Grupos de interesse da API Protected Audience

Um grupo de interesse da API Protected Audience representa um grupo de pessoas com um interesse comum, correspondente a uma lista de remarketing. Cada grupo de interesse da API Protected Audience tem um proprietário.

Os proprietários do grupo de interesse agem como compradores 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.

Funções da API

`joinAdInterestGroup()`

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 associação do navegador.

A origem do contexto de chamada de joinAdInterestGroup() precisa corresponder à origem do proprietário do grupo de interesse. Portanto, joinAdInterestGroup() precisará ser chamado de um iframe (por exemplo, de um DSP), a menos que a origem do proprietário do grupo de interesse corresponda à do documento atual (por exemplo, um site com os próprios grupos de interesse).

O app joinAdInterestGroup() precisa da permissão de:

O site que está sendo visitado
O proprietário do grupo de interesse

Isso significa que malicious.example não pode chamar joinAdInterestGroup() para um grupo de interesse de propriedade de dsp.example.com sem a permissão dsp.example.com.

Permissão do site visitado

A permissão pode ser concedida da mesma origem ou origem cruzada. Por padrão, a permissão é concedida para chamadas joinAdInterestGroup() da mesma origem do site visitado, ou seja, da mesma origem do frame de nível superior da página atual.

Exemplo de uso

Este é um exemplo de como definir um grupo de interesse e solicitar que o navegador participe do grupo.

const interestGroup = {
  owner: 'https://dsp.example',
  name: 'custom-bikes',
  biddingLogicUrl: ...,
  biddingWasmHelperUrl: ...,
  updateUrl: ...,
  trustedBiddingSignalsUrl: ...,
  trustedBiddingSignalsKeys: ['key1', 'key2'],
  userBiddingSignals: {...},
  ads: [bikeAd1, bikeAd2, bikeAd3],
  adComponents: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2],
};

navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);

O objeto interestGroup transmitido para a função não pode ter mais de 50 kiB de tamanho. Caso contrário, a chamada falhará. O segundo parâmetro especifica a duração do grupo de interesse, com um limite de 30 dias. Chamadas sucessivas substituem os valores armazenados anteriormente.

Importante: todos os URLs usados como parâmetros para os métodos da API Protected Audience precisam ser de origens seguras. Todos os recursos precisam ser veiculados por URLs HTTPS. O módulo Como usar HTTPS para desenvolvimento local explica como fazer isso ao executar a API Protected Audience localmente. Além disso, biddingLogicUrl, decisionLogicUrl e trustedBiddingSignals exigem um cabeçalho de resposta HTTP X-Allow-FLEDGE: true.

Propriedades obrigatórias

As únicas propriedades obrigatórias para grupos de interesse são owner e name:

Propriedade	Exemplo	Papel
`owner`	`https://dsp.example`	Origem do proprietário do grupo de interesse.
`name`	`custom-bikes`	Nome do grupo de interesse.

Propriedades opcionais

As propriedades restantes são opcionais:

biddingLogicUrl^{1 e 2}: Exemplo: https://dsp.example/bid/custom-bikes/bid.js; Função: URL para dar lances em JavaScript executado no worklet.
biddingWasmHelperUrl^{1 e 2}: Exemplo: https://dsp.example/bid/custom-bikes/bid.wasm; Função: URL do código WebAssembly gerado por biddingLogicUrl.
updateUrl²: Exemplo: https://dsp.example/bid/custom-bikes/update; Papel: URL que retorna JSON para atualizar os atributos do grupo de interesse. Consulte Atualizar dados do público-alvo e atualizar anúncios.
trustedBiddingSignalsUrl²: Exemplo: https://dsp.example/trusted/bidding-signals; Função: URL de base para solicitações de chave-valor para o serviço de chave-valor confiável do bidder.
trustedBiddingSignalsKeys: Exemplo: ['key1', 'key2' ...]; Papel: chaves para solicitações de serviço de chave-valor confiável.
userBiddingSignals: Exemplo: {...}; Papel: metadados adicionais que o proprietário pode usar durante os lances.
ads¹: Exemplo: [bikeAd1, bikeAd2, bikeAd3]; Função: anúncios que podem ser renderizados para esse grupo de interesse.
adComponents: Exemplo: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2]; Função: componentes de anúncios compostos por várias partes.

¹ As propriedades biddingLogicUrl e ads são opcionais, mas obrigatórias para participar de um leilão. Pode haver casos de uso para criar um grupo de interesse sem essas propriedades: por exemplo, um proprietário de grupo de interesse pode querer adicionar um navegador a um grupo de interesse para uma campanha que ainda não está em exibição ou para algum outro uso futuro, ou ele pode ter temporariamente sem orçamento de publicidade.

² Na implementação atual da API Protected Audience, biddingLogicUrl, biddingWasmHelperUrl, updateUrl e trustedBiddingSignalsUrl precisam ter a mesma origem que o proprietário. Essa pode não ser uma restrição de longo prazo, e os URLs ads e adComponents não têm essa restrição.

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
}

`leaveAdInterestGroup()`

O proprietário do grupo de interesse pode solicitar que um navegador seja removido de um grupo de interesse. O navegador remove o grupo de interesse de sua lista de associação.

navigator.leaveAdInterestGroup({
  owner: 'https://dsp.example',
  name: 'custom-bikes'
});

Se um usuário retornar ao site que solicitou a adição de um grupo de interesse ao navegador, o proprietário do grupo poderá chamar a função navigator.leaveAdInterestGroup() para solicitar que o navegador remova o grupo de interesse.

O código de um anúncio também pode chamar essa função para seu grupo de interesse.

Perguntas frequentes

Qual é o número máximo de grupos de interesse por proprietário de grupo para um único usuário?

O Chrome permite até mil grupos de interesse por proprietário e até mil proprietários de grupos de interesse. Esses limites são usados como uma proteção, e não durante a operação normal.

Como maximizar os anúncios do grupo de interesse que atendem aos limites de k-anonimato?

Como indica a explicação pública, como um único grupo de interesse pode exibir vários anúncios que podem ser exibidos, o grupo terá a oportunidade de dar um novo lance a outro de seus anúncios para atuar como um "anúncio substituto" sempre que sua escolha mais preferida estiver abaixo do limite. Isso significa que um anúncio pequeno e especializado que ainda está abaixo do limite de k-anonimato ainda pode participar de leilões, e o grupo de interesse dele tem uma maneira de voltar a um anúncio mais genérico até que o mais especializado tenha um público grande o suficiente.

De uma perspectiva tática, você pode considerar o seguinte:

Para que um novo anúncio comece a ser exibido, basta começar a definir lances com ele nos casos em que você quiser que ele seja exibido. Você não precisa fazer mais nada.
É possível ter um anúncio substituto para quando os novos anúncios não são k-anonimato. Há um risco de seu anúncio substituto não ser um k-anonimato. Desse modo, às vezes você pode considerar apenas definir lances com o anúncio substituto. Faça isso 1% das vezes, por exemplo, se esse for um bom nível para garantir que você espera que o substituto fique acima do limite.

Há uma discussão recente sobre outras maneiras de as coisas funcionarem. Portanto, se você tiver algum caso de uso para o qual esse mecanismo representaria um problema, continue a se envolver na conversa pública sobre maneiras de aprimorar a API.

Todas as referências da API Protected Audience

API reference guides are available:

Developer guide for the Protected Audience API.
Ad buyer guide to Protected Audience interest groups and bid generation.
Ad seller guide to Protected Audience ad auctions.
Guide to reporting auction results
Best practices for Protected Audience ad auction latency
Troubleshoot Protected Audience

The Protected Audience API explainer also provides detail about feature support and constraints.