Esta página foi traduzida pela API Cloud Translation.

Definir dados do público-alvo

Saiba como definir um público-alvo criando um grupo de interesse com a API Protected Audience. Leia o guia para desenvolvedores para conhecer o ciclo de vida completo da API Protected Audience e consulte a explicação da API Protected Audience para conferir uma proposta detalhada de como os navegadores registram os 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 em comum, correspondente a uma lista de remarketing. Todo grupo de interesse da API Protected Audience tem um proprietário.

Os proprietários dos grupos de interesse atuam como compradores no leilão de anúncios da API Protected Audience. A associação ao grupo de interesse é armazenada pelo navegador e 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, 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 assinaturas.

A origem do contexto de chamada para joinAdInterestGroup() precisa corresponder à origem do proprietário do grupo de interesse. Portanto, joinAdInterestGroup() vai precisar ser chamado em 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 os próprios grupos de interesse).

joinAdInterestGroup() requer permissão de:

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

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

Permissão do site visitado

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

Exemplo de uso

Veja 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 para a 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.

Importante: todos os URLs usados como parâmetros para os métodos da API Protected Audience precisam ter origens seguras. Todos os recursos precisam ser disponibilizados em URLs HTTPS. O artigo 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 demais propriedades são opcionais:

biddingLogicUrl^{1 e 2}: Exemplo: https://dsp.example/bid/custom-bikes/bid.js; Papel: o URL para lances do JavaScript é executado no worklet.
biddingWasmHelperUrl^{1 e 2}: Exemplo: https://dsp.example/bid/custom-bikes/bid.wasm; Papel: URL para o código WebAssembly gerado de biddingLogicUrl.
updateUrl²: Exemplo: https://dsp.example/bid/custom-bikes/update; Função: o URL que retorna JSON para atualizar os atributos do grupo de interesse. Consulte Atualizar dados de público-alvo e anúncios.
trustedBiddingSignalsUrl²: Exemplo: https://dsp.example/trusted/bidding-signals; Papel: 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 para o serviço de chave-valor confiável.
userBiddingSignals: Exemplo: {...}; Papel: outros metadados que o proprietário pode usar durante os lances.
ads¹: Exemplo: [bikeAd1, bikeAd2, bikeAd3]; Função: são anúncios que podem ser renderizados para este grupo de interesse.
adComponents: Exemplo: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2]; Função: componentes para 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 do grupo de interesse pode querer adicionar um navegador a um grupo para uma campanha que ainda não está em exibição ou para algum outro uso futuro, ou pode ter ficado 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, como opção, 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 a remoção de um grupo de interesse em um navegador. O navegador remove o grupo de interesse da 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, 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 correspondente.

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 servem como proteções e não devem ser atingidos em operações normais.

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

Como as observações públicas, como um único grupo de interesse pode exibir vários anúncios possíveis, o grupo poderá dar um novo lance em outro anúncio dele para agir como "anúncio substituto" sempre que a opção 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 optar por participar de leilões, e o grupo de interesse dele tem uma maneira de recorrer a um anúncio mais genérico até que o mais especializado tenha um público-alvo grande o suficiente.

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

Para que um novo anúncio comece a ser veiculado, comece a definir lances com ele nos casos em que quiser que ele apareça. Nenhuma ação adicional é necessária.
Você pode ter um anúncio substituto para usar quando os novos anúncios não forem k-anonimato. Há um risco de que o anúncio substituto não seja um k-anonimato. Por isso, às vezes, convém dar lances apenas com o anúncio substituto. Faça isso 1% das vezes, por exemplo, se for um bom nível para garantir que você espera que o substituto fique acima do limite.

Houve algumas discussões recentes sobre outras maneiras como as coisas podem funcionar, portanto, se você tiver algum caso de uso para o qual esse mecanismo poderia representar um problema, continue interagindo na conversa pública sobre como a API pode melhorar.

Todas as referências da API Protected Audience

Os guias de referência da API estão disponíveis:

Guia do desenvolvedor da API Protected Audience.
Guia do comprador de anúncios sobre grupos de interesse e geração de lances da API Protected Audience.
Guia do vendedor de anúncios para leilões de anúncios da Protected Audience.
Guia para gerar relatórios de resultados do leilão
Práticas recomendadas para latência do leilão de anúncios da Protected Audience
Resolver problemas da API Protected Audience

A explicação da API Protected Audience também fornece detalhes sobre o suporte e as restrições de recursos.