Migra a Client Hints de usuario-agente

Estrategias para migrar tu sitio de depender de la cadena de usuario-agente a las nuevas User-Agent Client Hints.

Publicado: 19 de mayo de 2021

La cadena de usuario-agente es una superficie de creación pasiva de huellas digitales significativa en los navegadores, además de ser difícil de procesar. Sin embargo, existen todo tipo de motivos válidos para recopilar y procesar datos de usuario-agente, por lo que se necesita una ruta hacia una mejor solución. Los User-Agent Client Hints proporcionan una forma explícita de declarar tu necesidad de datos del usuario-agente y métodos para devolver los datos en un formato fácil de usar.

Aquí, te guiaremos para que audites tu acceso a los datos del usuario-agente y migres el uso de la cadena de usuario-agente a las sugerencias de clientes del usuario-agente.

Browser Support

  • Chrome: 90.
  • Edge: 90.
  • Firefox: not supported.
  • Safari: not supported.

Source

Audita la recopilación y el uso de datos del usuario-agente

Al igual que con cualquier forma de recopilación de datos, siempre debes comprender por qué los recopilas. El primer paso, independientemente de si tomarás o no alguna medida, es comprender dónde y por qué usas los datos del usuario-agente.

Si no sabes si se usan los datos del usuario-agente o dónde se usan, considera buscar en tu código de frontend el uso de navigator.userAgent y en tu código de backend el uso del encabezado HTTP User-Agent. También debes verificar el código de frontend para usar funciones que ya estén obsoletas, como navigator.platform y navigator.appVersion.

Desde un punto de vista funcional, piensa en cualquier parte de tu código en la que estés registrando o procesando lo siguiente:

  • Nombre o versión del navegador
  • Nombre o versión del sistema operativo
  • Marca o modelo del dispositivo
  • Tipo, arquitectura o cantidad de bits de la CPU (por ejemplo, 64 bits)

También es probable que uses una biblioteca o un servicio de terceros para procesar el usuario-agente. En este caso, verifica si se están actualizando para admitir User-Agent Client Hints.

¿Solo usas datos básicos del usuario-agente?

El conjunto predeterminado de User-Agent Client Hints incluye lo siguiente:

  • Sec-CH-UA: nombre del navegador y versión principal o significativa
  • Sec-CH-UA-Mobile: Es un valor booleano que indica un dispositivo móvil.
  • Sec-CH-UA-Platform: Es el nombre del sistema operativo.

La versión reducida de la cadena de usuario-agente que se propone también conservará esta información básica de forma retrocompatible. Por ejemplo, en lugar de Chrome/90.0.4430.85, la cadena incluiría Chrome/90.0.0.0.

Si solo verificas la cadena de usuario-agente para el nombre del navegador, la versión principal o el sistema operativo, tu código seguirá funcionando, aunque es probable que veas advertencias de baja.

Si bien puedes y debes migrar a User-Agent Client Hints, es posible que tengas restricciones de código o recursos heredados que lo impidan. La reducción de la información en la cadena de usuario-agente de esta manera retrocompatible tiene como objetivo garantizar que, si bien el código existente recibirá información menos detallada, aún conservará la funcionalidad básica.

Estrategias

Existen varias estrategias que puedes adoptar para migrar el uso de la cadena de usuario-agente a las sugerencias de clientes de usuario-agente.

API de JavaScript del cliente on demand

Si usas navigator.userAgent, debes realizar la transición para preferir navigator.userAgentData antes de recurrir al análisis de la cadena de usuario-agente.

if (navigator.userAgentData) {
  // use new hints
} else {
  // fall back to user-agent string parsing
}

Si estás verificando si se trata de un dispositivo móvil o una computadora de escritorio, usa el valor booleano mobile:

const isMobile = navigator.userAgentData.mobile;

userAgentData.brands es un array de objetos con las propiedades brand y version en el que el navegador puede enumerar su compatibilidad con esas marcas. Puedes acceder a él directamente como un array o usar una llamada some() para verificar si hay una entrada específica:

function isCompatible(item) {
  // In real life you most likely have more complex rules here
  return ['Chromium', 'Google Chrome', 'NewBrowser'].includes(item.brand);
}
if (navigator.userAgentData.brands.some(isCompatible)) {
  // browser reports as compatible
}

