Volver al Blog
Identidad

Control del User-Agent y Client Hints (UA-CH) en BotBrowser

Aprende cómo BotBrowser gestiona las cadenas User-Agent, los encabezados Client Hints y navigator.userAgentData a nivel de motor para mantener una identidad de navegador consistente.

Introducción

La cadena User-Agent ha sido durante décadas la base de la identificación del navegador. Pero el sistema moderno de identidad del navegador es más complejo. Los Client Hints (UA-CH) proporcionan datos estructurados sobre el navegador mediante encabezados HTTP y APIs de JavaScript. El encabezado Sec-CH-UA, navigator.userAgentData y getHighEntropyValues() exponen marca, plataforma, versión y dispositivo en un formato estandarizado. Cuando estos valores no coinciden con la cadena User-Agent tradicional, la inconsistencia genera una señal de seguimiento distinguible.

BotBrowser gestiona todas las señales de User-Agent y Client Hints mediante perfiles y opciones de CLI. Los perfiles establecen la línea base automáticamente, y las banderas de la CLI ofrecen control en tiempo de ejecución para identidades personalizadas. Este artículo explica cómo funcionan UA y Client Hints juntos, qué señales importan y cómo configurarlas correctamente.

Impacto en la privacidad

User-Agent y Client Hints están entre las primeras señales que recibe un servidor. Llegan con la petición HTTP inicial, antes de que se ejecute cualquier JavaScript. Esto las convierte en una entrada principal para la huella del lado servidor y el rastreo.

Los riesgos de privacidad por desalineación de UA/Client Hints incluyen:

  • Detección de inconsistencia en servidor: Los servidores comparan el encabezado User-Agent con los Sec-CH-UA de la misma petición. Una discrepancia indica modificación.
  • Comparación JavaScript-encabezado: Las páginas pueden comparar navigator.userAgent con navigator.userAgentData.brands y detectar desalineaciones.
  • Correlación de valores de alta entropía: getHighEntropyValues() devuelve datos detallados de plataforma, arquitectura y versión que deben corresponder con la identidad general.
  • Consistencia entre contextos: Los valores UA deben ser coherentes en hilo principal, web workers, service workers y encabezados HTTP. Coberturas parciales generan brechas detectables.

BotBrowser asegura consistencia en todas estas superficies porque controla UA y Client Hints en el nivel del motor, antes de enviar peticiones o ejecutar JavaScript.

Antecedentes técnicos

La cadena User-Agent

La cabecera tradicional User-Agent es una cadena larga que identifica navegador, versión, SO y motor de renderizado:

Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/142.0.7444.60 Safari/537.36

Esta cadena se envía con cada petición HTTP y está disponible en JavaScript vía navigator.userAgent. Aunque los navegadores reducen gradualmente la información en la cadena UA (UA Reduction de Chrome), sigue siendo una señal importante.

Client Hints (UA-CH)

Client Hints proporcionan la misma información de forma estructurada a través de encabezados HTTP y APIs JS:

Encabezados por defecto (enviados con cada petición):

  • Sec-CH-UA: tokens de marca con versiones mayores. Ejemplo: "Chromium";v="142", "Google Chrome";v="142", "Not:A-Brand";v="99"
  • Sec-CH-UA-Mobile: si es móvil. Ejemplo: ?0
  • Sec-CH-UA-Platform: sistema operativo. Ejemplo: "Windows"

Encabezados de alta entropía (enviados sólo si el servidor los solicita vía Accept-CH):

  • Sec-CH-UA-Full-Version-List
  • Sec-CH-UA-Platform-Version
  • Sec-CH-UA-Arch
  • Sec-CH-UA-Bitness
  • Sec-CH-UA-Model

API JavaScript (navigator.userAgentData):

// Baja entropía (siempre disponible)
navigator.userAgentData.brands       // [{brand: "Chromium", version: "142"}, ...]
navigator.userAgentData.mobile       // false
navigator.userAgentData.platform     // "Windows"

// Alta entropía (devuelve Promise)
const data = await navigator.userAgentData.getHighEntropyValues([
  'platformVersion', 'architecture', 'bitness',
  'fullVersionList', 'model'
]);

Tokens GREASE

