Guia de integração da API Topics

Aprenda a usar a API Topics para atender a casos de uso específicos de adtech.

Antes de começar

A primeira etapa é se familiarizar com a API e os serviços da API Topics.

  1. Consulte a documentação para desenvolvedores:
    1. Comece lendo a visão geral para se familiarizar com a API Topics e os recursos dela.
    2. Assista ao tutorial de demonstração da Topics (vídeo).
    3. Teste as demonstrações do cabeçalho da API Topics e da API JavaScript.
    4. Separe as demonstrações (ambas fornecem links para os códigos) e execute-as no seu site.
    5. Confira a explicação sobre a API para entender melhor os detalhes.
  2. Verifique o status da implementação e o cronograma da API Topics.
  3. Entenda o papel da API em oferecer suporte à relevância do anúncio em um futuro sem cookies.
  4. Para receber notificações sobre mudanças de status na API, entre na lista de e-mails para desenvolvedores e fique de olho nas atualizações mais recentes da API Topics.
  5. Fique por dentro das notícias mais recentes sobre a API Topics.
  6. Contribua com a conversa por meio de problemas do GitHub ou chamadas do W3C.
  7. Se você encontrar termos desconhecidos, consulte o glossário do Sandbox de privacidade.
  8. Para mais informações sobre os conceitos do Chrome, como as sinalizações do Chrome, veja os vídeos curtos e os artigos disponíveis em goo.gle/cc.

Criar e testar localmente

Esta seção descreve como testar a API Topics como desenvolvedor individual.

  1. Teste e implantação locais (tempo estimado: cerca de dois dias)
    1. Ative a API com o navegador local pela linha de comando usando sinalizações de recursos. Teste as demonstrações do cabeçalho e da API JavaScript para conferir a API Topics em ação (tutorial em vídeo).
    2. Execute o Colab da API Topics para testar a inferência de temas usando o modelo de machine learning da API Topics.

Ativar a API Topics no navegador

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

  1. Abra chrome://flags/#privacy-sandbox-ads-apis e ative as APIs do Sandbox de privacidade.
  2. (Recomendado) Execute o Chrome na linha de comando com as flags do Chromium usando parâmetros específicos da API Topics para configurar conforme necessário.
Ative as APIs do Sandbox de privacidade em chrome://flags/#privacy-sandbox-ads-apis.
Ativar as APIs do Sandbox de privacidade.

Você tem um controle mais refinado sobre os recursos da API 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 dos usuários) e o comportamento da API de acordo com suas necessidades.

É importante lembrar que, se chrome://flags/#privacy-sandbox-ads-apis estiver ativado, isso substituirá a configuração de época da linha de comando, retornando ao valor padrão (atualmente uma semana).

Prévia da mecânica da API Topics

Você pode conferir localmente a mecânica da API Topics usando as ferramentas chrome://topics-internals.

Dê uma olhada na API Topics em chrome://topics-internals.
A guia "Estado dos tópicos" chrome://topics-internals tools.

Use a ferramenta Internal API Topics para testar localmente o classificador com base nos sites que você acessa.

Com essa ferramenta, você pode conferir:

  • Estado dos tópicos:mostra os temas observados para o usuário atual.
  • Classificador:visualiza temas inferidos para nomes de host.
  • Recursos e parâmetros:confira os valores de parâmetro da API para verificar se as flags de recursos estão funcionando conforme o esperado.

Aprenda a depurar tópicos com a ferramenta Internals (link em inglês).

Como a API retorna temas

Se o Chrome não tiver um número suficiente de temas observados para criar os cinco principais temas de uma época (uma semana), a API Topics vai adicionar temas aleatórios para completar os cinco principais. A coluna "Topics Internals" com o título Real ou Random indica se esse tópico específico foi baseado em uma observação real ou "padding" aleatório adicional para completar os cinco principais. Saiba mais sobre esse mecanismo na explicação.

