Guía de integración de la API de Topics

Aprende a usar la API de Topics para cumplir con casos de uso específicos de tecnología publicitaria.

Antes de comenzar

El primer paso es familiarizarte con la API y los servicios de Topics.

  1. Revisa la documentación para desarrolladores:
    1. Comienza por leer la descripción general para familiarizarte con la API de Topics y sus capacidades.
    2. Mira la explicación de la demostración de Topics (video).
    3. Prueba el encabezado de Topics y las demostraciones de la API de JavaScript.
    4. Bifurca las demostraciones (ambas proporcionan vínculos a su código) y ejecútalas desde tu propio sitio.
    5. Lee la explicación de la API para obtener más detalles.
  2. Verifica el estado de implementación y el cronograma de la API de Topics.
  3. Comprende el rol de la API para respaldar la relevancia de los anuncios en un futuro sin cookies.
  4. Para recibir notificaciones sobre los cambios de estado en la API, únete a la lista de distribución para desarrolladores y mantente al tanto de las actualizaciones más recientes de Topics.
  5. Mantente al tanto de las noticias más recientes sobre la API de Topics.
  6. Contribuye a la conversación mediante problemas de GitHub o llamadas de W3C.
  7. Si encuentras términos que no conoces, consulta el glosario de Privacy Sandbox.
  8. Para obtener más información sobre los conceptos de Chrome, como las marcas de Chrome, consulta los videos cortos y los artículos disponibles en goo.gle/cc.

Compila y prueba de manera local

En esta sección, se describe cómo probar la API de Topics como desarrollador individual.

  1. Implementación y pruebas locales (tiempo estimado: alrededor de 2 días)
    1. Habilita la API con tu navegador local desde la línea de comandos con marcas de función. Prueba las demostraciones del encabezado y de la API de JavaScript para ver Topics en acción (video explicativo).
    2. Ejecuta el Colab de Topics para probar la inferencia de temas mediante el modelo de aprendizaje automático de Topics.

Habilita Topics en tu navegador

Tienes dos opciones para habilitar la API de Topics en tu propia instancia de Chrome para realizar pruebas locales:

  1. Abre chrome://flags/#privacy-sandbox-ads-apis y habilita las APIs de Privacy Sandbox.
  2. (Recomendado) Ejecuta Chrome desde la línea de comandos con las marcas de Chromium con los parámetros específicos de la API de Topics para configurarlo según sea necesario.
Habilita las APIs de Privacy Sandbox en chrome://flags/#privacy-sandbox-ads-apis.
Habilitación de las APIs de Privacy Sandbox

Ejecuta Chrome desde la línea de comandos para tener un control más detallado sobre las funciones de Topics. Por ejemplo, es posible establecer ciclos de entrenamiento de Topics (el período que usa la API para calcular los intereses de los usuarios) y configurar el comportamiento de la API según tus necesidades.

Es importante recordar que, si chrome://flags/#privacy-sandbox-ads-apis está habilitada, se anulará la configuración de la época de la línea de comandos y se regresará al valor predeterminado (actualmente, una semana).

Vista previa de la mecánica de la API de Topics

Puedes obtener visibilidad de la mecánica subyacente de la API de Topics de forma local con las herramientas chrome://topics-internals.

Observa la API de Topics en chrome://topics-internals.
La pestaña Estado de Topics de las herramientas chrome://topics-internals.

Usa la herramienta Internals de la API de Topics para probar de forma local el clasificador en función de los sitios que visitas.

Con esta herramienta, puedes revisar lo siguiente:

  • Estado de los temas: Muestra los temas observados para el usuario actual.
  • Clasificador: Obtén una vista previa de los temas inferidos para los nombres de host.
  • Funciones y parámetros: Consulta los valores de los parámetros de la API para verificar que las marcas de función funcionen según lo previsto.

Aprende a depurar Topics con la herramienta Internals.

Cómo muestra temas la API

