Implementa la API de Topics

En esta página, se explican los detalles de implementación que deben observar los llamadores de la API de Topics para acceder a los temas. Antes de comenzar a implementar tu solución, asegúrate de que tu navegador esté configurado correctamente. Consulta la sección de descripción general para obtener más información sobre cómo los llamadores observan y acceden a los temas de los usuarios.

Observa y accede a los temas

Hay dos formas de observar y acceder a los temas de un usuario: encabezados HTTP y la API de JavaScript.

Encabezados HTTP

El uso de encabezados HTTP es un enfoque recomendado para observar y acceder a los temas del usuario. Este enfoque puede ser mucho más eficiente que usar la API de JavaScript. Con los encabezados HTTP, la URL de la solicitud proporciona el dominio registrable que se registra como el dominio de la entidad llamadora. Este es el dominio que se observó que registró los temas del usuario.

Iniciar solicitud

Existen dos formas de usar Topics con encabezados:

  • Accediendo a los encabezados de solicitud y respuesta en una solicitud fetch() que incluye una opción browsingTopics: true
  • Accediendo a los encabezados de un elemento iframe que incluye un atributo browsingtopics
Inicia la solicitud con una recuperación

Con fetch, el llamador de la API realiza una solicitud que incluye {browsingTopics: true} en el parámetro de opciones. El origen del parámetro de URL de la solicitud de recuperación es el origen que se observó que tiene temas.

   fetch('<topics_caller_eTLD+1>', { browsingTopics: true })
    .then((response) => {
        // Process the response
    });
Cómo iniciar una solicitud con un iframe

Agrega el atributo browsingtopics al elemento <iframe>. El navegador incluirá el encabezado Sec-Browsing-Topics en la solicitud del iframe, con el origen del iframe como llamador.

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

Interpreta los valores de los encabezados de solicitud

En ambos enfoques (iframe y recuperación), los temas observados para un usuario se pueden recuperar en el servidor desde el encabezado de solicitud Sec-Browsing-Topics. La API de Topics incluirá automáticamente los temas del usuario en el encabezado de la solicitud de fetch() o iframe. Si la API devuelve uno o más temas, una solicitud de recuperación al origen desde el que se observaron los temas incluirá un encabezado Sec-Browsing-Topics como este:

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

Si la API no devuelve ningún tema, el encabezado se verá de la siguiente manera:

   ();p=P0000000000000000000000000000000

Se seguirán los redireccionamientos, y los temas enviados en la solicitud de redireccionamiento serán específicos de la URL de redireccionamiento. Los valores del encabezado Sec-Browsing-Topics se completan con caracteres de relleno para mitigar el riesgo de que un atacante conozca la cantidad de temas que se limitan a un llamador en función de la longitud del encabezado.

Cómo controlar la respuesta del servidor

Si la respuesta a la solicitud incluye un encabezado Observe-Browsing-Topics: ?1, esto indica que el navegador debe marcar los temas de la solicitud adjunta como observados y, luego, incluir la visita a la página actual en el cálculo de los temas de la próxima época del usuario. Incluye el encabezado Observe-Browsing-Topics: ?1 en la respuesta en tu código del servidor:

   res.setHeader('Observe-Browsing-Topics', '?1');
Encabezados de solicitud y respuesta para establecer y recuperar temas.
Encabezados para iframe y fetch().

Compartir temas observados con socios

Dado que las SSPs solo están presentes del lado del publicador, es posible que las DSPs quieran compartir con sus SSPs asociadas los temas que observan en los sitios de los anunciantes. Para ello, pueden realizar una solicitud fetch() con el encabezado de temas a las SSP desde el contexto de nivel superior del anunciante.

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

Cómo observar y acceder a los temas con JavaScript

El método document.browsingTopics() de la API de Topics en JavaScript proporciona una forma de observar y recuperar los temas de interés de un usuario en el entorno del navegador: - Registro de observación: Informa al navegador que el llamador observó que el usuario visitó la página actual. Esta observación contribuye al cálculo del tema del usuario para el llamador en épocas futuras. - Access Topics: Recupera los temas que el llamador observó anteriormente para el usuario. El método devuelve un array de hasta tres objetos de temas, uno para cada una de las épocas más recientes, en orden aleatorio.

Te recomendamos que bifurques la demostración de la API de Topics en JavaScript y la uses como punto de partida para tu código.

de disponibilidad de API

Antes de usar la API, asegúrate de que sea compatible y esté disponible:

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

Cómo incorporar un iframe

Se debe usar un iframe de origen cruzado para la llamada, ya que el contexto desde el que se invoca la API se usa para garantizar que el navegador devuelva los temas adecuados para el llamador. Incluye un elemento <iframe> en tu código HTML:

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

También puedes crear un iframe de forma dinámica con JavaScript:

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

Llama a la API desde el 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.
 }

De forma predeterminada, el método document.browsingTopics() también hace que el navegador registre la visita a la página actual según la observa el llamador, de modo que se pueda usar más adelante en el cálculo de temas. Se le puede pasar un argumento opcional al método para evitar que se registre la visita a la página: {skipObservation:true}.

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

Comprende la respuesta

Se muestra un máximo de tres temas: uno o cero para cada una de las últimas tres semanas, según si se observaron temas o no. Solo se devuelven los temas que el llamador observó para el usuario actual. Este es un ejemplo de lo que devuelve la API:

 [{
'configVersion': chrome.2,
 'modelVersion': 4,
 'taxonomyVersion': 2,
 'topic': 309,
 'version': chrome.2:2:4
}]
  • configVersion: Es una cadena que identifica la versión de configuración del algoritmo de temas del navegador.
  • modelVersion: Es una cadena que identifica el clasificador de aprendizaje automático que se usa para inferir temas.
  • taxonomyVersion: Es una cadena que identifica el conjunto de temas que usa el navegador.
  • topic: Es un número que identifica el tema en la taxonomía.
  • version: Es una cadena que concatena configVersion, taxonomyVersion y modelVersion. Los parámetros que se describen en esta guía y los detalles de la API (como el tamaño de la taxonomía, la cantidad de temas calculados por semana y la cantidad de temas que se muestran por llamada) están sujetos a cambios a medida que incorporamos comentarios del ecosistema e iteramos en la API.

Consulta la página Prueba y publica para saber qué respuesta esperar y cómo usar los temas como un indicador adicional para mostrar anuncios más relevantes.

Pasos siguientes

Aprende a implementar, probar y escalar soluciones basadas en Topics.
Obtén información sobre las herramientas disponibles en Chrome para ver información de la API de Topics, comprender cómo se asignan los temas y depurar tu implementación.

Consulta también

Consulta nuestros recursos para comprender mejor la API de Topics en la Web.