Aprenda a trabalhar com a API, incluindo como usar as sinalizações do Chrome para 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.
Confira a demonstração
Há duas demonstrações da API Topics que permitem testar a API como um único usuário.
- Demonstração da API JavaScript: topics-demo.glitch.me
- Demonstração do 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.
Usar a API JavaScript para acessar tópicos e registrá-los conforme observado
A API Topics JavaScript tem um método: document.browsingTopics()
. Isso tem dois propósitos:
- Informe ao navegador para registrar a visita atual à página como tendo sido observada pelo autor da chamada, para que possa ser usado posteriormente para calcular temas 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 temas, um para cada um dos três períodos 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 usados pelo navegador, por exemplo,2
.topic
: um número que identifica o tema na taxonomia (link em inglês), 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 tamanho da taxonomia, 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 fazemos iterações na API.
Detectar suporte a 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 tópicos com a API JavaScript
Este é um exemplo básico de um 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 atual à página, conforme observado pelo autor da chamada, para que ela possa ser usada no cálculo dos temas. No Chrome 108, o método pode receber um argumento opcional para evitar que a visita à página seja registrada: {skipObservation:true}
.
Em outras palavras, {skipObservation:true}
significa que a chamada de método não fará com que a página atual seja incluída no cálculo de temas.
Use cabeçalhos para acessar os tópicos e marque-os como observados
É possível acessar tópicos e marcar visitas à página como observadas com a ajuda dos cabeçalhos de solicitação e resposta.
O uso da abordagem de cabeçalho pode ser muito mais eficiente 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()
dele. Um iframe de origem cruzada precisa ser usado para a chamada porque o contexto a partir do qual a API é invocada é usado para garantir que o navegador retorne os tópicos apropriados para o autor da chamada. A explicação da API Topics tem mais detalhes: É possível enviar temas usando a ferramenta Buscar como um cabeçalho de solicitação? .
Os temas podem ser acessados no cabeçalho Sec-Browsing-Topics
de uma solicitação fetch()
ou XHR
.
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 que ela possa ser usada no cálculo de temas.
Os tópicos podem ser acessados e observados com cabeçalhos HTTP de duas maneiras:
fetch()
: adicione{browsingTopics: true}
ao parâmetro de opções de uma solicitaçãofetch()
. A demonstração do cabeçalho "Tópicos" mostra um exemplo simplificado.- Atributo iframe: adicione o atributo
browsingtopics
a um elemento<iframe>
ou defina a propriedade JavaScript equivalenteiframe.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 tópicos enviados na solicitação de redirecionamento 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 de tema do usuário para o próximo período.
- O cabeçalho de resposta só é atendido se a solicitação correspondente incluir o cabeçalho de tópicos.
- O URL da solicitação fornece o domínio registrável que é gravado como o domínio do autor da chamada.
Depurar a implementação da API
A página chrome://topics-internals
vai ficar disponível no Chrome para computador depois que você ativar a API Topics. São exibidos tópicos do usuário atual, temas 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: adicione seu feedback em bugs.chromium.org.
Ver temas calculados para seu navegador
Os usuários podem consultar informações sobre temas observados no navegador durante as épocas atual e anterior acessando chrome://topics-internals
.
![A página chrome://topics-internals com o painel Estado dos temas selecionado.](https://developers.google.cn/static/privacy-sandbox/assets/images/the-chrometopics-inter-0a0a54332c409.png?authuser=8&hl=pt-br)
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 observam temas) para fornecer cinco temas.
A coluna Domínios de contexto observados por contexto (com hash) mostra o valor de hash de um nome do host em que um tópico foi observado.
Ver tópicos inferidos para nomes de host
Também é possível conferir os temas inferidos pelo modelo de classificador da API Topics para um ou mais nomes de host em chrome://topics-internals
.
![A página chrome://topics-internals com o painel "Classificador" selecionado.](https://developers.google.cn/static/privacy-sandbox/assets/images/the-chrometopics-inter-680196727dbe8.png?authuser=8&hl=pt-br)
A implementação atual da API Topics reconhece temas apenas com base nos nomes do host, e não em qualquer outra parte de um URL.
Use apenas nomes de host (sem protocolo ou caminho) para visualizar temas inferidos do classificador chrome://topics-internals
. chrome://topics-internals
exibirá um erro se você tentar incluir um "/" no campo "Host".
Ver informações da API Topics
É possível encontrar 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 da linha de comando funcionaram conforme o esperado.
No exemplo, time_period_per_epoch
foi definido como 15 segundos (o padrão é sete dias).
![Página chrome://topics-internals com o painel "Recursos e parâmetros" selecionado.](https://developers.google.cn/static/privacy-sandbox/assets/images/chrometopics-internals-a56a143c41aa1.png?authuser=8&hl=pt-br)
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, na demonstração em topics-fetch-demo.glitch.me, recomendamos o uso das seguintes sinalizações:
--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 as APIs de anúncios: Attribution Reporting, Protected Audience, Topics, Fenced Frames.
PrivacySandboxSettings4
- Valor padrão: desativado
- Ativa a quarta versão das configurações de interface do Sandbox de privacidade.
OverridePrivacySandboxSettingsLocalTesting
- Valor padrão:ativado
- Se essa opção for ativada, o navegador não vai mais exigir que as configurações para ativar os recursos do Sandbox de privacidade sejam ativadas.
BrowsingTopicsBypassIPIsPubliclyRoutableCheck
- Valor padrão: desativado
- Se ativada, a verificação para saber se o endereço IP é publicamente roteável será ignorada ao determinar a qualificação para uma página ser incluída no cálculo de tópicos.
BrowsingTopics:number_of_epochs_to_expose
- Valor padrão: 3
- O número de épocas a partir de onde calcular os temas a serem enviados a um contexto de solicitação. O navegador manterá até N+1 períodos.
BrowsingTopics:time_period_per_epoch
- Valor padrão: 7d-0h-0m-0s
- Duração de cada período. Para depuração, pode ser útil defini-lo como, por exemplo, 15 segundos, em vez dos sete dias padrão.
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 é fixa em uma época e em um local.
BrowsingTopics:number_of_epochs_of_observation_data_to_use_for_filtering
- Valor padrão: 3
- Quantos períodos de dados de uso da API (por exemplo, observações de temas) serão usados para filtrar os temas para 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 a serem mantidos para cada tema principal. A intent é limitar a memória em uso.
BrowsingTopics:max_number_of_api_usage_context_entries_to_load_per_epoch
- Valor padrão: 100000
- 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 momento do cálculo dos temas. A intenção é limitar o pico de uso da memória.
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 só pode ser
associado a um conjunto de configurações. Atualizar os parâmetros de configuração sem atualizar o
config_version
geralmente é adequado para testes locais, mas, em algumas situações, pode deixar o navegador em um estado inconsistente e resultar em uma falha do navegador, como atualizar onumber_of_top_topics_per_epoch
. BrowsingTopics:taxonomy_version
- Valor padrão: 1
- A versão da taxonomia usada pela API.
Desativar seu site
Para desativar o cálculo de temas em páginas específicas do seu site, inclua o cabeçalho Permissions-Policy: browsing-topics=()
Permissions-Policy em uma página para evitar o cálculo de temas para todos os usuários. 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 as outras.
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 no cabeçalho, use self
e todos os domínios que terão acesso à API. Por exemplo, para desativar completamente o uso da API Topics em todos os contextos de navegação, exceto na sua origem e no 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.
- Teste 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.