Si a Chrome le falta una cantidad suficiente de temas observados para crear los cinco temas principales de una época (una semana), la API de Topics agregará temas aleatorios para completar los cinco principales. La columna Topics Internals con el encabezado Real o Random indica si ese tema en particular se basó en una observación real o en un “padding” aleatorio adicional para completar los cinco primeros. Lee más sobre este mecanismo en la explicación.

El tema seleccionado para cada época se elige de forma aleatoria entre los cinco temas principales del usuario para ese período. Si no se observaron suficientes temas durante el ciclo de entrenamiento, se elegirán temas adicionales al azar para formar el total de cinco. Estos temas seleccionados de forma aleatoria están sujetos a filtros.

Para mejorar aún más la privacidad y garantizar que todos los temas estén representados, hay una probabilidad del 5% de que el tema seleccionado para un ciclo se elija de forma aleatoria entre todos los temas, en lugar de elegirse entre los temas observados. Al igual que en el caso anterior, en el que se observaron muy pocos temas, estos temas seleccionados al azar no están sujetos a filtros.

Puedes obtener más información sobre cómo se seleccionan los temas en el artículo de la clasificación de temas.

Recomendaciones clave

  1. Asegúrate de cerrar (y detener) todos los procesos de Chrome antes de iniciar el nuevo con las funciones experimentales.
  2. Si realizas pruebas en tu entorno local, debes inhabilitar chrome://flags/#privacy-sandbox-ads-apis, ya que anula la configuración de la línea de comandos y vuelve a los valores predeterminados.
  3. Utiliza la página de depuración para comprender cómo funciona Topics de forma local.
  4. Si tienes preguntas, consulta los problemas de GitHub para la explicación.
  5. Si la API no funciona como debería, prueba nuestras sugerencias para solucionar problemas.

Planifica la implementación de tu MVP

La API de Topics brinda acceso a temas de interés observados para un usuario, sin tener que recurrir a hacer un seguimiento de los sitios que visita el usuario ni exponer su historial de navegación.

El llamador de la API de Topics es la entidad que llama al método document.browsingTopics() de JavaScript o que observa temas y accede a ellos mediante encabezados de solicitud HTTP. Tu código y el eTLD+1 del que se llama, en esta instancia, es el emisor. Cuando llamas a la API de Topics, le indicas al navegador del usuario que observe los temas de interés cuando el usuario visite un sitio web. Esta visita se considera en el cálculo de temas para el próximo ciclo de entrenamiento.

La API de Topics está diseñada para filtrar resultados por emisor o por-eTLD+1 del contexto de llamada. En otras palabras, el origen del iframe (cuando se usa la API de JavaScript) o la URL de la solicitud de recuperación (cuando se usan encabezados) se considera como emisor, y los temas se calculan de acuerdo con ese llamador.

En el siguiente diagrama, se ilustra este enfoque:

Los pasos que realiza la API de Topics cuando los usuarios visitan sitios que usan la API.
Cómo la API observa los temas y accede a ellos.

En este diagrama, se muestra lo siguiente:

  1. Un usuario abre Chrome y visita varios sitios web (customerA.example, customerB.example.br, etc.) que incluyen el iframe de tu tecnología publicitaria (fuente: iframe.adtech.example) o los encabezados de transferencia de llamadas para la recuperación.
    • Chrome registrará temas de interés de este usuario.
  2. Después de siete días de navegación, con temas de interés observados por la API de Topics, el mismo usuario con el mismo dispositivo visita un sitio web objetivo (p. ej., publicador). La API de Topics muestra una lista de temas y, en este ejemplo específico, se mostrará un tema calculado a partir de la semana anterior de observaciones de este usuario.
    • Solo los navegadores de los usuarios que visitaron sitios que adtech.example observó en el paso 1 mostrarán resultados de temas en el paso 2 (a esto lo llamamos filtrado de observaciones; no puedes ver temas de usuarios que no hayas visto antes).
  3. Con esta lista (de un tema por ahora), puedes llamar a tu API de backend (ads.adtech.example/topics-backend) para usar datos de temas como parte de tu conjunto de datos contextuales.
  4. Ahora, según tu caso de uso, puedes crear una experiencia más personalizada para este usuario accediendo a los temas de interés que le has observado durante las últimas semanas.

