Configuração da API Topics

Prepare seu ambiente para usar, testar e desenvolver aplicativos da Web com a API Topics.

Criar e testar localmente

Esta seção descreve como configurar seu ambiente local para testar a API Topics como um desenvolvedor individual. Recomendamos que você confira as demonstrações para entender como os tópicos funcionam antes de começar a implementação.

Ativar os temas no navegador

Para ativar a API Topics na sua própria instância do Chrome para testes locais, você tem duas opções:

  1. Ative todas as APIs de privacidade de anúncios em chrome://settings/adPrivacy.
  2. (Recomendado) Execute o Chrome na linha de comando com flags do Chromium usando parâmetros específicos da API Topics para configurar conforme necessário. Você tem um controle mais refinado sobre os recursos do Topics ao executar o Chrome na linha de comando. Por exemplo, é possível definir épocas de tópicos (o período usado pela API para calcular os interesses do usuário) e configurar o comportamento da API de acordo com suas necessidades.

Principais recomendações

  1. Feche e interrompa todos os processos do Chrome antes de iniciar o novo usando as flags.
  2. Verifique se todas as APIs de privacidade de anúncios estão ativadas em chrome://settings/adPrivacy.
  3. Se a API não funcionar como esperado, confira nossas dicas de solução de problemas.
  4. Se tiver dúvidas, confira os problemas do GitHub para a explicação.

Controlar a API Topics com flags do Chrome

As flags do Chrome podem modificar o comportamento da API Topics. Execute o Chrome na linha de comando com os parâmetros especificados para facilitar o teste. Por exemplo, a demonstração de cabeçalhos recomenda usar as seguintes flags:

--enable-features=BrowsingTopics,BrowsingTopicsParameters:time_period_per_epoch/15s/max_epoch_introduction_delay/3s,PrivacySandboxAdsAPIsOverride,PrivacySandboxSettings3,OverridePrivacySandboxSettingsLocalTesting

A tabela a seguir explica cada parâmetro, o valor padrão e a finalidade dele.

Nome da flag Valor padrão Descrição
BrowsingTopics ativado Indica se a API Topics está ativada.
PrivacySandboxAdsAPIsOverride ativado Ativa as APIs de anúncios: Attribution Reporting, Protected Audience, Topics e Fenced Frames.
PrivacySandboxSettings4 desativado Ativa a quarta versão das configurações da interface do Sandbox de privacidade.
OverridePrivacySandboxSettingsLocalTesting ativado Se ativado, o navegador não vai mais exigir que as configurações subjacentes estejam ativadas para ativar os recursos do Sandbox de privacidade.
BrowsingTopicsBypassIPIsPubliclyRoutableCheck desativado Se ativada, a verificação de roteamento público do endereço IP será ignorada ao determinar a qualificação de uma página para inclusão no cálculo de tópicos.
BrowsingTopics:number_of_epochs_to_expose 3 O número de épocas de onde calcular os tópicos para dar a um contexto de solicitação. Internamente, o navegador mantém até N+1 épocas.
BrowsingTopics:time_period_per_epoch 7d-0h-0m-0s Duração de cada época. Para depuração, pode ser útil definir esse valor como 15 segundos, por exemplo, em vez dos sete dias padrão.
BrowsingTopics:number_of_top_topics_per_epoch 5 Número de tópicos calculados por época.
BrowsingTopics:use_random_topic_probability_percent 5 Probabilidade de que um tema individual em um período seja retornado aleatoriamente de toda a taxonomia de temas. A aleatoriedade é vinculada a uma época e a um site.
BrowsingTopics:number_of_epochs_of_observation_data_to_use_for_filtering 3 Quantas épocas de dados de uso da API (ou seja, observações de temas) serão usadas para filtrar os temas de um contexto de chamada.
BrowsingTopics:max_number_of_api_usage_context_domains_to_keep_per_topic 1000 O número máximo de domínios de contexto observados a serem mantidos para cada tópico principal. O objetivo é limitar a memória em uso.
BrowsingTopics:max_number_of_api_usage_context_entries_to_load_per_epoch 100000 O número máximo de entradas que podem ser recuperadas do banco de dados para cada consulta dos contextos de uso da API. A consulta vai ocorrer uma vez por época no momento do cálculo dos temas. O objetivo é limitar o pico de uso da memória.
BrowsingTopics:max_number_of_api_usage_context_domains_to_store_per_page_load 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 1 Codifica os parâmetros de configuração da API Topics. Cada número de versão só pode ser mapeado para 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, por exemplo, ao atualizar o number_of_top_topics_per_epoch.
BrowsingTopics:taxonomy_version 1 A versão da taxonomia usada pela API.

Antes de começar a implementar

Antes de começar a implementação, recomendamos que você revise estes recursos para se familiarizar com a API Topics.

  1. Leia a documentação para desenvolvedores:
    1. Entender a finalidade da API Topics e o papel dela na publicidade com base em interesses
    2. Entenda como a Topics funciona na Web.
    3. Teste as demonstrações e assista ao vídeo explicativo sobre as demonstrações, o Colab e as ferramentas de tópicos.
    4. Faça um fork das demonstrações e execute-as no seu próprio site.
    5. Leia a explicação da API para entender mais detalhes.
  2. Entenda a função da API em apoiar a relevância do anúncio no futuro, quando os cookies de terceiros não estiverem disponíveis para uma proporção cada vez maior de usuários.
  3. Para receber notificações sobre mudanças de status na API, participe da lista de e-mails para desenvolvedores e fique por dentro das atualizações mais recentes da API Topics.
  4. Contribua para a conversa em problemas do GitHub ou chamadas do W3C.
  5. Se você encontrar termos desconhecidos, consulte o glossário do Sandbox de privacidade.
  6. Para mais informações sobre conceitos do Chrome, como flags, confira os vídeos e artigos disponíveis em goo.gle/cc.

Próximas etapas

Confira os detalhes de implementação e os exemplos de código para que os autores de chamadas observem e acessem os tópicos.
Saiba como implantar, testar e dimensionar soluções baseadas em tópicos.