Guia para desenvolvedores da API Topics

Aprenda a trabalhar com a API, incluindo como usar as sinalizações do Chrome para testes.

Status da implementação

Veja a demonstração

Há duas demonstrações da API Topics que permitem testar a API como um único usuário.

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 concatena configVersion, taxonomyVersion e modelVersion. 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. Usar a abordagem de cabeçalho pode ser muito mais eficiente do que chamar a API JavaScript.

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ção fetch(). 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 equivalente 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 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.
O painel "Estado dos temas" da página chrome://topics-internals mostra IDs de tópicos, atribuições aleatórias e reais de tópicos 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 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 &quot;Classificador&quot; selecionado.
O painel "Classificador" da página chrome://topics-internals mostra os tópicos selecionados, os hosts visitados e a versão e o caminho do modelo.

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 &quot;Recursos e parâmetros&quot; selecionado.
O painel "Recursos e parâmetros" chrome://topics-internals mostra os elementos ativados, o tempo por período e o número de épocas a serem usados para calcular os 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, 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 o number_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

Interaja e compartilhe feedback