Chromium añade tokens aleatorios "GREASE" a Client Hints para evitar que los servidores codifiquen supuestos rígidos sobre el formato de tokens. Un Sec-CH-UA típico incluye un token GREASE:

"Not:A-Brand";v="99", "Chromium";v="142", "Google Chrome";v="142"

El formato, versión y posición del token GREASE cambian entre versiones y marcas. BotBrowser genera tokens GREASE correctos para cada perfil y configuración de marca.

Requisitos de consistencia

Para una identidad de navegador creíble, lo siguiente debe coincidir:

  1. User-Agent header coincide con navigator.userAgent
  2. Tokens de marca en Sec-CH-UA coinciden con navigator.userAgentData.brands
  3. Plataforma en Sec-CH-UA-Platform coincide con navigator.userAgentData.platform
  4. Versión mayor en la cadena UA coincide con la versión en Sec-CH-UA
  5. Versiones completas en Sec-CH-UA-Full-Version-List coinciden con getHighEntropyValues().fullVersionList
  6. Versión de plataforma es realista para el SO declarado
  7. Arquitectura y bitness coinciden con la plataforma
  8. Todos los valores son iguales en hilo principal, workers y encabezados HTTP

Enfoques comunes y sus limitaciones

Override a nivel de framework

Playwright y Puppeteer permiten sobrescribir el UA:

// Playwright
const context = await browser.newContext({
  userAgent: 'Custom UA String'
});

// Puppeteer
await page.setUserAgent('Custom UA String');

Estos cambios modifican navigator.userAgent y el header User-Agent pero no actualizan:

  • Sec-CH-UA headers
  • navigator.userAgentData.brands
  • getHighEntropyValues()
  • UA a nivel de worker

La discrepancia entre la cadena UA sobrescrita y los Client Hints no modificados es fácilmente detectable.

Network.setUserAgentOverride de CDP

CDP ofrece Network.setUserAgentOverride con soporte parcial para Client Hints:

await cdpSession.send('Network.setUserAgentOverride', {
  userAgent: 'Custom UA',
  userAgentMetadata: {
    brands: [...],
    platform: 'Windows',
    // ...
  }
});

Es más completo que el override a nivel de framework, pero tiene limitaciones:

  • Requiere Network.enable
  • Debe aplicarse por target
  • GREASE no se genera automáticamente
  • Alineación de versiones es manual

Inyección manual de encabezados

page.setExtraHTTPHeaders() puede sobrescribir Sec-CH-UA, pero las APIs JS siguen retornando los valores reales, creando inconsistencia.

Enfoque de BotBrowser

Configuración automática basada en perfiles

Los perfiles de BotBrowser contienen configuraciones completas de UA y Client Hints tomadas de navegadores reales. Al cargar un perfil, todas las señales se alinean automáticamente:

chrome --bot-profile="/path/to/profile.enc"

El perfil establece:

  • Cadena User-Agent (header y JS)
  • Todos los headers Client Hints por defecto
  • Todos los valores de alta entropía
  • navigator.userAgentData (brands, platform, mobile)
  • Tokens GREASE apropiados
  • Valores consistentes entre hilo principal, workers y headers

No se requieren flags adicionales para la configuración estándar.

Overrides por CLI para identidades personalizadas

Para identidades personalizadas, BotBrowser expone flags finos de CLI:

（保留原文标志示例）

Ejemplo de --user-agent con marcadores:

chrome --bot-profile="/path/to/profile.enc" \
       --user-agent="Mozilla/5.0 (Linux; Android {platform-version}; {model}) AppleWebKit/537.36 Chrome/{ua-full-version} Mobile Safari/537.36" \
       --bot-config-platform=Android \
       --bot-config-platform-version=13 \
       --bot-config-model=SM-G991B \
       --bot-config-ua-full-version=142.0.7444.60

BotBrowser sustituye los marcadores por los flags correspondientes y genera navigator.userAgentData y los headers Client Hints.

Consistencia en todas las superficies

BotBrowser asegura coherencia en:

  • Headers HTTP: User-Agent y Sec-CH-UA-*
  • JS hilo principal: navigator.userAgent, navigator.userAgentData
  • Web Workers: valores coherentes en workers
  • Service Workers: mismos valores en service workers
  • Valores de alta entropía: getHighEntropyValues() consistente

Configuración y uso