Llama a la API de Topics

Existen dos maneras de observar los temas de un usuario y acceder a ellos. Puedes usar el modo

  • La API de JavaScript desde un iframe:
    • Agregar un iframe en los sitios web de destino (sitios web de publicadores) que contengan código JavaScript que llame a la API de Topics mediante document.browsingTopics()
  • Opción de encabezados:
    • Recuperación (que se recomienda) o XHR (no se recomienda y solo estaba disponible durante la prueba de origen completada):
      • Puedes acceder a los temas desde el encabezado Sec-Browsing-Topics en las solicitudes al backend de tecnología publicitaria. Esta es la opción de mejor rendimiento (latencia baja para observar temas de un usuario específico).
    • Usa una etiqueta de iframe con el atributo browsingtopics:
      • Puedes agregar un iframe con un atributo browsingtopics, y Chrome incluirá temas (observados para el eTLD+1 del iframe) en el encabezado Sec-Browsing-Topics de la solicitud del iframe.

Implementación con iframes y JavaScript

Te recomendamos bifurcar la demostración de la API de JavaScript de Topics o la demostración de encabezado y usar una de ellas como punto de partida para tu código.

Puedes incluir un elemento <iframe> en HTML o agregar un iframe de forma dinámica con JavaScript. Una forma de crear un iframe de forma dinámica es con el siguiente JavaScript:

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

Comprueba si la API de Topics es compatible y está disponible en este dispositivo a través de la detección de funciones:

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

Llama a la API de Topics desde ese iframe:

const topics = await document.browsingTopics();

Deberías recibir una lista de los temas observados para este usuario durante las últimas tres semanas. Recuerda que esta lista puede estar vacía o incluir 1, 2 o 3 temas, de las últimas tres semanas como máximo.

Este es un ejemplo de lo que muestra la API:

[{'configVersion': String, 
  'modelVersion': String, 
  'taxonomyVersion': String, 
  'topic': Number, 
  'version': String}]
  • configVersion: una string que identifica la configuración actual
  • modelVersion: Es una cadena que identifica el clasificador de aprendizaje automático que se usa para inferir los temas.
  • taxonomyVersion: Es una cadena que identifica el conjunto de temas que usa el navegador en este momento.
  • topic: Un número que identifica el tema en la taxonomía.
  • version: Es una cadena que combina configVersion y modelVersion.

Obtén más información sobre esta implementación.

Implementación con encabezados HTTP

Se puede acceder a los temas desde el encabezado Sec-Browsing-Topics de una solicitud fetch()/XHR o iframe.

Encabezados de solicitud y respuesta para configurar y recuperar temas.
Encabezados para iframe y fetch().

Para marcar los temas proporcionados por los encabezados de la solicitud como se observan, configura un encabezado Observe-Browsing-Topics: ?1 en la respuesta de la solicitud. Luego, el navegador utilizará esos temas para calcular temas de interés para un usuario.

Si la API muestra uno o más temas, una solicitud de recuperación al eTLD+1 desde el que se observaron los temas incluirá un encabezado Sec-Browsing-Topics como el siguiente: 

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

Si la API no muestra ningún tema, el encabezado tiene el siguiente aspecto:

();p=P0000000000000000000000000000000

Se rellenan los valores del encabezado Sec-Browsing-Topics para mitigar el riesgo de que un atacante aprenda la cantidad de temas que se limitan a un llamador en función de la longitud del encabezado.

Implementación con fetch()

En la página del publicador, agrega el código para la solicitud de recuperación y asegúrate de incluir {browsingTopics: true}.

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

En los navegadores compatibles con la API, la solicitud fetch() incluirá un encabezado Sec-Browsing-Topics que enumera los temas observados para el nombre de host de la URL de la solicitud.

Implementación con un iframe

Al igual que con una solicitud fetch(), el encabezado Sec-Browsing-Topics se enviará cuando se use el atributo browsingtopics en un iframe.

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