O tema de cada época é selecionado aleatoriamente entre os cinco principais temas do usuário no período. Se não forem observados tópicos suficientes durante a época, outros tópicos serão escolhidos aleatoriamente para completar o total de cinco. Esses tópicos selecionados aleatoriamente estão sujeitos a filtragem.

Para aumentar ainda mais a privacidade e garantir que todos os temas sejam representados, há 5% de chance de que o tema selecionado para uma época seja selecionado aleatoriamente entre todos os temas, em vez de ser escolhido entre temas observados. Como no caso acima, em que poucos temas foram observados, esses temas selecionados aleatoriamente não estão sujeitos à filtragem.

Saiba mais sobre a seleção dos temas em Classificação de temas.

Principais recomendações

  1. Feche (e interrompa) todos os processos do Chrome antes de iniciar um novo usando as flags.
  2. Se estiver testando no seu ambiente local, desative chrome://flags/#privacy-sandbox-ads-apis, já que ele substitui as configurações da linha de comando, revertendo para os valores padrão.
  3. Use a página de depuração para entender como a API Topics está funcionando localmente.
  4. Se tiver dúvidas, confira a explicação em Problemas do GitHub (link em inglês).
  5. Se a API não funcionar como esperado, tente nossas dicas de solução de problemas.

Planejar a implantação do MVP

A API Topics dá acesso a temas de interesse observados para um usuário, sem ter que recorrer ao rastreamento dos sites que o usuário visita ou à exposição do histórico de navegação.

O autor da chamada da API Topics é a entidade que chama o método JavaScript document.browsingTopics() ou observa e acessa temas usando cabeçalhos de solicitação HTTP. Nesse caso, seu código e o eTLD+1 dele é chamado. Ao chamar a API Topics, você está instruindo o navegador do usuário a observar os temas de interesse quando ele visita um site. Essa visita é considerada no cálculo de temas para a próxima época.

A API Topics foi projetada para filtrar resultados por autor da chamada ou por eTLD+1 do contexto de chamada. Em outras palavras, a origem do iframe (ao usar a API JavaScript) ou o URL da solicitação de busca (ao usar cabeçalhos) é considerada o autor da chamada, e os tópicos são calculados de acordo com esse autor.

O diagrama a seguir ilustra essa abordagem:

As etapas que a API Topics segue quando os usuários visitam sites que usam a API.
Como a API observa e acessa temas.

Neste diagrama:

  1. Um usuário abre o Chrome e visita vários sites (customerA.example, customerB.example.br etc.) que incluem o iframe da adtech (fonte: iframe.adtech.example) ou os cabeçalhos de transferência de chamadas de busca.
    • O Chrome registrará os temas de interesse deste usuário.
  2. Depois de navegar por sete dias, com temas de interesse sendo observados pela API Topics, o mesmo usuário no mesmo dispositivo acessa um site de destino (editor, por exemplo). A API Topics retorna uma lista de temas e, neste exemplo específico, um tema calculado a partir da semana anterior de observações desse usuário vai ser retornado.
    • Somente os navegadores de usuários que visitaram sites que o adtech.example observou na Etapa 1 vão retornar resultados de temas na Etapa 2 (chamamos essa filtragem de observação, porque não é possível ver temas de usuários que você nunca viu antes).
  3. Com esta lista (de um tópico por enquanto), você pode chamar sua API de back-end (ads.adtech.example/topics-backend) para usar dados de tópicos como parte de seu conjunto de dados contextual.
  4. Agora, dependendo do seu caso de uso, é possível criar uma experiência mais personalizada para esse usuário acessando os temas de interesse que você observou nas últimas semanas.

Chamar a API Topics

