Retour au Blog
Identité

Contrôle du User-Agent et des Client Hints (UA-CH) dans BotBrowser

Découvrez comment BotBrowser gère les chaînes User-Agent, les en-têtes Client Hints et navigator.userAgentData au niveau du moteur pour une identité de navigateur cohérente.

Introduction

La chaîne User-Agent a longtemps constitué la pierre angulaire de l'identification des navigateurs. Mais le système d'identité moderne est plus complexe. Les Client Hints (UA-CH) fournissent des données structurées sur le navigateur via des en-têtes HTTP et des API JavaScript. L'en-tête Sec-CH-UA, navigator.userAgentData et getHighEntropyValues() exposent la marque, la plateforme, la version et le modèle de l'appareil dans un format standardisé. Lorsque ces valeurs ne correspondent pas à la chaîne User-Agent traditionnelle, l'incohérence crée un signal de suivi notable.

BotBrowser gère tous les signaux User-Agent et Client Hints via des profils et des options en ligne de commande. Les profils définissent automatiquement la configuration de base, et les flags CLI offrent un contrôle d'exécution pour des identités personnalisées. Cet article explique comment UA et Client Hints interagissent, quelles sont les signaux importants et comment les configurer correctement.

Impact sur la vie privée

Les User-Agent et Client Hints sont parmi les premières informations envoyées au serveur. Elles arrivent avec la requête HTTP initiale, avant l'exécution de tout JavaScript. Elles constituent donc une entrée principale pour le fingerprinting côté serveur et le suivi.

Les risques liés à une désynchronisation UA/Client Hints comprennent :

  • Détection d'incohérence côté serveur : Les serveurs comparent l'en-tête User-Agent avec les Sec-CH-UA de la même requête. Une divergence indique une modification.
  • Comparaison JS/en-tête : Les pages peuvent comparer navigator.userAgent avec navigator.userAgentData.brands et détecter des différences.
  • Corrélation de valeurs à haute entropie : getHighEntropyValues() renvoie des informations détaillées (plateforme, architecture, version) qui doivent correspondre à l'identité globale.
  • Cohérence inter-contexte : Les valeurs UA doivent être cohérentes entre le thread principal, les web workers, les service workers et les en-têtes HTTP. Des surcharges partielles créent des écarts détectables.

BotBrowser assure la cohérence sur tous ces aspects car il contrôle UA et Client Hints au niveau du moteur, avant l'envoi des requêtes ou l'exécution du JavaScript.

Contexte technique

La chaîne User-Agent

L'en-tête traditionnel User-Agent est une longue chaîne identifiant le navigateur, sa version, le système d'exploitation et le moteur de rendu :

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

Cette chaîne est envoyée avec chaque requête HTTP et est accessible via navigator.userAgent en JavaScript. Bien que les navigateurs réduisent progressivement l'information dans la chaîne UA (UA Reduction de Chrome), elle reste un signal important.

Client Hints (UA-CH)

Les Client Hints fournissent les mêmes informations de manière structurée via des en-têtes HTTP et des API JS :

En-têtes par défaut (envoyés avec chaque requête) :

  • Sec-CH-UA : tokens de marque avec versions majeures. Ex. : "Chromium";v="142", "Google Chrome";v="142", "Not:A-Brand";v="99"
  • Sec-CH-UA-Mobile : indicateur mobile. Ex. : ?0
  • Sec-CH-UA-Platform : système d'exploitation. Ex. : "Windows"

En-têtes haute entropie (envoyés seulement si le serveur les demande via 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) :

// Faible entropie (toujours disponible)
navigator.userAgentData.brands       // [{brand: "Chromium", version: "142"}, ...]
navigator.userAgentData.mobile       // false
navigator.userAgentData.platform     // "Windows"

// Haute entropie (Promise)
const data = await navigator.userAgentData.getHighEntropyValues([
  'platformVersion', 'architecture', 'bitness',
  'fullVersionList', 'model'
]);

Tokens GREASE

Chromium insère des tokens aléatoires "GREASE" dans les Client Hints pour empêcher les serveurs de faire des suppositions rigides sur le format des tokens. Un Sec-CH-UA typique inclut un token GREASE :

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

Le format, la version et la position du token GREASE évoluent selon la version du navigateur et la marque. BotBrowser génère des tokens GREASE conformes pour chaque profil et configuration.

Exigences de cohérence

Pour une identité crédible, il faut que :

  1. l'en-tête User-Agent corresponde à navigator.userAgent
  2. les tokens de marque de Sec-CH-UA correspondent à navigator.userAgentData.brands
  3. la plateforme de Sec-CH-UA-Platform corresponde à navigator.userAgentData.platform
  4. la version majeure dans la UA corresponde à la version dans Sec-CH-UA
  5. les versions complètes dans Sec-CH-UA-Full-Version-List correspondent à getHighEntropyValues().fullVersionList
  6. la version de plateforme soit réaliste pour l'OS déclaré
  7. l'architecture et la bitness correspondent à la plateforme
  8. toutes les valeurs soient identiques dans le thread principal, les workers et les en-têtes HTTP

Approches communes et limites

Override au niveau framework

Playwright et Puppeteer permettent d'overrider le UA :

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

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

Ces modifications changent navigator.userAgent et l'en-tête User-Agent, mais n'actualisent pas :

  • Sec-CH-UA headers
  • navigator.userAgentData.brands
  • getHighEntropyValues()
  • UA au niveau des workers

L'écart entre la chaîne UA modifiée et les Client Hints inchangés est facilement détectable.

