Recursos de suporte para a API Topics na Web

Encontre recomendações para depuração, solução de problemas e recursos de suporte para tópicos na Web.

Solução de problemas

Se você fizer uma chamada document.browsingTopics() ou uma solicitação fetch() com o cabeçalho Sec-Browsing-Topics definido, mas receber uma matriz vazia como resposta, há várias etapas de depuração que podem ser realizadas para identificar a causa raiz do problema, tanto no ambiente de desenvolvimento local quanto no sistema ativo.

Depurar localmente

Se você fizer o teste localmente, verifique se está executando o Chrome com os parâmetros necessários.

  • Para ignorar a inscrição, ative a flag chrome://flags/#privacy-sandbox-enrollment-overrides e adicione o URL do site que chama os tópicos.

  • Configure a API Topics para testes usando as flags de recursos. Com essas flags, é possível modificar parâmetros como a duração da época, o número de principais temas e outros, para que você possa testar os temas com facilidade. Você pode usar estas flags de recursos recomendadas:

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

  • Antes de executar o Chrome com flags, feche todas as outras instâncias e processos do Chrome.

  • Confira se:

    • Você está usando o Chrome 101 ou mais recente.
    • Seu script chamou a API Topics para observar temas. Durante o teste, você pode simular o comportamento do usuário acessando os sites em que seu script está incorporado. Consulte a demonstração para conferir um exemplo prático.
    • Você não tem um bloqueador de anúncios ou um app ou extensão semelhante em execução.
    • Você não está no modo de navegação anônima.
    • Em chrome://settings/trackingProtection, a opção Block all third-party cookies está desativada.

Depurar a implementação em tempo real

Se você estiver chamando a API Topics de um aplicativo ativo na primeira semana de observação de um usuário, o resultado será vazio, porque o aplicativo ainda não observou temas para um usuário. Você pode depurar sua solução seguindo nossas recomendações.

  • Verifique se o site está registrado no Sandbox de privacidade.
  • Teste o código do front-end para garantir que o JavaScript esteja funcionando conforme o esperado.
  • Teste seu back-end para receber os resultados dos temas.
    • Verifique se os tipos de dados e os parâmetros da API de back-end estão configurados corretamente.
    • Verifique se o back-end está configurado para dimensionar adequadamente.
  • Pela nossa experiência, é necessário aguardar pelo menos três semanas antes de começar a receber resultados de tópicos mais relevantes.
  • Nem todos os usuários vão ter a opção "Temas" ativada:
    • Os usuários podem desativar explicitamente a API Topics.
    • As páginas do editor podem controlar a política de permissões e desativar os sites.
  • Adicione métricas e observabilidade a esse ambiente: você vai precisar delas para analisar os primeiros resultados. Confira alguns exemplos de métricas:
    • Latência das chamadas.
    • Erros HTTP em chamadas de tópicos.
  • Tente limitar as mudanças na implementação durante as três semanas iniciais.

Recursos