Há duas maneiras de observar e acessar os temas para um usuário. É possível usar o

  • A API JavaScript em um iframe:
    • Adição de um iframe em sites de destino (sites do editor) que contêm código JavaScript chamando a API Topics usando document.browsingTopics().
  • Opção de cabeçalhos:
    • Buscar (recomendado) ou XHR (não recomendado e só estava disponível durante o teste de origem concluído):
      • É possível acessar temas do cabeçalho Sec-Browsing-Topics nas solicitações para o back-end da adtech. Essa é a opção de melhor performance (baixa latência para observar temas de um usuário específico).
    • Como usar uma tag de iframe com o atributo browsingtopics:
      • É possível adicionar um iframe com um atributo browsingtopics. O Chrome vai incluir temas (observados para o eTLD+1 do iframe) no cabeçalho Sec-Browsing-Topics na solicitação do iframe.

Implementar com JavaScript e iframes

Recomendamos que você bifurque a demonstração da API JavaScript ou a demonstração do cabeçalho da API Topics e use uma delas como ponto de partida para seu código.

É possível incluir um elemento <iframe> no HTML ou adicionar um iframe dinamicamente com JavaScript. Uma forma de criar dinamicamente um iframe é usar o seguinte JavaScript:

const iframe = document.createElement('iframe');
iframe.setAttribute('src', 'https://...');
document.body.appendChild(iframe);

Use a detecção de recursos para verificar se a API Topics tem suporte e está disponível neste dispositivo:

'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');

Chame a API Topics a partir desse iframe:

const topics = await document.browsingTopics();

Você deve receber uma lista dos temas observados para esse usuário nas últimas três semanas. Esta lista pode estar vazia ou incluir um, dois ou três tópicos das últimas três semanas.

Veja um exemplo do que a API retorna:

[{'configVersion': String, 
  'modelVersion': String, 
  'taxonomyVersion': String, 
  'topic': Number, 
  'version': String}]
  • configVersion: uma string que identifica a configuração atual.
  • modelVersion: uma string que identifica o classificador de aprendizado de máquina usado para inferir temas.
  • taxonomyVersion: string que identifica o conjunto de temas atualmente em uso pelo navegador.
  • topic: um número que identifica o tema na taxonomia.
  • version: uma string que combina configVersion e modelVersion.

Leia mais sobre essa implementação.

Implementar com cabeçalhos HTTP

Os tópicos podem ser acessados pelo cabeçalho Sec-Browsing-Topics de uma solicitação fetch()/XHR ou de uma solicitação iframe.

Cabeçalhos de solicitação e resposta para definir e recuperar tópicos.
Cabeçalhos para iframe e fetch().

Para marcar tópicos fornecidos pelos cabeçalhos da solicitação como observados, defina um cabeçalho Observe-Browsing-Topics: ?1 na resposta à solicitação. O navegador usará esses temas para calcular os temas de interesse de um usuário.

Se a API retornar um ou mais temas, uma solicitação de busca para o eTLD+1 em que os temas foram observados vai incluir um cabeçalho Sec-Browsing-Topics como este: 

(325);v=chrome.1:1:1, ();p=P000000000

Se a API não retornar nenhum tópico, o cabeçalho terá esta aparência:

();p=P0000000000000000000000000000000

Os valores do cabeçalho Sec-Browsing-Topics são preenchidos para reduzir o risco de um invasor descobrir o número de temas do autor da chamada com base no tamanho do cabeçalho.

Implementar com fetch()

Na página do editor, adicione seu código para a solicitação de busca, incluindo {browsingTopics: true}.

fetch('<topics_caller_eTLD+1>', {browsingTopics: true})
    .then((response) => {
        // Process the response
 })

Em navegadores compatíveis com a API, a solicitação fetch() vai incluir um cabeçalho Sec-Browsing-Topics que lista os tópicos observados para o nome do host do URL da solicitação.

Implementar com um iframe

Da mesma forma que uma solicitação fetch(), o cabeçalho Sec-Browsing-Topics será enviado ao usar o atributo browsingtopics em um iframe.

<iframe src="<topics_caller_eTLD+1>" browsingtopics></iframe>

Nesse caso, será o autor da chamada, semelhante à chamada de busca.

Lado do servidor: idêntico para todos os casos

