Guia para desenvolvedores da API Topics

Aprenda a trabalhar com a API, incluindo o uso das sinalizações do Chrome em testes.

Status da implementação

Teste a demonstração

Há duas demonstrações da API Topics que você pode testar como um único usuário.

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 concatena configVersion, taxonomyVersion e modelVersion, 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ção fetch(). 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. propriedade iframe.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.

A página chrome://topics-internals com o painel &quot;Estado dos tópicos&quot; selecionado.
O painel de estado dos temas da página chrome://topics-internals mostra IDs de temas, atribuições de temas aleatórios e reais e versões de taxonomia e modelo.

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 página chrome://topics-internals com o painel Classificador selecionado.
O painel Classificador da página chrome://topics-internals mostra os tópicos selecionados, os hosts visitados, a versão do modelo e o caminho.

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).

Página chrome://topics-internals com o painel &quot;Recursos e parâmetros&quot; selecionado.
O painel "Recursos e parâmetros" em chrome://topics-internals mostra os recursos ativados, o tempo por época, o número de períodos usados para calcular temas, a versão da taxonomia e outras configurações.

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 o number_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

Interaja e compartilhe feedback