En este caso, será el llamador, de manera similar a la llamada de recuperación.

Del lado del servidor (idéntico para todos los casos)

Para que el navegador marque los temas del encabezado de la solicitud Sec-Browsing-Topics como los observa, pero también para incluir la visita a la página actual en el cálculo del tema principal del ciclo de entrenamiento siguiente del usuario, la respuesta del servidor debe incluir Observe-Browsing-Topics: ?1.

A continuación, verás un ejemplo de JavaScript con setHeader():

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

Implementación de backend de Topics

Agregar un backend para Topics es opcional. Tu elección depende de cómo y dónde quieras usar los temas calculados en el dispositivo (en el 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
}

Usa temas como datos contextuales

Los datos de temas se pueden considerar junto con otros indicadores, como URLs, palabras clave y hasta etiquetas, como un indicador adicional sobre tu público.

Como se explica en Maximizar la relevancia de los anuncios después de las cookies de terceros, existen varios enfoques para aprovechar Topics a fin de publicar anuncios relevantes. Algunas de estas implican el uso de temas para crear públicos, y otras sugieren usar Topics como un indicador entre otras para entrenar modelos de aprendizaje automático, que se utilizarán para inferir intereses adicionales del público o incluso para optimizar la lógica de ofertas.

Compila e implementa

  1. Observa a los usuarios en producción para recopilar temas (tiempo estimado: aproximadamente 1 semana)
    1. Información sobre las opciones: iframe y JavaScript o encabezados HTTP
    2. Define el dominio del iframe.
    3. Compila el código JavaScript con la app de demostración como referencia de código o implementa la opción de encabezados.
    4. Implementa Topics en tu entorno controlado (algunos sitios de producción).
    5. Agrega la implementación de Topics a algunos sitios de segmentación (en este momento, no más de cinco sitios).
    6. Validación y pruebas funcionales.
  2. Usa los datos de Topics como indicador contextual (con URLs, etiquetas, etcétera). [Opcional] Tiempo estimado: aproximadamente 3 días.
    1. Después de recibir la lista de temas, puedes enviarla a tu backend con otros indicadores contextuales.

Implementa en algunos sitios de destino

Ahora que tienes el código, agreguémoslo a algunos sitios de destino para realizar una primera prueba y asegurarnos de que la API sea estable y funcione en este entorno controlado.

Le recomendamos que elija sitios web orientados a los siguientes tipos de anuncios:

  • Obtener una pequeña cantidad de visitas mensuales (menos de 1 millón de visitas al mes): Primero, debes comenzar por implementar la API para un público pequeño.
  • Eres el propietario y el que controlas: Si es necesario, puedes inhabilitar rápidamente la implementación sin aprobaciones complejas.
  • No son fundamentales para la empresa: Dado que esta implementación puede interrumpir la experiencia del usuario, comienza con sitios segmentados de bajo riesgo.
  • En total, no más de cinco sitios: Por el momento, no necesitarás tanto tráfico ni tanto exposición.
  • Representar temas diferentes: Elige sitios web que representen diferentes categorías (por ejemplo, uno sobre deportes, otro sobre noticias, otro sobre comidas y bebidas, etcétera). Puedes usar la herramienta interna de temas en Chrome para validar los dominios y cómo se clasifican en el clasificador de aprendizaje automático de Topics. Obtén más información sobre la depuración en la guía para desarrolladores de la API de Topics.

Pruebas funcionales y validación

Cuando llamas a la API de Topics en este entorno limitado, puedes esperar lo siguiente:

  • Un array vacío de temas [] si esta es la primera llamada de este dispositivo para este sitio y el emisor en los últimos siete días.
  • Una lista de entre cero y tres temas que representan los intereses de este usuario.
  • Después de siete días de observación, deberías recibir lo siguiente:
    • Tema que representa el interés de ese usuario calculado a partir del historial de navegación de esa semana.
      • Un detalle importante: si no observaste suficientes temas para que un usuario de la API de Topics calcule los cinco temas principales de esa semana, Topics agregará tantos temas aleatorios como sea necesario para llegar a la cantidad total de cinco. Obtén más información sobre la API.
  • Una nueva entrada de tema que reemplazará una de las tres si la llamas después de cuatro semanas de observación.
    • Esto sucede porque la API de Topics permanecerá estable durante las siguientes semanas, sin exponer demasiados de los intereses del usuario. Obtén más información en GitHub.
  • Si no has observado temas para el usuario durante más de tres semanas, la API de Topics volverá a mostrar un array vacío [].

