Guía para desarrolladores de la API de Topics

Aprende a trabajar con la API, incluido cómo usar funciones experimentales de Chrome para las pruebas.

Estado de implementación

Probar la demostración

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

También puedes ejecutar colab de Topics para probar el modelo clasificador de Topics.

Usa la API de JavaScript para acceder a los temas y registrarlos como se observaron

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

  • Indica al navegador que registre la visita actual a la página como observada para el llamador, de modo que luego se pueda usar para calcular los temas para el usuario (para el llamador).
  • Accede a los temas del 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 epoch más recientes, en orden aleatorio. Un ciclo de entrenamiento es un período establecido en una semana en la implementación de Chrome.

Cada objeto del 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 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: 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 repetimos la API.

Cómo detectar la 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 temas para el 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 actual a la página según la observa el llamador, de modo que se pueda usar más adelante en 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 la página actual se incluya en el cálculo de los temas.

Usa encabezados para acceder a los temas y marcarlos como observados

Puede acceder a temas y también marcar las visitas a la página como observadas, con la ayuda de request y response.

El uso del enfoque de encabezado puede ser mucho más eficaz que el uso de la API de JavaScript, ya que la API requiere crear un iframe de origen cruzado y realizar una llamada a document.browsingTopics() desde él. (Para la llamada, se debe usar un iframe de origen cruzado, ya que el contexto desde el que se invoca la API se utiliza para garantizar que el navegador muestre los temas adecuados para el emisor). En la explicación de temas, se analiza lo siguiente: ¿Debería haber alguna manera de enviar temas con la función Fetch como encabezado de la solicitud? .

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

Configura un encabezado Observe-Browsing-Topics: ?1 en la respuesta a la solicitud hace que el navegador registre la visita a la página actual según la observa el llamador para que luego se pueda usar para el cálculo de temas.

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

  • fetch(): Agrega {browsingTopics: true} al parámetro de opciones de una solicitud fetch(). La demostración de encabezado de Topics muestra un ejemplo simplificado de esto.
  • Atributo iframe: Agrega el atributo browsingtopics a un elemento <iframe> o establece el código JavaScript equivalente. propiedad 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 emisor es example.com.

Algunas 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 para el 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 observada, por lo que no afectará el cálculo de temas 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.

Cómo depurar tu implementación de la API

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

Ver los temas calculados para tu navegador

Los usuarios pueden consultar información sobre los temas observados en su navegador durante las épocas actuales y anteriores si consultan chrome://topics-internals.

La página chrome://topics-internals con el panel Estado de temas seleccionado.
En el panel Estado de temas de la página chrome://topics-internals, se muestran los IDs de los temas, las asignaciones aleatorias y reales de temas, y las versiones de taxonomía y modelo.

En esta captura de pantalla, se 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 observan temas) para proporcionar cinco temas.

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

Ver los temas inferidos para nombres de host

También puedes ver los temas que infiere el modelo clasificador 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, la versión del modelo y la ruta de acceso.

La implementación actual de la API de Topics infiere los temas solo a partir de nombres de host. no desde ninguna 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 la taxonomía y la duración del ciclo de entrenamiento, 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 la línea de comandos funcionaron según lo esperado.

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

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

Los parámetros que se muestran en la captura de pantalla corresponden a las marcas 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 Google Ads: 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 verificará si la dirección IP se puede enrutar de forma pública se omite al determinar la elegibilidad de una página para que se incluya en los temas. cálculo.

BrowsingTopics:number_of_epochs_to_expose
Valor predeterminado: 3
La cantidad de ciclos de entrenamiento desde los que se deben calcular los temas para dar a un solicitante adicional. 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 establecer esto en 15 segundos, en lugar de los siete días predeterminados.

BrowsingTopics:number_of_top_topics_per_epoch
Valor predeterminado: 5
Cantidad de temas calculada por ciclo de entrenamiento.

BrowsingTopics:use_random_topic_probability_percent
Valor predeterminado: 5
Probabilidad de que un tema individual dentro de un ciclo de entrenamiento sea uno que se muestre al azar desde toda la taxonomía de temas. La aleatoriedad se mantiene en un ciclo de entrenamiento y un sitio.

BrowsingTopics:number_of_epochs_of_observation_data_to_use_for_filtering
Valor predeterminado: 3
Para cuántos ciclos de entrenamiento se usarán los datos de uso de la API (es decir, observaciones de temas) filtrando los temas para 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 deben conservar para cada tema principal. El intent es limitar la memoria en uso.

BrowsingTopics:max_number_of_api_usage_context_entries_to_load_per_epoch
Valor predeterminado: 100000
La cantidad máxima de entradas que se pueden recuperar de la base de datos para cada consulta para los contextos de uso de la API. La consulta se realizará una vez por época en el cálculo de temas tiempo. Su 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 se asigna a un conjunto de configuración. Debes actualizar los parámetros de configuración sin actualizar config_version generalmente son adecuados para las pruebas locales, pero, en algunos casos, es posible que el navegador quede en estado incoherente y podría provocar una falla del navegador, por ejemplo, actualizar la number_of_top_topics_per_epoch

BrowsingTopics:taxonomy_version
Valor predeterminado: 1
La taxonomía más antigua 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 para todos los usuarios de esa página únicamente. 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, esto no afectará a otras páginas.

También puedes controlar qué terceros tienen acceso a los temas de tu página con el encabezado Permissions-Policy para controlar el acceso de terceros a la API de Topics. Como parámetros del encabezado, usa self y cualquier dominio que desees permitir el acceso a la API. Por ejemplo, para inhabilitar por completo 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