Guía para desarrolladores de la API de Topics

Aprende a trabajar con la API, incluidas las funciones experimentales de Chrome para realizar pruebas.

Estado de implementación

Probar demostración

Hay dos demostraciones de la API de Topics que te permiten probar Topics como un solo usuario.

También puedes ejecutar la colab de Topics para probar el modelo de clasificación de Topics.

Usar la API de JavaScript para acceder a los temas y registrarlos según lo observado

La API de Topics JavaScript tiene un método: document.browsingTopics(). Esto tiene dos propósitos:

  • Indica al navegador que registre la visita a la página actual como se observó para el emisor, de modo que más tarde pueda usarse para calcular los temas del usuario (para el llamador).
  • Temas de acceso para el usuario que observó el llamador.

El método muestra una promesa que se resuelve en un array de hasta tres temas, uno para cada uno de los tres ciclos de entrenamiento más recientes, en orden aleatorio. Un ciclo de entrenamiento es un período de tiempo que se establece en una semana en la implementación de Chrome.

Cada objeto de tema del array que muestra document.browsingTopics() tiene las siguientes propiedades:

  • configVersion: Es una cadena que identifica la configuración actual de la API de Topics, por ejemplo, chrome.2.
  • modelVersion: Es una cadena que identifica el clasificador de aprendizaje automático que se usa para inferir los temas del sitio, por ejemplo, 4.
  • taxonomyVersion: Es una cadena que identifica el conjunto de temas que usa el navegador, por ejemplo, 2.
  • topic: Es un número que identifica el tema en la taxonomía, por ejemplo, 309.
  • version: Es una cadena que concatena configVersion, taxonomyVersion y modelVersion, por ejemplo, chrome.2:2:4.

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 sobre el ecosistema y iteramos en la API.

Cómo detectar compatibilidad con document.browsingTopics

Antes de usar la API, comprueba si es compatible con el navegador y si está disponible en el documento:

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

Accede a temas con la API de JavaScript

A continuación, se muestra un ejemplo básico de un posible uso de la API para acceder a los temas del usuario actual.

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

Accede a temas sin modificar el estado

document.browsingTopics() muestra los temas que observa el llamador para el usuario actual. De forma predeterminada, el método también hace que el navegador registre la visita a la página actual tal como la observa el emisor, de modo que más adelante se pueda usar para el cálculo de temas. A partir de Chrome 108, se puede pasar al método un argumento opcional para evitar que se registre la visita a la página: {skipObservation:true}.

En otras palabras, {skipObservation:true} significa que la llamada de método no hará que se incluya la página actual en el cálculo de temas.

Usar encabezados para acceder a los temas y marcarlos como observados

Puedes acceder a los temas y marcar las visitas a la página como observadas con la ayuda de los encabezados de solicitud y respuesta. Usar el enfoque de encabezado puede tener un rendimiento mucho mayor que llamar a la API de JavaScript.

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

Configurar un encabezado Observe-Browsing-Topics: ?1 en la respuesta a la solicitud hace que el navegador registre la visita a la página actual tal como la observa el llamador, de modo que se pueda usar más adelante para el cálculo de temas.

Se puede acceder a los temas y observarlos con encabezados HTTP de dos maneras:

  • fetch(): Agrega {browsingTopics: true} al parámetro de opciones de una solicitud fetch(). La demostración del encabezado de Topics muestra un ejemplo simplificado de esto.
  • Atributo de iframe: Agrega el atributo browsingtopics a un elemento <iframe> o establece la propiedad de JavaScript equivalente iframe.browsingTopics = true. El dominio registrable de la fuente de iframe es el dominio del emisor; por ejemplo, para <iframe src="https://example.com" browsingtopics></iframe>, el llamador es example.com.

Notas adicionales sobre los encabezados:

  • Se seguirán los redireccionamientos, y los temas enviados en la solicitud de redireccionamiento serán específicos de la URL de redireccionamiento.
  • El encabezado de la solicitud no modificará el estado del emisor, a menos que haya un encabezado de respuesta correspondiente. Es decir, sin el encabezado de respuesta, la visita a la página no se registrará como se observa, por lo que no afectará el cálculo del tema del usuario para el siguiente ciclo de entrenamiento.
  • El encabezado de respuesta solo se respeta si la solicitud correspondiente incluyó el encabezado de temas.
  • La URL de la solicitud proporciona el dominio registrable que se registra como el dominio del emisor.