Para que os temas no cabeçalho da solicitação Sec-Browsing-Topics sejam marcados pelo navegador como observado, mas também para incluir a visita atual à página no cálculo de tema principal da próxima época do usuário, a resposta do servidor precisa incluir Observe-Browsing-Topics: ?1.

Confira um exemplo de JavaScript usando setHeader():

res.setHeader('Observe-Browsing-Topics', '?1');

Implementação de back-end da API Topics

A adição de um back-end para a API Topics é opcional. Sua escolha depende de como e onde você quer usar os temas calculados no dispositivo (no navegador). 

// Use the language/framework/stack of your preference
function processTopicsBackendAPI(topics, user, domain, caller) {
  // Validate inputs
  // If the list is not empty, continue
  // Use topics as an additional contextual signal
}

Usar tópicos como dados contextuais

Os dados da API Topics podem ser considerados com outros indicadores, como URLs, palavras-chave e até tags, como um indicador adicional sobre seu público-alvo.

Conforme explicado em Maximizar a relevância do anúncio após cookies de terceiros, há várias abordagens para usar a API Topics para veicular anúncios relevantes. Alguns deles envolvem o uso de temas para criar públicos-alvo, e outros sugerem usar a API Topics como um indicador, entre outros, para treinar modelos de aprendizado de máquina que vão ser usados para inferir outros interesses do público-alvo ou até mesmo otimizar a lógica de lances.

Criar e implantar

  1. Colete temas observando os usuários na produção ainda não dimensionada (tempo estimado: aproximadamente 1 semana)
    1. Entenda suas opções: iframe e JavaScript ou cabeçalhos HTTP
    2. Defina o domínio do iframe.
    3. Crie o código JavaScript usando o app de demonstração como referência de código ou implemente a opção de cabeçalhos.
    4. Implante a API Topics no ambiente controlado (alguns sites de produção).
    5. Adicione a implementação da API Topics a alguns sites de destino (no momento, no máximo cinco sites).
    6. Validação e teste funcional.
  2. [Opcional] Use os dados da API Topics como um indicador de contexto (com URLs, tags etc.) (Tempo estimado: cerca de três dias).
    1. Depois de receber a lista de tópicos, você pode enviá-la para seu back-end com outros sinais de contexto.

Implantar em alguns sites de destino

Agora que você tem o código, vamos adicioná-lo a alguns sites de destino para um primeiro teste e para garantir que a API seja estável e funcione nesse ambiente controlado.

Recomendamos que você escolha sites de destino que:

  • Receber um pequeno número de visitas mensais (menos de um milhão de visitas/mês): comece implantando a API para um público-alvo pequeno primeiro.
  • Você tem a propriedade e controla: se necessário, é possível desativar rapidamente a implementação sem aprovações complexas.
  • Não são essenciais para os negócios: como essa implementação pode atrapalhar a experiência do usuário, comece com sites segmentados de baixo risco.
  • Total de cinco sites no máximo: você não vai precisar de tanto tráfego ou exposição por enquanto.
  • Representam temas diferentes: escolha sites que representem diferentes categorias (por exemplo, um sobre esportes, outro sobre notícias, mais um sobre alimentos e bebidas etc.). Você pode usar a ferramenta de tópicos internos no Chrome para validar domínios e como eles são classificados pelo classificador de aprendizado de máquina da API Topics. Saiba mais sobre depuração no guia para desenvolvedores da API Topics.

Teste e validação funcional

