Идентичность21 октября 2025 г.

Контроль User-Agent и Client Hints (UA-CH) в BotBrowser

Узнайте, как BotBrowser управляет строками User-Agent, заголовками Client Hints и navigator.userAgentData на уровне движка для согласованной идентичности браузера.

Введение

Строка User-Agent долгое время была краеугольным камнем идентификации браузера. Но современная система идентичности браузеров сложнее. Client Hints (UA-CH) предоставляют структурированные данные о браузере через HTTP-заголовки и JavaScript API. Заголовок Sec-CH-UA, navigator.userAgentData и getHighEntropyValues() возвращают бренд, платформу, версию и модель устройства в стандартизированном формате. Если эти значения не соответствуют традиционной строке User-Agent, возникает заметный сигнал для трекинга.

BotBrowser управляет всеми сигналами User-Agent и Client Hints через профили и флаги CLI. Профили задают базовую конфигурацию автоматически, а флаги CLI дают управление идентичностью в рантайме. В этой статье объясняется, как работают UA и Client Hints вместе, какие сигналы важны и как правильно их настраивать.

Влияние на приватность

User-Agent и Client Hints — одни из первых сигналов, которые получает сервер. Они приходят с начальным HTTP-запросом, до выполнения любого JavaScript. Это делает их основными входными данными для серверного фингерпринтинга и трекинга.

Риски при несоответствии UA/Client Hints:

Детекция несоответствия на сервере: Серверы сравнивают заголовок User-Agent с Sec-CH-UA в том же запросе. Несовпадение указывает на модификацию.
Сравнение JS и заголовков: Страницы могут сравнивать navigator.userAgent с navigator.userAgentData.brands и отмечать расхождения.
Корреляция высокоэнтропийных значений: getHighEntropyValues() возвращает детализированную информацию о платформе, архитектуре и версии, которая должна соответствовать общей идентичности.
Согласованность между контекстами: Значения UA должны быть однородны в основном потоке, web workers, service workers и HTTP-заголовках. Частичные переопределения создают обнаружимые пробелы.

BotBrowser обеспечивает согласованность по всем этим параметрам, поскольку контролирует UA и Client Hints на уровне движка, до отправки запроса или выполнения JavaScript.

Технический фон

Строка User-Agent

Традиционный заголовок User-Agent — длинная строка, идентифицирующая браузер, версию, ОС и движок рендеринга:

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

Эта строка отправляется с каждым HTTP-запросом и доступна через navigator.userAgent в JavaScript. Хотя браузеры постепенно уменьшают информацию в UA-строке (UA Reduction в Chrome), она остаётся важным сигналом.

Client Hints (UA-CH)

Client Hints предоставляют ту же информацию в структурированном виде через HTTP-заголовки и JS API:

Дефолтные заголовки (отправляются с каждым запросом):

Sec-CH-UA: маркеры бренда с мажорными версиями. Пример: "Chromium";v="142", "Google Chrome";v="142", "Not:A-Brand";v="99"
Sec-CH-UA-Mobile: флаг мобильного устройства. Пример: ?0
Sec-CH-UA-Platform: ОС. Пример: "Windows"

