Aprenda a trabalhar com a API, incluindo o uso das sinalizações do Chrome em testes.
Status da implementação
- A API Topics concluiu a fase de discussão pública e atualmente está disponível para 99% dos usuários, chegando a 100%.
- Para enviar feedback sobre a API Topics, crie um problema na explicação da API Topics ou participe das discussões no grupo de negócios Como melhorar a publicidade na Web (em inglês). A explicação tem várias perguntas em aberto que ainda precisam de definição.
- O cronograma do Sandbox de privacidade apresenta os cronogramas de implementação da API Topics e de outras propostas do Sandbox de privacidade.
- API Topics: atualizações mais recentes detalha mudanças e melhorias na API Topics e implementações.
Teste a demonstração
Há duas demonstrações da API Topics que você pode testar como um único usuário.
- Demonstração da API JavaScript: topics-demo.glitch.me
- Demonstração de cabeçalho: topics-fetch-demo.glitch.me
Você também pode executar o Colab da API Topics para testar o modelo de classificador da API Topics.
Usar a API JavaScript para acessar temas e registrá-los conforme observado
A API Topics JavaScript tem um método: document.browsingTopics()
. Isso tem duas finalidades:
- Diga ao navegador para registrar a visita atual à página como tendo sido observada para o autor da chamada. Assim, isso poderá ser usado posteriormente para calcular tópicos para o usuário (para o autor da chamada).
- Acessar temas do usuário que foram observados pelo autor da chamada.
O método retorna uma promessa que é resolvida em uma matriz de até três tópicos, um para cada uma das três épocas mais recentes, em ordem aleatória. Um período é um período definido como uma semana na implementação do Chrome.
Cada objeto de tópico na matriz retornada por document.browsingTopics()
tem estas propriedades:
configVersion
: uma string que identifica a configuração atual da API Topics, por exemplo,chrome.2
.modelVersion
: uma string que identifica o classificador de aprendizado de máquina usado para inferir temas para o site, por exemplo,4
taxonomyVersion
: uma string que identifica o conjunto de temas usado pelo navegador, por exemplo,2
.topic
: um número que identifica o tema na taxonomia, por exemplo,309
version
: uma string que concatenaconfigVersion
,taxonomyVersion
emodelVersion
, por exemplo,chrome.2:2:4
.
Os parâmetros descritos neste guia e os detalhes da API (como o tamanho da taxonomia, o número de temas calculados por semana e o número de temas retornados por chamada) estão sujeitos a mudanças à medida que incorporamos o feedback do ecossistema e repetimos a API.
Detectar suporte para document.browsingTopics
Antes de usar a API, verifique se ela é compatível com o navegador e está disponível no documento:
'browsingTopics' in document && document.featurePolicy.allowsFeature('browsing-topics') ?
console.log('document.browsingTopics() is supported on this page') :
console.log('document.browsingTopics() is not supported on this page');
Acessar temas com a API JavaScript
Este é um exemplo básico do possível uso da API para acessar tópicos para o usuário atual.
try {
// Get the array of top topics for this user.
const topics = await document.browsingTopics();
// Request an ad creative, providing topics information.
const response = await fetch('https://ads.example/get-creative', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(topics)
})
// Get the JSON from the response.
const creative = await response.json();
// Display ad.
} catch (error) {
// Handle error.
}
Acessar tópicos sem modificar o estado
document.browsingTopics()
retorna temas observados pelo autor da chamada para o usuário atual. Por padrão, o método também faz com que o navegador registre a visita à página atual, conforme observado pelo autor da chamada, para que possa ser usado posteriormente no cálculo de temas. No Chrome 108, o método pode receber um argumento opcional para pular a gravação da visita à página: {skipObservation:true}
.
Em outras palavras, {skipObservation:true}
significa que a chamada do método não fará com que a página atual seja incluída no cálculo dos temas.
Usar cabeçalhos para acessar temas e marcá-los como observados
Você pode acessar tópicos e também marcar visitas à página como observadas, com a ajuda de request e response.
Usar a abordagem de cabeçalho pode ter um desempenho muito melhor do que usar a API JavaScript, já que a API exige a criação de um iframe de origem cruzada e uma chamada document.browsingTopics()
a partir dele. É necessário usar um iframe de origem cruzada para a chamada, porque o contexto a partir do qual a API é invocada é usado para garantir que o navegador retorne os temas adequados ao autor da chamada. A explicação da API Topics tem uma discussão mais aprofundada: é possível enviar temas usando "Buscar como um cabeçalho de solicitação"? .
Os tópicos podem ser acessados no cabeçalho Sec-Browsing-Topics
de uma solicitação fetch()
ou XHR
.
Como definir um cabeçalho Observe-Browsing-Topics: ?1
na resposta à solicitação
faz com que o navegador registre a visita atual à página conforme observado pelo autor da chamada,
para uso posterior no cálculo de temas.
Os tópicos podem ser acessados e observados com cabeçalhos HTTP de duas maneiras:
fetch()
: adicionar{browsingTopics: true}
ao parâmetro de opções de uma solicitaçãofetch()
. A demonstração do cabeçalho da API Topics mostra um exemplo simplificado.- Atributo iframe: adicione o atributo
browsingtopics
a um elemento<iframe>
ou defina o JavaScript equivalente. propriedadeiframe.browsingTopics = true
. O domínio registrável da origem do iframe é o domínio do autor da chamada: por exemplo, para<iframe src="https://example.com" browsingtopics></iframe>
: o autor da chamada éexample.com
.
Algumas observações adicionais sobre cabeçalhos:
- Os redirecionamentos serão seguidos, e os temas enviados na solicitação serão específicos para o URL de redirecionamento.
- O cabeçalho da solicitação não modificará o estado do autor da chamada, a menos que haja um cabeçalho de resposta correspondente. Ou seja, sem o cabeçalho de resposta, a visita à página não será registrada como observada. Portanto, isso não afetará o cálculo do tema do usuário para a próxima época.
- O cabeçalho de resposta só será respeitado se a solicitação correspondente incluir o cabeçalho de tópicos.
- O URL da solicitação fornece o domínio registrável que é registrado como o domínio do autor da chamada.
Depurar a implementação da API
A página chrome://topics-internals
fica disponível no Chrome para computadores depois que você ativa a API Topics. Ele mostra os tópicos do usuário atual, inferidos para nomes de host e informações técnicas sobre a implementação da API. Estamos iterando e melhorando o design da página com base no feedback dos desenvolvedores. Envie sua opinião em bugs.chromium.org.
Ver temas calculados para seu navegador
Os usuários podem conferir informações sobre temas observados no navegador durante a época atual e anterior acessando chrome://topics-internals
.
Esta captura de tela mostra que os sites visitados recentemente incluem topics-demo-cats.glitch.me
e cats-cats-cats-cats.glitch.me
. Isso faz com que a API Topics selecione Pets
e Cats
como dois dos principais temas da época atual. Os três temas restantes foram escolhidos aleatoriamente, já que não há histórico de navegação suficiente (em sites que acompanham temas) para fornecer cinco temas.
A coluna Domínios de contexto observados (com hash) fornece o valor em hash de um nome do host para o qual um tópico foi observado.
Conferir temas inferidos para nomes de host
Também é possível visualizar os temas inferidos pelo modelo de classificador da API Topics para um ou mais nomes de host em chrome://topics-internals
.
A implementação atual da API Topics infere temas apenas com base em nomes de host. de qualquer outra parte de um URL.
Use somente nomes de host (sem protocolo ou caminho) para ver os tópicos inferidos do classificador chrome://topics-internals
. chrome://topics-internals
exibirá um erro se você tentar incluir um "/" no campo Host.
Conferir informações da API Topics
Confira informações sobre a implementação e as configurações da API Topics, como a versão da taxonomia e a duração da época, em chrome://topics-internals
. Esses valores refletem as configurações padrão da API ou os parâmetros definidos na linha de comando. Isso pode ser útil para confirmar se as sinalizações de linha de comando funcionaram conforme o esperado.
No exemplo, time_period_per_epoch
foi definido como 15 segundos (o padrão é sete dias).
Os parâmetros mostrados na captura de tela correspondem às sinalizações que podem ser definidas ao executar o Chrome na linha de comando. Por exemplo, a demonstração em topics-fetch-demo.glitch.me recomenda o uso das seguintes flags:
--enable-features=BrowsingTopics,BrowsingTopicsParameters:time_period_per_epoch/15s/max_epoch_introduction_delay/3s,PrivacySandboxAdsAPIsOverride,PrivacySandboxSettings3,OverridePrivacySandboxSettingsLocalTesting
A lista a seguir explica cada parâmetro, o valor padrão e a finalidade dele.
Sinalizações do Chrome
BrowsingTopics
- Valor padrão: ativado
- Define se a API Topics está ativada.
PrivacySandboxAdsAPIsOverride
- Valor padrão: ativado
- Ativa APIs de anúncios: Attribution Reporting, Protected Audience, Topics, Fenced Frames.
PrivacySandboxSettings4
- Valor padrão: desativado
- Ativa a quarta versão das configurações da interface do Sandbox de privacidade.
OverridePrivacySandboxSettingsLocalTesting
- Valor padrão: ativado
- Se ativado, o navegador não exige mais que as configurações subjacentes estejam ativadas para ativar os recursos do Sandbox de privacidade.
BrowsingTopicsBypassIPIsPubliclyRoutableCheck
- Valor padrão: desativado
- Se ativada, a verificação para saber se o endereço IP é roteável publicamente será ignorado ao determinar a qualificação de uma página para inclusão em temas cálculo.
BrowsingTopics:number_of_epochs_to_expose
- Valor padrão: 3
- O número de períodos a partir do qual calcular os temas a serem fornecidos a um solicitante contexto. O navegador manterá internamente até N+1 períodos.
BrowsingTopics:time_period_per_epoch
- Valor padrão: 7d-0h-0m-0s
- Duração de cada época. Para depuração, pode ser útil definir isso como 15 segundos, em vez do padrão de 7 dias.
BrowsingTopics:number_of_top_topics_per_epoch
- Valor padrão: 5
- Número de temas calculados por época.
BrowsingTopics:use_random_topic_probability_percent
- Valor padrão: 5
- Probabilidade de que um tema individual em uma época seja retornado aleatoriamente de toda a taxonomia de temas. A aleatoriedade segue uma época e um site.
BrowsingTopics:number_of_epochs_of_observation_data_to_use_for_filtering
- Valor padrão: 3
- Por quantos períodos os dados de uso da API (ou seja, observações de tópicos) serão usados filtrando os tópicos por um contexto de chamada.
BrowsingTopics:max_number_of_api_usage_context_domains_to_keep_per_topic
- Valor padrão: 1.000
- O número máximo de domínios de contexto observados por domínios de contexto a serem mantidos para cada tópico principal. A intenção é limitar a memória em uso.
BrowsingTopics:max_number_of_api_usage_context_entries_to_load_per_epoch
- Valor padrão: 100.000
- O número máximo de entradas que podem ser recuperadas do banco de dados para cada consulta para os contextos de uso da API. A consulta vai ocorrer uma vez por época no cálculo dos temas tempo de resposta. A intenção é limitar o uso de memória de pico.
BrowsingTopics:max_number_of_api_usage_context_domains_to_store_per_page_load
- Valor padrão: 30
- O número máximo de domínios de contexto de uso da API que podem ser armazenados por carregamento de página.
BrowsingTopics:config_version
- Valor padrão: 1
- Codifica os parâmetros de configuração da API Topics. Cada número de versão deve ser
associados a um conjunto de configurações. Atualizar os parâmetros de configuração sem atualizar o
config_version
precisa geralmente são adequados para testes locais, mas, em algumas situações, o navegador pode ficar estado inconsistente e pode resultar em uma falha do navegador, por exemplo, atualizar onumber_of_top_topics_per_epoch
. BrowsingTopics:taxonomy_version
- Valor padrão: 1
- A taxonomia usada pela API.
Desativar seu site
Para desativar o cálculo de temas em páginas específicas do site, inclua o cabeçalho Permissions-Policy: browsing-topics=()
Permissions-Policy em uma página para impedir o cálculo de temas para todos os usuários da página. As visitas subsequentes a outras páginas do site não serão afetadas: se você definir uma política para bloquear a API Topics em uma página, isso não vai afetar outras páginas.
Também é possível controlar quais terceiros têm acesso aos temas da sua página usando o cabeçalho Permissions-Policy
para controlar o acesso de terceiros à API Topics. Como parâmetros para o cabeçalho, use self
e todos os domínios aos quais você quer permitir o acesso à API. Por exemplo, para desativar completamente o uso da API Topics em todos os contextos de navegação, exceto sua própria origem e https://example.com
, defina o seguinte cabeçalho de resposta HTTP:
Permissions-Policy: browsing-topics=(self "https://example.com")
Próximas etapas
- Saiba mais sobre o que são os temas e como eles funcionam.
- Confira a demonstração.
Saiba mais
Interaja e compartilhe feedback
- GitHub: leia a explicação da API Topics, tire dúvidas e acompanhe a discussão de problemas no repositório da API.
- W3C: discuta casos de uso do setor no grupo de negócios Como melhorar a publicidade na Web (em inglês).
- Avisos: participe ou acesse a lista de e-mails.
- Suporte ao desenvolvedor do Sandbox de privacidade: faça perguntas e participe de discussões no repositório de suporte para desenvolvedores do Sandbox de privacidade (link em inglês).
- Chromium: registre um bug do Chromium para fazer perguntas sobre a implementação atualmente disponível para teste no Chrome.