Depura la implementación de tu API

La página chrome://topics-internals estará disponible en Chrome para computadoras de escritorio una vez que habilites la API de Topics. Se mostrarán temas del usuario actual, temas inferidos para los nombres de host e información técnica sobre la implementación de la API. Estamos iterando y mejorando el diseño de la página en función de los comentarios de los desarrolladores. Puedes agregar tus comentarios en bugs.chromium.org.

Ver temas calculados para tu navegador

Los usuarios pueden ver información sobre los temas observados en su navegador durante el ciclo de entrenamiento actual y el anterior si consultan chrome://topics-internals.

La página chrome://topics-internals con el panel Topics State seleccionado.
El panel Estado de temas de la página chrome://topics-internals muestra los IDs de tema, las asignaciones de temas aleatorias y reales, y las versiones de taxonomía y de modelos.

Esta captura de pantalla muestra que los sitios visitados recientemente incluyen topics-demo-cats.glitch.me y cats-cats-cats-cats.glitch.me. Esto hace que la API de Topics seleccione Pets y Cats como dos de los temas principales para el ciclo de entrenamiento actual. Los tres temas restantes se elegieron de forma aleatoria, ya que no hay suficiente historial de navegación (en sitios que analizan temas) para proporcionar cinco temas.

La columna Dominios de contexto observados (con hash) proporciona el valor de hash de un nombre de host para el que se observó un tema.

Ver temas inferidos para nombres de host

También puedes ver los temas que infiere el modelo de clasificación de Topics para uno o más nombres de host en chrome://topics-internals.

La página chrome://topics-internals con el panel Clasificador seleccionado.
El panel Clasificador de la página chrome://topics-internals muestra los temas seleccionados, los hosts visitados, y la versión y la ruta del modelo.

La implementación actual de la API de Topics infiere temas solo a partir de nombres de host, no de cualquier otra parte de una URL.

Usa solo nombres de host (sin protocolo ni ruta de acceso) para ver los temas inferidos del clasificador chrome://topics-internals. chrome://topics-internals mostrará un error si intentas incluir una "/" en el campo Host.

Ver información de la API de Topics

Puedes encontrar información sobre la implementación y la configuración de la API de Topics, como la versión de taxonomía y la duración de la época, en chrome://topics-internals. Estos valores reflejan la configuración predeterminada de la API o los parámetros que se establecieron correctamente desde la línea de comandos. Esto puede ser útil para confirmar que las marcas de línea de comandos funcionaron según lo esperado.

En el ejemplo, se estableció time_period_per_epoch en 15 segundos (el valor predeterminado es siete días).

Página chrome://topics-internals con el panel Funciones y parámetros seleccionado.
En el panel Funciones y parámetros de chrome://topics-internals, se muestran las funciones habilitadas, el tiempo por época, la cantidad de ciclos de entrenamiento que se usarán para calcular los temas, la versión de taxonomía y otros parámetros de configuración.

Los parámetros que se muestran en la captura de pantalla corresponden a funciones experimentales que se pueden configurar cuando se ejecuta Chrome desde la línea de comandos. Por ejemplo, la demostración en topics-fetch-demo.glitch.me recomienda usar las siguientes marcas:

--enable-features=BrowsingTopics,BrowsingTopicsParameters:time_period_per_epoch/15s/max_epoch_introduction_delay/3s,PrivacySandboxAdsAPIsOverride,PrivacySandboxSettings3,OverridePrivacySandboxSettingsLocalTesting

En la siguiente lista, se explica cada parámetro, su valor predeterminado y su propósito.

Funciones experimentales de Chrome

BrowsingTopics
Valor predeterminado: habilitado
Indica si la API de Topics está habilitada.

PrivacySandboxAdsAPIsOverride
Valor predeterminado: habilitado
Habilita las APIs de anuncios: Attribution Reporting, Protected Audience, Topics y Marcos vallados.

PrivacySandboxSettings4
Valor predeterminado: inhabilitado
Habilita la cuarta versión de la configuración de la IU de Privacy Sandbox.