Si necesitas uno de los valores de usuario-agente de alta entropía más detallados, debes especificarlo y verificar el resultado en el Promise que se devuelve:

navigator.userAgentData.getHighEntropyValues(['model'])
  .then(ua => {
    // requested hints available as attributes
    const model = ua.model
  });

También puedes usar esta estrategia si deseas pasar del procesamiento del servidor al procesamiento del cliente. La API de JavaScript no requiere acceso a los encabezados de la solicitud HTTP, por lo que los valores de usuario-agente se pueden solicitar en cualquier momento.

Encabezado estático del servidor

Si usas el encabezado de la solicitud User-Agent en el servidor y tus necesidades de esos datos son relativamente coherentes en todo el sitio, puedes especificar los Client Hints como un conjunto estático en tus respuestas. Este es un enfoque relativamente simple, ya que, por lo general, solo necesitas configurarlo en una ubicación. Por ejemplo, puede estar en la configuración de tu servidor web si ya agregas encabezados allí, en la configuración de hosting o en la configuración de nivel superior del framework o la plataforma que usas para tu sitio.

Considera esta estrategia si transformas o personalizas las respuestas que se publican según los datos del usuario-agente.

Los navegadores o clientes pueden elegir proporcionar diferentes sugerencias predeterminadas, por lo que es una buena práctica especificar todo lo que necesitas, incluso si se proporciona de forma predeterminada.

Por ejemplo, los valores predeterminados actuales de Chrome se representarían de la siguiente manera:

⬇️ Encabezados de respuesta

Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Platform, Sec-CH-UA

Si también quieres recibir el modelo del dispositivo en las respuestas, debes enviar lo siguiente:

⬇️ Encabezados de respuesta

Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Model, Sec-CH-UA-Platform, Sec-CH-UA

Cuando proceses esto en el servidor, primero debes verificar si se envió el encabezado Sec-CH-UA deseado y, luego, recurrir al análisis del encabezado User-Agent si no está disponible.

Delega sugerencias a solicitudes de origen cruzado

Si solicitas recursos secundarios de origen cruzado o de sitios cruzados que requieren que se envíen User-Agent Client Hints en sus solicitudes, deberás especificar de forma explícita las sugerencias deseadas con una política de permisos.

Por ejemplo, supongamos que https://blog.site aloja recursos en https://cdn.site, que puede devolver recursos optimizados para un dispositivo específico. https://blog.site puede solicitar la sugerencia Sec-CH-UA-Model, pero debe delegarla de forma explícita a https://cdn.site con el encabezado Permissions-Policy. La lista de Client Hints controladas por políticas está disponible en el borrador de la infraestructura de Client Hints.

⬇️ Respuesta de blog.site que delega la sugerencia

Accept-CH: Sec-CH-UA-Model
Permissions-Policy: ch-ua-model=(self "https://cdn.site")

⬆️ Las solicitudes a recursos secundarios en cdn.site incluyen la sugerencia delegada

Sec-CH-UA-Model: "Pixel 5"

Puedes especificar varias sugerencias para varios orígenes, y no solo desde el rango ch-ua:

⬇️ Respuesta de blog.site que delega varios hints a varios orígenes

Accept-CH: Sec-CH-UA-Model, DPR
Permissions-Policy: ch-ua-model=(self "https://cdn.site"),
                    ch-dpr=(self "https://cdn.site" "https://img.site")

Delega sugerencias a iframes

Los iframes de origen cruzado funcionan de manera similar a los recursos de origen cruzado, pero tú especificas las sugerencias que deseas delegar en el atributo allow.

⬇️ Respuesta de blog.site

Accept-CH: Sec-CH-UA-Model

↪️ HTML para blog.site

<iframe src="https://widget.site" allow="ch-ua-model"></iframe>

⬆️ Solicitud para widget.site

Sec-CH-UA-Model: "Pixel 5"

El atributo allow en el iframe anulará cualquier encabezado Accept-CH que widget.site pueda enviar por sí mismo, así que asegúrate de haber especificado todo lo que necesitará el sitio del iframe.

Sugerencias dinámicas del servidor