Высокоэнтропийные заголовки (отправляются только по запросу сервера через 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

JS API (navigator.userAgentData):

// Низкая энтропия (всегда доступна)
navigator.userAgentData.brands       // [{brand: "Chromium", version: "142"}, ...]
navigator.userAgentData.mobile       // false
navigator.userAgentData.platform     // "Windows"

// Высокая энтропия (возвращает Promise)
const data = await navigator.userAgentData.getHighEntropyValues([
  'platformVersion', 'architecture', 'bitness',
  'fullVersionList', 'model'
]);

GREASE токены

Chromium вставляет случайные GREASE токены в Client Hints, чтобы предотвратить жёсткую привязку серверов к формату токенов. Типичный Sec-CH-UA содержит GREASE токен:

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

Формат, версия и позиция GREASE токена меняются между версиями и брендами. BotBrowser генерирует корректные GREASE токены для каждого профиля и конфигурации бренда.

Требования согласованности

Чтобы идентичность выглядела правдоподобно, необходимо:

Заголовок User-Agent должен соответствовать navigator.userAgent
Токены бренда в Sec-CH-UA должны соответствовать navigator.userAgentData.brands
Платформа в Sec-CH-UA-Platform должна соответствовать navigator.userAgentData.platform
Основная версия в UA должна совпадать с версией в Sec-CH-UA
Полные версии в Sec-CH-UA-Full-Version-List должны совпадать с getHighEntropyValues().fullVersionList
Версия платформы должна быть реалистичной для заявленной ОС
Архитектура и битность должны соответствовать платформе
Все значения должны быть одинаковыми в основном потоке, worker'ах и заголовках HTTP

Распространённые подходы и ограничения

Переопределение на уровне фреймворка

Playwright и Puppeteer позволяют переопределять UA:

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

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

Эти методы изменяют navigator.userAgent и заголовок User-Agent, но не обновляют:

Sec-CH-UA заголовки
navigator.userAgentData.brands
getHighEntropyValues()
UA в контексте worker'ов

Несоответствие между переопределённой строкой UA и неизменёнными Client Hints легко обнаруживается.

Network.setUserAgentOverride (CDP)

CDP предоставляет Network.setUserAgentOverride с частичной поддержкой Client Hints:

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

Это более полно, чем framework-override, но имеет ограничения:

требует Network.enable
нужно применять для каждого target'а
GREASE не генерируется автоматически
выравнивание версий ручное

Ручная инъекция заголовков

page.setExtraHTTPHeaders() может перезаписать Sec-CH-UA, но JS API по-прежнему вернёт реальные значения, что приведёт к несогласованности.

Подход BotBrowser

Автоматическая конфигурация на основе профилей

Профили BotBrowser содержат полные конфигурации UA и Client Hints, снятые с реальных браузеров. При загрузке профиля все сигналы автоматически совпадают:

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

Профиль задаёт:

строку User-Agent (заголовок и JS)
все дефолтные Client Hints заголовки
все высокоэнтропийные значения
navigator.userAgentData (brands, platform, mobile)
корректные GREASE токены
согласованные значения в main thread, workers и заголовках

Для стандартного использования дополнительные флаги не требуются.

CLI-overrides для кастомных идентичностей

Когда нужно создать кастомную идентичность, BotBrowser предоставляет детальные CLI-флаги：

（示例保留）

Пример --user-agent с заполнителями:

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 заменяет заполнители соответствующими флагами и автоматически генерирует navigator.userAgentData и все заголовки Client Hints.

Согласованность на всех поверхностях

BotBrowser обеспечивает согласованность для：

HTTP-заголовков: User-Agent и Sec-CH-UA-*
JS main thread: navigator.userAgent, navigator.userAgentData
Web Workers: те же значения
Service Workers: те же значения
Высокоэнтропийных значений: getHighEntropyValues() согласован

Конфигурация и использование

（保留示例與驗證代碼塊）

Проверка

После настройки проверьте：

что navigator.userAgent содержит корректное имя и версию
что navigator.userAgentData.brands содержит правильные маркеры бренда
что Sec-CH-UA соответствует брендам, сообщаемым JS
что getHighEntropyValues() возвращает корректные platform, architecture и version
согласованность в контексте Web Worker

Часто задаваемые вопросы

（保留要点）

Резюме

User-Agent и Client Hints составляют сетевую основу идентичности браузера. BotBrowser управляет этими сигналами через профили и CLI-флаги, чтобы поддерживать согласованность во всех контекстах.

См. также: Browser Brand Switching、Timezone, Locale, and Language Configuration、Multi-Account Browser Isolation。

title: "Управление User Agent и Client Hints (UA-CH) в BotBrowser" description: "Узнайте, как BotBrowser управляет строками User-Agent и Client Hints на уровне движка для согласованной идентификации браузера." date: "2025-10-22" locale: ru category: identity tags: ["user-agent", "client-hints", "identity", "ua-ch", "privacy"] published: true

Как BotBrowser управляет UA и Client Hints

Профили BotBrowser содержат полный набор значений User-Agent и Client Hints из реальных браузерных сред. При загрузке профиля все сигналы согласуются автоматически:

HTTP-заголовки: User-Agent и все заголовки Sec-CH-* совпадают
JavaScript API: navigator.userAgent, navigator.userAgentData.brands и getHighEntropyValues() возвращают согласованные значения
Сигналы платформы: информация о платформе, архитектуре, разрядности и версии полностью совпадает

Профиль настраивает все автоматически. Дополнительные флаги не требуются:

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

Для переопределения бренда браузера с сохранением согласованности других значений:

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

Что управляется

Заголовки по умолчанию в каждом запросе: Sec-CH-UA (токены бренда), Sec-CH-UA-Mobile и Sec-CH-UA-Platform.

Высокоэнтропийные значения через JavaScript: Sec-CH-UA-Full-Version-List, Sec-CH-UA-Platform-Version, Sec-CH-UA-Arch, Sec-CH-UA-Bitness и Sec-CH-UA-Model.

Доступ через JavaScript с помощью navigator.userAgentData:

// Low-entropy (always available)
navigator.userAgentData.brands
navigator.userAgentData.platform

// High-entropy (requires promise)
const data = await navigator.userAgentData.getHighEntropyValues([
  'platformVersion', 'architecture', 'bitness', 'fullVersionList'
]);

Пример проверки

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();
})();

Распространенные ошибки

Переопределение UA без Client Hints. Метод Puppeteer page.setUserAgent() или опция Playwright userAgent изменяют только строку UA. Client Hints остаются неизменными, создавая несоответствие. С профилями BotBrowser эти переопределения не нужны.

Несовпадение версий платформы. Профили BotBrowser содержат правильную версию.

Неправильный порядок брендов. Профили BotBrowser сохраняют правильный порядок.

Начало работы

Скачайте BotBrowser с GitHub
Загрузите профиль с --bot-profile для автоматической согласованности UA и Client Hints
При необходимости используйте --bot-config-browser-brand для переключения идентификации бренда
Проверьте инструментами фингерпринтинга, что все сигналы UA совпадают

#user-agent#client-hints#identity#ua-ch#privacy