OverridePrivacySandboxSettingsLocalTesting
Valor predeterminado: habilitado
Si se habilita, el navegador ya no requiere que se habilite la configuración subyacente para habilitar las funciones de Privacy Sandbox.

BrowsingTopicsBypassIPIsPubliclyRoutableCheck
Valor predeterminado: inhabilitado
Si se habilita, se omitirá la comprobación de si la dirección IP se puede enrutar de forma pública a la hora de determinar la elegibilidad de una página para incluirse en el cálculo de temas.

BrowsingTopics:number_of_epochs_to_expose
Valor predeterminado: 3
Es la cantidad de ciclos de entrenamiento desde los que se calcularán los temas para un contexto de solicitud. El navegador mantendrá internamente hasta N + 1 ciclos de entrenamiento.

BrowsingTopics:time_period_per_epoch
Valor predeterminado: 7d-0h-0m-0s
Duración de cada ciclo de entrenamiento. Para la depuración, puede ser útil configurarlo en, por ejemplo, 15 segundos, en lugar de los siete días predeterminados.

BrowsingTopics:number_of_top_topics_per_epoch
Valor predeterminado: 5
Cantidad de temas calculadas por época.

BrowsingTopics:use_random_topic_probability_percent
Valor predeterminado: 5
Probabilidad de que se muestre de forma aleatoria un tema individual dentro de una época a partir de toda la taxonomía de temas. La aleatoriedad es fija en un ciclo de entrenamiento y un sitio.

BrowsingTopics:number_of_epochs_of_observation_data_to_use_for_filtering
Valor predeterminado: 3
Cuántos ciclos de entrenamiento de los datos de uso de la API (es decir, observaciones de temas) se utilizarán para filtrar los temas de un contexto de llamada.

BrowsingTopics:max_number_of_api_usage_context_domains_to_keep_per_topic
Valor predeterminado: 1,000
La cantidad máxima de dominios de contexto observados que se conservarán para cada tema principal. El objetivo es limitar la memoria en uso.

BrowsingTopics:max_number_of_api_usage_context_entries_to_load_per_epoch
Valor predeterminado: 100,000
La cantidad máxima de entradas que se pueden recuperar de la base de datos en cada consulta para los contextos de uso de la API. La consulta se producirá una vez por época, en el momento de cálculo de los temas. El objetivo es limitar el uso máximo de memoria.

BrowsingTopics:max_number_of_api_usage_context_domains_to_store_per_page_load
Valor predeterminado: 30
La cantidad máxima de dominios de contexto de uso de la API que se pueden almacenar por carga de página.

BrowsingTopics:config_version
Valor predeterminado: 1
Codifica los parámetros de configuración de la API de Topics. Cada número de versión solo debe asignarse a un conjunto de configuración. Por lo general, actualizar los parámetros de configuración sin actualizar config_version debería ser adecuado para las pruebas locales. Sin embargo, en algunas situaciones, podría dejar el navegador en un estado incoherente y podría generar una falla en el navegador, por ejemplo, actualizar number_of_top_topics_per_epoch.

BrowsingTopics:taxonomy_version
Valor predeterminado: 1
La versión de taxonomía que usa la API.

Cómo inhabilitar tu sitio

Si deseas inhabilitar el cálculo de temas para páginas específicas de tu sitio, incluye el encabezado Permissions-Policy: browsing-topics=() Permissions-Policy en una página para evitar que se calculen temas solo para todos los usuarios de esa página. Las visitas posteriores a otras páginas de tu sitio no se verán afectadas: si estableces una política para bloquear la API de Topics en una página, no afectará a otras.

También puedes controlar qué terceros tienen acceso a los temas de tu página. Para ello, usa el encabezado Permissions-Policy a fin de controlar el acceso de los terceros a la API de Topics. Como parámetros del encabezado, usa self y cualquier dominio al que desees permitir el acceso a la API. Por ejemplo, para inhabilitar completamente el uso de la API de Topics en todos los contextos de navegación, excepto tu propio origen y https://example.com, configura el siguiente encabezado de respuesta HTTP:

Permissions-Policy: browsing-topics=(self "https://example.com")

Próximos pasos

Más información

Interactúa y comparte comentarios