（保留原文示例与验证代码块）

Verificación

Tras configurar, verificar:

  1. navigator.userAgent contiene el nombre y versión correctos
  2. navigator.userAgentData.brands contiene los tokens correctos
  3. Sec-CH-UA coincide con lo reportado por JS
  4. getHighEntropyValues() devuelve platform, architecture y version correctos
  5. Consistencia en Web Worker

Buenas prácticas

  1. Preferir perfiles sobre configuración manual.
  2. No usar overrides de UA de Playwright/Puppeteer para cambios completos.
  3. Mantener versiones realistas.
  4. Alinear versiones específicas de marca.
  5. Probar con herramientas de verificación de huellas.
  6. Actualizar perfiles regularmente.

Preguntas frecuentes

（保留 FAQ 要点）

Resumen

User-Agent y Client Hints forman la base de identidad del navegador a nivel de red. BotBrowser gestiona ambas mediante perfiles y flags de CLI para mantener señales alineadas en todos los contextos.

Referencias: Browser Brand Switching；Timezone, Locale, and Language Configuration；Multi-Account Browser Isolation。

title: "Control de User Agent y Client Hints (UA-CH) en BotBrowser" description: "Aprende como BotBrowser gestiona las cadenas de User-Agent y Client Hints a nivel del motor para una identidad de navegador consistente." date: "2025-10-22" locale: es category: identity tags: ["user-agent", "client-hints", "identity", "ua-ch", "privacy"] published: true

Como BotBrowser gestiona UA y Client Hints

Los perfiles de BotBrowser contienen el conjunto completo de valores de User-Agent y Client Hints de entornos de navegador reales. Al cargar un perfil, todas las senales se alinean automaticamente:

  • Headers HTTP: Tanto User-Agent como todos los headers Sec-CH-* coinciden
  • APIs JavaScript: navigator.userAgent, navigator.userAgentData.brands y getHighEntropyValues() devuelven valores consistentes
  • Senales de plataforma: Plataforma, arquitectura, bits y version coinciden
chrome --bot-profile="/path/to/profile.enc"

Para cambiar la marca manteniendo otros valores consistentes:

chrome --bot-profile="/path/to/profile.enc" \
       --bot-config-browser-brand=edge

Que se gestiona

Headers por defecto: Sec-CH-UA, Sec-CH-UA-Mobile y Sec-CH-UA-Platform.

Valores de alta entropia: Sec-CH-UA-Full-Version-List, Sec-CH-UA-Platform-Version, Sec-CH-UA-Arch, Sec-CH-UA-Bitness y Sec-CH-UA-Model.

// Baja entropia (siempre disponible)
navigator.userAgentData.brands
navigator.userAgentData.platform

// Alta entropia (requiere promise)
const data = await navigator.userAgentData.getHighEntropyValues([
  'platformVersion', 'architecture', 'bitness', 'fullVersionList'
]);

Ejemplo de verificacion

const puppeteer = require('puppeteer-core');

(async () => {
  const browser = await puppeteer.launch({
    executablePath: '/path/to/botbrowser/chrome',
    args: ['--bot-profile=/path/to/profile.enc'],
    headless: true,
    defaultViewport: null,
  });

  const page = await browser.newPage();
  await page.goto('https://example.com');

  const ua = await page.evaluate(() => navigator.userAgent);
  const brands = await page.evaluate(() =>
    navigator.userAgentData.brands.map(b => `${b.brand} v${b.version}`)
  );
  console.log('User-Agent:', ua);
  console.log('Brands:', brands);
  await browser.close();
})();

Errores comunes

Sobreescribir UA sin Client Hints. page.setUserAgent() de Puppeteer solo cambia el string UA. Con perfiles BotBrowser no necesitas estas sobreescrituras.

Versiones de plataforma incorrectas. Los perfiles de BotBrowser incluyen la version correcta.

Orden de marca incorrecto. Los perfiles de BotBrowser preservan el orden correcto.

Primeros pasos

  1. Descarga BotBrowser desde GitHub
  2. Carga un perfil con --bot-profile
  3. Opcionalmente usa --bot-config-browser-brand para cambiar la identidad de marca
  4. Verifica con herramientas de huella digital que todas las senales UA coincidan
#user-agent#client-hints#identity#ua-ch#privacy