Implementar a API Topics

Nesta página, explicamos os detalhes da implementação para que os chamadores da API Topics observem e acessem tópicos. Antes de começar a implementar sua solução, verifique se o navegador está configurado corretamente. Confira a seção de visão geral para saber mais sobre como os chamadores observam e acessam os temas dos usuários.

Observar e acessar tópicos

Há duas maneiras de observar e acessar os temas de um usuário: cabeçalhos HTTP e API JavaScript.

Cabeçalhos HTTP

Usar cabeçalhos HTTP é uma abordagem recomendada para observar e acessar temas de interesse do usuário. Essa abordagem pode ter uma performance muito melhor do que usar a API JavaScript. Com cabeçalhos HTTP, o URL da solicitação fornece o domínio registrável que é gravado como o domínio do chamador. É o domínio que observou os temas do usuário.

Iniciar solicitação

Há duas maneiras de usar a API Topics com cabeçalhos:

  • Ao acessar cabeçalhos de solicitação e resposta em uma solicitação fetch() que inclui uma opção browsingTopics: true.
  • Ao acessar cabeçalhos de um elemento iframe que inclui um atributo browsingtopics.
Iniciar solicitação com uma busca

Usando o fetch, o chamador da API faz uma solicitação que inclui {browsingTopics: true} no parâmetro de opções. A origem do parâmetro de URL da solicitação de busca é a origem que parece ter observado tópicos.

   fetch('<topics_caller_eTLD+1>', { browsingTopics: true })
    .then((response) => {
        // Process the response
    });
Iniciar solicitação com um iframe

Adicione o atributo browsingtopics ao elemento <iframe>. O navegador vai incluir o cabeçalho Sec-Browsing-Topics na solicitação do iframe, com a origem dele como o chamador.

   <iframe src="https://adtech.example" browsingtopics></iframe>

Interpretar valores de cabeçalho de solicitação

Para as duas abordagens (busca e iframe), os temas observados para um usuário podem ser recuperados no servidor do cabeçalho de solicitação Sec-Browsing-Topics. A API Topics vai incluir automaticamente os temas do usuário no cabeçalho em uma solicitação fetch() ou iframe. Se a API retornar um ou mais temas, uma solicitação de busca para a origem de onde os temas foram observados vai incluir um cabeçalho Sec-Browsing-Topics como este:

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

Se nenhum tema for retornado pela API, o cabeçalho vai ficar assim:

   ();p=P0000000000000000000000000000000

Os redirecionamentos serão seguidos, e os tópicos enviados na solicitação de redirecionamento serão específicos do URL de redirecionamento. Os valores do cabeçalho Sec-Browsing-Topics são preenchidos para reduzir o risco de um invasor descobrir o número de temas no escopo de um autor da chamada com base no comprimento do cabeçalho.

Processar resposta do lado do servidor

Se a resposta à solicitação incluir um cabeçalho Observe-Browsing-Topics: ?1, isso vai indicar que o navegador deve marcar os temas da solicitação acompanhante como observados e incluir a visita à página atual no próximo cálculo de temas da época do usuário. Inclua o cabeçalho Observe-Browsing-Topics: ?1 na resposta no código do lado do servidor:

   res.setHeader('Observe-Browsing-Topics', '?1');
Cabeçalhos de solicitação e resposta para definir e recuperar tópicos.
Cabeçalhos para iframe e fetch().

Compartilhar tópicos observados com parceiros

Como as SSPs estão presentes apenas no lado do publisher, as DSPs podem compartilhar com as SSPs parceiras os temas que observam nos sites do anunciante. Para isso, basta fazer uma solicitação fetch() com o cabeçalho de tópicos para as SSPs no contexto de nível superior do anunciante.

const response = await fetch("partner-ssp.example", {
 browsingTopics: true
});

Observar e acessar tópicos com JavaScript

O método document.browsingTopics() da API JavaScript Topics oferece uma maneira de observar e recuperar os temas de interesse de um usuário no ambiente do navegador: - Registrar observação:informa ao navegador que o autor da chamada observou o usuário visitando a página atual. Essa observação contribui para o cálculo do tema do usuário para o autor da chamada em épocas futuras. - Acessar temas:recupera temas que o autor da chamada observou anteriormente para o usuário. O método retorna uma matriz de até três objetos de tema, um para cada uma das épocas mais recentes, em ordem aleatória.

Recomendamos que você crie um fork da demonstração da API JavaScript de tópicos e a use como ponto de partida para seu código.

de disponibilidade da API

Antes de usar a API, verifique se ela é compatível e está disponível:

 if ('browsingTopics' in document && document.featurePolicy.allowsFeature('browsing-topics')) {
    console.log('document.browsingTopics() is supported on this page');
 } else {
    console.log('document.browsingTopics() is not supported on this page');
 }

Incorporar um iframe

Um iframe de origem cruzada precisa ser usado para a chamada, porque o contexto de onde a API é invocada é usado para garantir que o navegador retorne os temas adequados ao autor da chamada. Inclua um elemento <iframe> no seu HTML:

<iframe src="https://example.com" browsingtopics></iframe>

Também é possível criar um iframe dinamicamente usando JavaScript:

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

Chamar a API de dentro do iframe

 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.
 }

Por padrão, o método document.browsingTopics() também faz com que o navegador registre a visita à página atual, conforme observado pelo caller, para que possa ser usado posteriormente no cálculo de temas. O método pode receber um argumento opcional para evitar que a visita à página seja registrada: {skipObservation:true}.

 // current page won't be included in the calculation of topics:
 const topics = await document.browsingTopics({skipObservation:true});

Entender a resposta

Um máximo de três temas é retornado: um ou zero para cada uma das últimas três semanas, dependendo se os temas foram observados ou não. Somente os temas observados pelo autor da chamada para o usuário atual são retornados. Confira um exemplo do que a API retorna:

 [{
'configVersion': chrome.2,
 'modelVersion': 4,
 'taxonomyVersion': 2,
 'topic': 309,
 'version': chrome.2:2:4
}]
  • configVersion: uma string que identifica a versão da configuração do algoritmo de tópicos do navegador.
  • modelVersion: uma string que identifica o classificador de aprendizado de máquina usado para inferir temas.
  • taxonomyVersion: uma string que identifica o conjunto de temas em uso pelo navegador.
  • topic: um número que identifica o tema na taxonomia.
  • version: uma string que concatena configVersion, taxonomyVersion e modelVersion. Os parâmetros descritos neste guia e os detalhes da API, como tamanho da taxonomia, número de temas calculados por semana e número de temas retornados por chamada, estão sujeitos a mudanças à medida que o feedback do ecossistema é incorporado e a iteração da API é feita.

Consulte a página Testar e publicar para saber qual resposta esperar e como usar os temas como um indicador adicional para anúncios mais relevantes.

Próximas etapas

Saiba como implantar, testar e dimensionar soluções baseadas em tópicos.
Saiba mais sobre as ferramentas disponíveis no Chrome para conferir informações da API Topics, entender como os temas são atribuídos e depurar sua implementação.

Consulte também

Confira nossos recursos para entender melhor a API Topics na Web.