Definir dados de público-alvo

Saiba como definir um público-alvo criando um grupo de interesse usando a API Protected Audience. Leia o guia para desenvolvedores para conhecer todo o ciclo de vida da API Protected Audience e consulte a explicação da API para uma proposta detalhada de como os navegadores registram grupos de interesse.

Não é 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 em comum, correspondente a uma lista de remarketing. Todo grupo de interesse da API Protected Audience tem um proprietário.

Os proprietários de grupos de interesse atuam como compradores 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 ou 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ções dele.

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

O joinAdInterestGroup() requer permissão de:

Isso significa que não é possível para malicious.example chamar joinAdInterestGroup() para um grupo de interesse de propriedade de dsp.example.com sem que dsp.example.com conceda permissão.

Permissão do site visitado

A permissão pode ser concedida da mesma origem ou entre origens. 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

Confira um exemplo de como definir um grupo de interesse e pedir que o navegador participe dele.

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 à função não pode ter mais de 50 KiB. Caso contrário, a chamada vai falhar. O segundo parâmetro especifica a duração do grupo de interesse, limitada a 30 dias. Chamadas sucessivas substituem os valores armazenados anteriormente.

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:

biddingLogicUrl1, 2
Exemplo: https://dsp.example/bid/custom-bikes/bid.js
Função: URL para execução de JavaScript de lances em worklet.
biddingWasmHelperUrl1, 2
Exemplo: https://dsp.example/bid/custom-bikes/bid.wasm
Função: URL para código WebAssembly gerado por biddingLogicUrl.
updateUrl2
Exemplo: https://dsp.example/bid/custom-bikes/update
Função: URL que retorna JSON para atualizar atributos de grupo de interesse. Consulte Atualizar dados de público-alvo e atualizar anúncios.
trustedBiddingSignalsUrl2
Exemplo: https://dsp.example/trusted/bidding-signals
Função: URL de base para solicitações de chave-valor ao serviço de chave-valor confiável do bidder.
trustedBiddingSignalsKeys
Exemplo: ['key1', 'key2' ...]
Função: chaves para solicitações ao serviço de chave/valor confiável.
userBiddingSignals
Exemplo: {...}
Função: metadados adicionais que o proprietário pode usar durante os lances.
ads1
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 para anúncios compostos de várias partes.

1 As propriedades biddingLogicUrl e ads são opcionais, mas necessárias para participar de um leilão. Pode haver casos de uso para criar um grupo de interesse sem essas propriedades. Por exemplo, o proprietário de um grupo de interesse pode querer adicionar um navegador a um grupo de interesse para uma campanha que ainda não está sendo veiculada ou para algum outro uso futuro, ou pode ter ficado temporariamente sem orçamento de publicidade.

2 Na implementação atual da API Protected Audience, biddingLogicUrl, biddingWasmHelperUrl, updateUrl e trustedBiddingSignalsUrl precisam ter a mesma origem do 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 pedir que um navegador seja removido de um grupo de interesse. O navegador remove o grupo de interesse da lista de participantes.

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

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

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

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é 1.000 grupos de interesse por proprietário e até 1.000 proprietários de grupos de interesse. Esses limites são como barreiras de proteção, não devem ser atingidos na operação regular.

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

Como o vídeo explicativo público observa, um único grupo de interesse pode veicular vários anúncios possíveis. Assim, o grupo tem a oportunidade de fazer um novo lance em outro anúncio para atuar como um "anúncio substituto" sempre que a opção preferida estiver abaixo do limite. Isso significa que um anúncio pequeno e especializado, mas ainda abaixo do limite de k-anonimato, pode participar de leilões, e o grupo de interesse tem uma maneira de voltar a um anúncio mais genérico até que o mais especializado tenha um público-alvo grande o suficiente.

Do ponto de vista tático, considere o seguinte:

  • Para começar a veicular um novo anúncio, faça um lance com ele nos casos em que você quer que ele apareça. Não é necessário fazer mais nada.
  • Você pode ter um anúncio substituto para usar quando os novos anúncios não forem 𝑘-anônimos. Há algum risco de o anúncio substituto não ser 𝑘-anônimo. Por isso, considere fazer lances com ele desde o início. Faça isso 1% das vezes, por exemplo, se esse for um bom nível para garantir que o fallback permaneça acima do limite.

Recentemente, houve uma discussão sobre outras maneiras de as coisas funcionarem. Se você tiver um caso de uso em que esse mecanismo seria um problema, continue participando da conversa pública sobre como a API pode melhorar.

Todas as referências da API Protected Audience

API reference guides are available:

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