Network.setUserAgentOverride (CDP)

CDP propose Network.setUserAgentOverride avec un support partiel des Client Hints :

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

C'est plus complet que l'override framework, mais présente des limites :

  • nécessite Network.enable
  • doit être appliqué par cible
  • GREASE n'est pas généré automatiquement
  • l'alignement des versions est manuel

Injection manuelle d'en-têtes

page.setExtraHTTPHeaders() peut remplacer Sec-CH-UA, mais les APIs JS renvoient toujours les valeurs réelles, causant une incohérence.

Approche BotBrowser

Configuration automatique par profils

Les profils BotBrowser contiennent la configuration complète de UA et Client Hints capturée depuis des navigateurs réels. Lorsque vous chargez un profil, tous les signaux s'alignent automatiquement :

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

Le profil définit :

  • la chaîne User-Agent (header et JS)
  • tous les en-têtes Client Hints par défaut
  • tous les valeurs de haute entropie
  • navigator.userAgentData (brands, platform, mobile)
  • tokens GREASE appropriés
  • valeurs cohérentes entre thread principal, workers et headers

L'utilisation standard ne nécessite pas de flags supplémentaires.

Overrides CLI pour identités personnalisées

Pour construire une identité personnalisée, BotBrowser propose des flags CLI granulaires :

（示例保留）

Exemple --user-agent avec placeholders :

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 remplace les placeholders par les flags correspondants puis génère navigator.userAgentData et les en-têtes Client Hints.

Cohérence sur toutes les surfaces

BotBrowser garantit la cohérence sur :

  • En-têtes HTTP : User-Agent et Sec-CH-UA-*
  • JS thread principal : navigator.userAgent, navigator.userAgentData
  • Web Workers : mêmes valeurs
  • Service Workers : mêmes valeurs
  • Valeurs haute entropie : getHighEntropyValues() cohérent

Configuration et utilisation

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

Vérification

Après configuration, vérifiez :

  1. que navigator.userAgent contient le nom et la version attendus
  2. que navigator.userAgentData.brands contient les tokens corrects
  3. que Sec-CH-UA correspond aux marques reportées par JS
  4. que getHighEntropyValues() renvoie platform, architecture et version corrects
  5. la cohérence dans un contexte Web Worker

Bonnes pratiques

  1. Préférez les profils plutôt que la configuration manuelle.
  2. N'utilisez pas les overrides UA de Playwright/Puppeteer pour la cohérence complète.
  3. Utilisez des versions réalistes.
  4. Alignez les versions spécifiques à la marque.
  5. Testez avec des outils de vérification de fingerprint.
  6. Mettez à jour les profils régulièrement.

FAQ

（保留要点）

Résumé

Les User-Agent et Client Hints constituent la base de l'identité navigateur au niveau réseau. BotBrowser gère ces signaux via des profils et des flags CLI pour maintenir l'alignement dans tous les contextes.

Voir aussi : Browser Brand Switching、Timezone, Locale, and Language Configuration、Multi-Account Browser Isolation。

title: "Controle du User Agent et Client Hints (UA-CH) dans BotBrowser" description: "Decouvrez comment BotBrowser gere les chaines User-Agent et les Client Hints au niveau du moteur pour une identite de navigateur coherente." date: "2025-10-22" locale: fr category: identity tags: ["user-agent", "client-hints", "identity", "ua-ch", "privacy"] published: true

Comment BotBrowser gere UA et Client Hints

Les profils BotBrowser contiennent l'ensemble complet des valeurs User-Agent et Client Hints d'environnements de navigateur reels. Lors du chargement d'un profil, tous les signaux s'alignent automatiquement :

  • En-tetes HTTP: User-Agent et tous les en-tetes Sec-CH-* correspondent
  • APIs JavaScript: navigator.userAgent, navigator.userAgentData.brands et getHighEntropyValues() retournent des valeurs coherentes
  • Signaux de plateforme: Plateforme, architecture, bits et version correspondent
chrome --bot-profile="/path/to/profile.enc"

Pour changer la marque tout en gardant les autres valeurs coherentes :

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

Ce qui est gere

En-tetes par defaut: Sec-CH-UA, Sec-CH-UA-Mobile et Sec-CH-UA-Platform.

Valeurs haute entropie: Sec-CH-UA-Full-Version-List, Sec-CH-UA-Platform-Version, Sec-CH-UA-Arch, Sec-CH-UA-Bitness et Sec-CH-UA-Model.

// Basse entropie (toujours disponible)
navigator.userAgentData.brands
navigator.userAgentData.platform

// Haute entropie (necessite une promesse)
const data = await navigator.userAgentData.getHighEntropyValues([
  'platformVersion', 'architecture', 'bitness', 'fullVersionList'
]);

Exemple de verification

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('Marques:', brands);
  await browser.close();
})();

Pieges courants

Remplacer UA sans Client Hints. page.setUserAgent() de Puppeteer ne change que le string UA. Avec les profils BotBrowser, ces remplacements ne sont pas necessaires.

Versions de plateforme incorrectes. Les profils BotBrowser incluent la bonne version.

Ordre de marque incorrect. Les profils BotBrowser preservent l'ordre correct.

Pour commencer

  1. Telechargez BotBrowser depuis GitHub
  2. Chargez un profil avec --bot-profile
  3. Optionnellement utilisez --bot-config-browser-brand pour changer la marque
  4. Verifiez avec des outils d'empreinte que tous les signaux UA correspondent
#user-agent#client-hints#identity#ua-ch#privacy