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. Primero, lee la descripción general para ponerte al día con la API de Topics y sus capacidades.
    2. Mira la explicación de 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 comprender más detalles.
  2. Verifica el estado de la implementación y el cronograma de la API de Topics.
  3. Comprende la función de la API para respaldar la relevancia del anuncio 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. Participa en la conversación a través de problemas de GitHub o llamadas de W3C.
  7. Si encuentras términos desconocidos, consulta el glosario de Privacy Sandbox.
  8. Para obtener más información sobre los conceptos de Chrome, como las funciones experimentales 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 funciones. Prueba el encabezado y las demostraciones 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 con el modelo de aprendizaje automático de Topics.

Habilita Topics en tu navegador

Si quieres habilitar la API de Topics en tu propia instancia de Chrome para realizar pruebas locales, tienes dos opciones:

  1. Habilita todas las APIs de privacidad en los anuncios de chrome://settings/adPrivacy.
  2. (Recomendado) Ejecuta Chrome desde la línea de comandos con marcas de Chromium y usa parámetros específicos de la API de Topics para configurarlos según sea necesario.

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.

Mecánica de la API de Topics de vista previa

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

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

Usa la herramienta de componentes internos de la API de Topics para probar el clasificador de forma local 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.
  • Atributos 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.

Obtén más información para depurar Topics con la herramienta Internals.

Cómo muestra la API los temas

Si Chrome no tiene una cantidad suficiente de temas observados para crear los cinco temas principales de un ciclo de entrenamiento (una semana), la API de Topics agregará temas aleatorios para completar los cinco principales. La columna Topics Internals con el título 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 principales. Obtén más información 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 sumar 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 puedan estar representados, hay una probabilidad del 5% de que el tema seleccionado para un ciclo de entrenamiento se seleccione de forma aleatoria de todos los temas, en lugar de elegirse a partir de temas observados. Como en el caso anterior en el que se observaron muy pocos temas, estos temas seleccionados de forma aleatoria no están sujetos a filtros.

Puedes encontrar más información sobre cómo se seleccionan los temas en Clasificación de temas.

Recomendaciones clave

  1. Asegúrate de cerrar (y detener) todos los procesos de Chrome antes de iniciar uno nuevo con las marcas.
  2. Asegúrate de que todas las APIs de privacidad en los anuncios estén habilitadas en chrome://settings/adPrivacy.
  3. Usa la página de depuración para comprender cómo funciona Topics a nivel local.
  4. Cuando tengas preguntas, consulta los problemas de GitHub para ver la explicación.
  5. Si la API no funciona como debería, prueba nuestras sugerencias para la solución de problemas.

Planifica tu implementación de MVP

La API de Topics brinda acceso a los temas de interés observados para un usuario, sin tener que recurrir a hacer un seguimiento de los sitios que visita un 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 bien observa y accede a temas con encabezados de solicitud HTTP. Tu código y el eTLD+1 desde el que se llama, en este caso, es el emisor. Cuando llamas a la API de Topics, le indicas al navegador del usuario que observe los temas de interés cuando visita un sitio web. Esta visita se considera en el cálculo de temas para la siguiente época.

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 el llamador, y los temas se calculan según 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 la llamada de recuperación.
    • Chrome registrará los temas de interés de este usuario.
  2. Después de siete días de navegación, y la API de Topics observa los temas de interés, el mismo usuario, en el mismo dispositivo, visita un sitio web objetivo (publisher-e.example). La API de Topics muestra una lista de temas y, en este ejemplo específico, se muestra un tema calculado a partir de la semana anterior de observaciones de este usuario.
    • Solo los navegadores de los usuarios que visitaron los sitios que adtech.example observó en el paso 1 mostrarán los resultados de temas en el paso 2 (a esto lo llamamos filtro de observación, ya que no puede ver temas de usuarios que nunca antes vio).
  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 observaste durante las últimas semanas.

Llama a la API de Topics

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

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

Cómo implementar con iframes y JavaScript

Te recomendamos bifurcar la demostración de la API de JavaScript de Topics o la demostración del encabezado y usar una de estas 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 devuelve la API:

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

Obtenga más información sobre esta implementación.

Cómo implementar con encabezados HTTP

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

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

Puedes marcar los temas proporcionados por los encabezados de solicitud como observados estableciendo un encabezado Observe-Browsing-Topics: ?1 en la respuesta a la solicitud. El navegador luego utilizará esos temas para calcular los 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 devuelve temas, el encabezado se verá de la siguiente manera:

();p=P0000000000000000000000000000000

Se rellenan los valores del encabezado Sec-Browsing-Topics para mitigar el riesgo de que un atacante conozca la cantidad de temas definidos para un llamador según la longitud del encabezado.

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

Cómo implementar con un iframe

Al igual que 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, similar a la llamada de recuperación.

Del servidor: idéntico para todos los casos

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

Este es un ejemplo de JavaScript con setHeader():

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

Implementación del 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 los 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 el artículo Cómo maximizar la relevancia de los anuncios después de las cookies de terceros, existen varios enfoques para aprovechar Topics para publicar anuncios relevantes. Algunas de estas prácticas implican usar temas para crear públicos, y otras sugieren usar Topics como un indicador, entre otros, para entrenar modelos de aprendizaje automático que se usarán para inferir los intereses adicionales del público o incluso optimizar la lógica de ofertas.

Compila e implementa

  1. Recopila temas observando a los usuarios que están en producción, sin escalar aún (tiempo estimado: aproximadamente 1 semana).
    1. Comprende tus opciones: iframe y JavaScript o los 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. Pruebas funcionales y validación.
  2. [Opcional] Usa datos de Topics como indicador contextual (con URLs, etiquetas, etcétera). Tiempo estimado: alrededor de 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, agrégalo 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 los sitios web de orientación que:

  • Obtener una pequeña cantidad de visitas mensuales (menos de 1 millón de visitas por mes): Primero, debes implementar la API para un público pequeño para un público pequeño.
  • Eres el propietario y tienes el control: Si es necesario, puedes inhabilitar la implementación rápidamente sin aprobaciones complejas.
  • No son fundamentales para la empresa: Dado que esta implementación puede alterar la experiencia del usuario, comienza con sitios objetivo de bajo riesgo.
  • Total de cinco sitios: No necesitarás tener tanto tráfico ni exposición por el momento.
  • Representa temas diferentes: Elige sitios web que representen diferentes categorías (por ejemplo, uno sobre deportes, otro sobre noticias, otro sobre comidas y bebidas, etc.). Puedes usar la herramienta interna de temas en Chrome para validar dominios y cómo se clasifican mediante 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 llames 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 representa los intereses de este usuario.
  • Después de siete días de observación, deberías recibir lo siguiente:
    • Un tema que representa el interés de ese usuario y se calcula 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 reemplaza una de las tres si la llamas después de cuatro semanas de observación.
    • Esto sucede porque la API de Topics se mantendrá estable durante las siguientes semanas y no expondrá demasiados intereses del usuario. Obtén más información en GitHub.
  • Si no observaste 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.

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

Solución de problemas

Estoy llamando a la API de Topics, pero recibo un valor nulo. ¿Qué puedo hacer?
Si llamas a la API de Topics en la primera semana de observar a un usuario, esto es lo esperado.

Recomendaciones clave

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

  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, debes 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 explícitamente la API de Topics.
    2. Las páginas del publicador pueden controlar la política de permisos. Consulta la sección (inhabilitación) en la guía para desarrolladores de la API de Topics.
    3. Para obtener más información, consulta chromestatus.com.

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

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

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

Escalamiento a producción

Este es 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). Esto se describe a continuación.
    1. Agregar el iframe a los sitios web de varios publicadores
  2. Procesar y usar datos de temas (tiempo estimado: alrededor de 4 semanas)
    1. Incorpora datos de temas como indicador aditivo junto con otros datos.
    2. Busca socios de prueba de ofertas en tiempo real.
    3. Ejecuta pruebas de utilidad con temas como un indicador aditivo para tus otros datos.

Escala tu implementación

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

Ahora es el momento de escalar esta implementación. Para ello, debes implementar el mismo código en más sitios web objetivo. Esto te permitirá observar a 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. Realiza implementaciones de forma gradual en tus sitios, en especial si tienes un gran volumen de tráfico.
  2. Realiza pruebas de carga para los datos de tus temas de acuerdo con el tráfico esperado.
    1. Confirma que tu backend puede manejar un gran volumen de llamadas.
    2. Configura la recopilación de métricas y los registros para el análisis.
  3. Inmediatamente después de implementar la API de Topics, verifica tus métricas para detectar cualquier problema grave de los usuarios finales. Sigue revisando tus métricas periódicamente.
  4. Si ocurre una interrupción o un comportamiento inesperado, revierte la implementación y analiza tus registros para comprender y solucionar el problema.

Interactúa y comparte comentarios