Ao chamar a API Topics nesse ambiente limitado, você pode esperar:

  • Uma matriz vazia de temas [], se esta for a primeira chamada desse dispositivo para o site e o autor da chamada nos últimos sete dias.
  • Uma lista de zero a três temas que representam os interesses desse usuário.
  • Após sete dias de observação, você receberá:
    • Um tema que representa o interesse desse usuário calculado a partir do histórico de navegação da semana.
      • Um detalhe importante: se você não observar temas suficientes para que a API Topics calcule os cinco principais temas da semana, a API Topics vai adicionar quantos temas aleatórios for necessário para chegar ao número total de cinco. Confira mais detalhes sobre a API.
  • Uma nova entrada de tópico substituindo um dos três se você estiver chamando-o após quatro semanas de observação.
    • Isso acontece porque a API Topics vai ficar estável nas semanas seguintes e não vai expor muitos interesses dos usuários. Confira mais detalhes no GitHub.
  • Se você não tiver observado temas para o usuário por mais de três semanas, a API Topics vai retornar uma matriz vazia [] de novo.

Avalie a performance e as métricas da experiência do usuário.

  • O tempo de execução das chamadas JavaScript para a API Topics em um iframe de origem cruzada precisa ser medido para ser usado em análises de desempenho futuras. Colete e armazene os dados de telemetria corretamente no back-end.
    • O tempo necessário para criar um iframe e postMessage() tópicos, depois que os temas são recebidos, também é outra métrica possível a ser calculada.

Solução de problemas

Estou chamando a API Topics, mas o resultado é nulo. E agora?
Se você está chamando a API Topics na primeira semana após observar um usuário, isso é esperado.

Principais recomendações

  1. Teste seu código de front-end para garantir que seu JavaScript esteja funcionando conforme o esperado.

  2. Teste seu back-end para receber os resultados dos tópicos.

    1. Não se esqueça de garantir que os tipos de dados e os parâmetros da API de back-end estejam configurados corretamente.
    2. Verifique se o back-end está configurado para escalonar corretamente.

  3. Com base na nossa experiência, é necessário aguardar pelo menos três semanas antes de começar a receber resultados de temas mais relevantes.

  4. A API Topics não está ativada para todos os usuários:

    1. Os usuários podem desativar explicitamente a API Topics.
    2. As páginas do editor podem controlar a política de permissões. Consulte (desativar) o guia para desenvolvedores da API Topics.
    3. Acesse chromestatus.com para saber mais detalhes.

  5. Adicione métricas e observabilidade a esse ambiente. Elas serão necessárias para analisar os primeiros resultados. Entre os exemplos de métricas estão:

    1. Latência de chamadas
    2. Erros HTTP em chamadas de temas

  6. Tente limitar as alterações em sua implementação durante as três semanas iniciais.

Escalonar para produção

Confira um resumo passo a passo de como escalonar para produção. As etapas são explicadas abaixo.

  1. Dimensionar a implementação (produção). Isso é descrito abaixo.
    1. Adicionar o iframe aos sites de vários editores.
  2. Processar e usar dados de temas (tempo estimado: cerca de quatro semanas).
    1. Incorporar dados de tópicos como um indicador adicional com outros dados.
    2. Conseguir parceiros de teste de lances em tempo real.
    3. Execute testes de utilidade com tópicos como um sinal adicional para seus outros dados.

Escalonar sua implementação

Neste ponto, os dados dos temas estão sendo coletados de alguns sites em um ambiente controlado, com um nível maior de confiança sobre a solução como um todo.

Agora é hora de escalonar essa implementação implantando o mesmo código em mais sites de destino. Assim, você poderá observar mais usuários, coletar mais dados sobre temas e aprofundar sua compreensão sobre seus públicos-alvo.

Recomendamos o seguinte:

  1. Implante de forma gradual nos seus sites, principalmente se você tiver um grande volume de tráfego.
  2. Faça testes de carga para os dados dos seus tópicos, de acordo com o tráfego esperado.
    1. Confirme se seu back-end pode lidar com um grande volume de chamadas.
    2. Configurar a coleta de métricas e registros para análise.
  3. Imediatamente após implantar a API Topics, verifique suas métricas para detectar problemas graves dos usuários finais. Verifique suas métricas regularmente.
  4. Em caso de interrupção ou comportamento inesperado, reverta a implantação e analise os registros para entender e corrigir o problema.

Interaja e compartilhe feedback