Si tienes partes específicas del recorrido del usuario en las que necesitas una selección más grande de sugerencias que en el resto del sitio, puedes optar por solicitar esas sugerencias a pedido en lugar de hacerlo de forma estática en todo el sitio. Esto es más complejo de administrar, pero si ya estableces encabezados diferentes por ruta, puede ser factible.

Lo importante que debes recordar aquí es que cada instancia del encabezado Accept-CH reemplazará de manera efectiva el conjunto existente. Por lo tanto, si configuras el encabezado de forma dinámica, cada página debe solicitar el conjunto completo de sugerencias necesarias.

Por ejemplo, puedes tener una sección en tu sitio en la que quieras proporcionar íconos y controles que coincidan con el sistema operativo del usuario. Para ello, es posible que también quieras extraer Sec-CH-UA-Platform-Version para entregar los recursos secundarios adecuados.

⬇️ Encabezados de respuesta para /blog

Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Platform, Sec-CH-UA

⬇️ Encabezados de respuesta para /app

Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Platform, Sec-CH-UA-Platform-Version, Sec-CH-UA

Aborda las sugerencias del servidor que se requieren en la primera solicitud

Puede haber casos en los que necesites más que el conjunto predeterminado de sugerencias en la primera solicitud. Sin embargo, es probable que esto sea poco frecuente, así que asegúrate de revisar el razonamiento.

La primera solicitud realmente significa la primera solicitud de nivel superior para ese origen enviada en esa sesión de navegación. El conjunto predeterminado de sugerencias incluye el nombre del navegador con la versión principal, la plataforma y el indicador de dispositivo móvil. Por lo tanto, la pregunta que debes hacerte aquí es si necesitas datos extendidos en la carga de página inicial.

Para obtener sugerencias adicionales sobre la primera solicitud, hay dos opciones. Primero, puedes usar el encabezado Critical-CH. Este tiene el mismo formato que Accept-CH, pero le indica al navegador que debe volver a intentar la solicitud de inmediato si la primera se envió sin la sugerencia crítica.

⬆️ Solicitud inicial

[With default headers]

⬇️ Encabezados de respuesta

Accept-CH: Sec-CH-UA-Model
Critical-CH: Sec-CH-UA-Model

🔃 El navegador vuelve a intentar la solicitud inicial con el encabezado adicional.

[With default headers + …]
Sec-CH-UA-Model: Pixel 5

Esto genera la sobrecarga del reintento en la primera solicitud, pero el costo de implementación es relativamente bajo. Envía el encabezado adicional y el navegador hará el resto.

Para situaciones en las que realmente necesitas sugerencias adicionales en la primera carga de la página, la propuesta de confiabilidad de las sugerencias de clientes establece una ruta para especificar sugerencias en la configuración a nivel de la conexión. Esto aprovecha la extensión de Configuración del protocolo de la capa de aplicación (ALPS) para TLS 1.3 para habilitar este paso anticipado de sugerencias en las conexiones HTTP/2 y HTTP/3. Esto todavía se encuentra en una etapa muy temprana, pero si administras de forma activa tu propia configuración de TLS y conexión, este es el momento ideal para contribuir.

Asistencia heredada

Es posible que tengas código heredado o de terceros en tu sitio que dependa de navigator.userAgent, incluidas partes de la cadena de usuario-agente que se reducirán. Debes planificar el cambio a las llamadas navigator.userAgentData equivalentes, pero hay una solución temporal.

UA-CH retrofill es una biblioteca pequeña que te permite reemplazar navigator.userAgent por una cadena nueva compilada a partir de los valores de navigator.userAgentData solicitados.

Por ejemplo, este código genera una cadena de usuario-agente que, además, incluye la sugerencia "model":

import { overrideUserAgentUsingClientHints } from './uach-retrofill.js';
overrideUserAgentUsingClientHints(['model'])
  .then(() => { console.log(navigator.userAgent); });

La cadena resultante mostraría el modelo Pixel 5, pero aún muestra el 92.0.0.0 reducido, ya que no se solicitó la sugerencia uaFullVersion:

Mozilla/5.0 (Linux; Android 10.0; Pixel 5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.0.0 Mobile Safari/537.36

Asistencia adicional

Si estas estrategias no abordan tu caso de uso, inicia un debate en el repositorio privacy-sandbox-dev-support y podremos explorar tu problema juntos.