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 desenvolvedor individual. Recomendamos que você confira as demonstrações para entender como a API Topics funciona antes de começar a implementação.

Ativar os temas no navegador

Para ativar a API Topics na sua 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 sinalizações 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 executando o Chrome na linha de comando. Por exemplo, é possível definir épocas da API Topics (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 um novo usando as sinalizações.
  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, tente nossas dicas de solução de problemas.
  4. Se tiver dúvidas, confira as explicações nos problemas do GitHub.

Controlar a API Topics com flags do Chrome

As sinalizações do Chrome podem modificar o comportamento da API Topics. Execute o Chrome na linha de comando com os parâmetros especificados para facilitar os testes. Por exemplo, a demonstração de cabeçalhos recomenda o uso das 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 Se a API Topics está ativada.
PrivacySandboxAdsAPIsOverride ativado Ativa as APIs de anúncios: Attribution Reporting, Protected Audience, Topics, Fenced Frames.
PrivacySandboxSettings4 desativado Ativa a quarta versão das configurações da interface do Sandbox de privacidade.
OverridePrivacySandboxSettingsLocalTesting ativado Se ativada, o navegador não precisa mais ativar as configurações subjacentes para ativar os recursos do Sandbox de privacidade.
BrowsingTopicsBypassIPIsPubliclyRoutableCheck desativado Se ativada, a verificação de se o endereço IP é roteável publicamente será ignorada ao determinar a qualificação de uma página para ser incluída no cálculo de tópicos.
BrowsingTopics:number_of_epochs_to_expose 3 O número de períodos a partir do qual calcular os temas a serem fornecidos a um contexto solicitante. O navegador mantém internamente 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 isso como 15 segundos, em vez do padrão de 7 dias.
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 um tema individual em uma época ser retornado aleatoriamente de toda a taxonomia de temas. A aleatoriedade é fixa a uma época e a um site.
BrowsingTopics:number_of_epochs_of_observation_data_to_use_for_filtering 3 Quantos períodos de dados de uso da API (ou seja, observações de temas) vão ser usados para filtrar os temas para 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. A intenção é 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 permitidas para serem recuperadas do banco de dados em 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 uso de memória de pico.
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 permitidos para armazenamento 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 precisa ser mapeado para apenas um conjunto de configuração. Em geral, não há problema em atualizar os parâmetros de configuração sem atualizar o config_version para testes locais. No entanto, em algumas situações, o navegador pode ficar em um estado inconsistente e resultar em uma falha, por exemplo, 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 iniciar a implementação, recomendamos que você analise estes recursos para se familiarizar com a API Topics.

  1. Revise 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. Experimente as demonstrações e assista ao tutorial das demonstrações da Topics, do Colab e das ferramentas.
    4. Crie uma cópia das demonstrações e execute-as no seu próprio site.
    5. Leia a explicação sobre a API para entender todos os detalhes.
  2. Entenda o papel da API para 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 alterações de status na API, participe da lista de e-mails para desenvolvedores e fique de olho nas atualizações mais recentes da API Topics.
  4. Participe da conversa sobre 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 os conceitos do Chrome, como as flags, assista os vídeos curtos e os 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.