Mide el rendimiento y las métricas de la experiencia del usuario.

  • El tiempo de ejecución de las llamadas de JavaScript a la API de Topics dentro de un iframe de origen cruzado debe medirse para su uso en análisis de rendimiento futuros. Asegúrate de recopilar y almacenar los datos de telemetría correctamente en tu backend.
    • El tiempo que lleva crear un iframe y temas de postMessage() después de recibir los temas también es otra métrica que se puede calcular.

Solución de problemas

Llamo a la API de Topics, pero el resultado es nulo. ¿Qué puedo hacer?
Si llamas a la API de Topics durante la primera semana después de observar a un usuario, esto es lo que se espera.

Recomendaciones clave

  1. Prueba tu código de frontend para asegurarte de que JavaScript funciona como se espera.

  2. Prueba tu backend para recibir los resultados de los temas.

    1. Recuerda asegurarte de que los tipos de datos y los parámetros de la API de backend estén configurados correctamente.
    2. Asegúrate de que tu backend esté configurado para escalar de forma adecuada.

  3. Según nuestra experiencia, es necesario esperar al menos tres semanas antes de comenzar a obtener resultados de temas más relevantes.

  4. No todos los usuarios tendrán Topics habilitados:

    1. Los usuarios pueden inhabilitar la API de Topics de forma explícita.
    2. Las páginas del publicador pueden controlar la política de permisos. Consulta (inhabilitación) en la guía para desarrolladores de la API de Topics.
    3. Consulta chromestatus.com para obtener más detalles.

  5. Agrega métricas y observabilidad a este entorno: las necesitarás para analizar los primeros resultados. Algunos ejemplos de métricas son:

    1. Latencia de las llamadas;
    2. Errores de HTTP en llamadas a temas.

  6. Intenta limitar los cambios en tu implementación durante las tres semanas iniciales.

Escala para producción

A continuación, te presentamos un resumen paso a paso de cómo puedes escalar a producción. Los pasos se explican a continuación.

  1. Escala la implementación (producción). A continuación, se describe cómo hacerlo.
    1. Agrega el iframe a varios sitios web de publicadores.
  2. Procesa y usa datos de temas (tiempo estimado: alrededor de 4 semanas).
    1. Incorpora datos de temas como indicadores adicionales junto con otros datos.
    2. Consigue socios de prueba de ofertas en tiempo real.
    3. Ejecuta pruebas de utilidad con temas como indicador adicional de tus otros datos.

Escala tu implementación

En este punto, deberías tener datos de temas que se recopilan de algunos sitios en un entorno controlado, con un mayor nivel de confianza en toda la solución.

Ahora es momento de escalar esta implementación implementando el mismo código en más sitios web de destino. Esto te permitirá observar más usuarios, recopilar más datos de temas y profundizar tu comprensión de tus públicos.

Te recomendamos que hagas lo siguiente:

  1. Implementa gradualmente en tus sitios, especialmente si tienes un gran volumen de tráfico.
  2. Realiza pruebas de carga para los datos de tus temas según el tráfico esperado.
    1. Confirma que tu backend puede manejar un gran volumen de llamadas.
    2. Configurar la recopilación de métricas y registros para el análisis
  3. Inmediatamente después de implementar la API de Topics, verifica tus métricas para detectar cualquier problema grave del usuario final. Continúa revisando tus métricas periódicamente.
  4. En caso de interrupción o comportamiento inesperado, revierte la implementación y analiza tus registros para comprender y solucionar el problema.

Interactúa y comparte comentarios