User-Agent et Client Hints (UA-CH) : guide de contrôle complet

Introduction

La chaîne User-Agent est un pilier de l'identification des navigateurs depuis des décennies. Mais le système moderne d'identité du navigateur 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 tous des informations de marque, de plateforme, de version et d'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 distinct.

BotBrowser gère tous les signaux User-Agent et Client Hints via des profils et des remplacements CLI. Les profils définissent automatiquement la configuration de base, et les flags CLI fournissent un contrôle à l'exécution pour les identités personnalisées. Cet article explique comment le UA et les Client Hints fonctionnent ensemble, quels signaux comptent et comment les configurer correctement.

Impact sur la vie privée

Le User-Agent et les Client Hints sont parmi les premiers signaux qu'un serveur reçoit. Ils arrivent avec la requête HTTP initiale, avant que tout JavaScript ne s'exécute. Cela en fait une entrée primaire pour le fingerprinting et le suivi côté serveur.

Les risques de confidentialité d'un UA/Client Hints incohérent incluent :

• Détection d'incohérence côté serveur : Les serveurs comparent l'en-tête User-Agent avec les en-têtes Sec-CH-UA sur la même requête. Une incohérence indique une modification.
• Comparaison JavaScript-en-tête : Les pages peuvent comparer navigator.userAgent avec navigator.userAgentData.brands et vérifier l'alignement. Toute divergence est signalée.
• Corrélation des valeurs à haute entropie : getHighEntropyValues() retourne des informations détaillées sur la plateforme, l'architecture et la version. Celles-ci doivent correspondre à l'identité globale.
• Cohérence inter-contextes : Les valeurs UA doivent être cohérentes entre le thread principal, les web workers, les service workers et les en-têtes HTTP. Les remplacements partiels qui n'affectent qu'un contexte créent des écarts détectables.

BotBrowser assure la cohérence sur toutes ces surfaces car il contrôle le UA et les Client Hints au niveau du moteur, avant qu'une requête ne soit envoyée ou que du JavaScript ne s'exécute.

Contexte technique

La chaîne User-Agent

L'en-tête traditionnel User-Agent est une longue chaîne qui identifie le navigateur, la 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 disponible via navigator.userAgent en JavaScript. Bien que les navigateurs réduisent progressivement les informations dans la chaîne UA (la réduction UA de Chrome), elle reste un signal d'identité significatif.

Client Hints (UA-CH)

Les Client Hints fournissent les mêmes informations dans un format structuré via des en-têtes HTTP et des API JavaScript :

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

• Sec-CH-UA : Jetons de marque avec versions majeures. Exemple : "Chromium";v="142", "Google Chrome";v="142", "Not:A-Brand";v="99"
• Sec-CH-UA-Mobile : Si l'appareil est mobile. Exemple : ?0
• Sec-CH-UA-Platform : Système d'exploitation. Exemple : "Windows"

En-têtes à haute entropie (envoyés uniquement lorsque le serveur les demande via Accept-CH) :

• Sec-CH-UA-Full-Version-List : Chaînes de version complètes pour toutes les marques
• Sec-CH-UA-Platform-Version : Version du système d'exploitation (par ex., "15.0.0" pour Windows 11)
• Sec-CH-UA-Arch : Architecture CPU (par ex., "x86")
• Sec-CH-UA-Bitness : Nombre de bits du système (par ex., "64")
• Sec-CH-UA-Model : Modèle d'appareil (principalement pour mobile)

API JavaScript (navigator.userAgentData) :

// Basse entropie (toujours disponible, pas de permission nécessaire)
navigator.userAgentData.brands       // [{brand: "Chromium", version: "142"}, ...]
navigator.userAgentData.mobile       // false
navigator.userAgentData.platform     // "Windows"

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

Jetons GREASE

Chromium ajoute des jetons "GREASE" (Generate Random Extensions And Sustain Extensibility) randomisés aux Client Hints. Ce sont des noms de marque délibérément invalides insérés pour empêcher les serveurs de coder en dur des hypothèses sur les formats de jetons. Une valeur Sec-CH-UA typique inclut un jeton GREASE :

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

Le format du jeton GREASE, la version et la position changent entre les versions de navigateur et les marques. BotBrowser génère les jetons GREASE corrects pour chaque profil et configuration de marque.

Exigences de cohérence

Pour une identité de navigateur crédible, les éléments suivants doivent tous s'aligner :

1. L'en-tête User-Agent correspond à navigator.userAgent
2. Les jetons de marque dans Sec-CH-UA correspondent à navigator.userAgentData.brands
3. La plateforme dans Sec-CH-UA-Platform correspond à navigator.userAgentData.platform
4. La version majeure dans la chaîne UA correspond à la version dans les jetons de marque Sec-CH-UA
5. Les versions complètes dans Sec-CH-UA-Full-Version-List correspondent à getHighEntropyValues().fullVersionList
6. La version de la plateforme est réaliste pour le système d'exploitation revendiqué (par ex., Windows 11 rapporte "15.0.0" ou plus)
7. L'architecture et le nombre de bits correspondent à la plateforme (par ex., x86/64 pour Windows, arm/64 pour Mac série M)
8. Toutes les valeurs sont identiques dans le thread principal, les workers et les en-têtes HTTP

Approches courantes et leurs limitations

Remplacement UA au niveau du framework

Playwright et Puppeteer fournissent des options de remplacement du UA :

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

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

Ces méthodes changent navigator.userAgent et l'en-tête User-Agent mais ne mettent pas à jour :

• Les en-têtes Sec-CH-UA (qui reflètent toujours l'identité réelle du navigateur)
• navigator.userAgentData.brands (inchangé)
• getHighEntropyValues() (retourne les vraies valeurs)
• Le UA au niveau des workers (peut ne pas être cohérent)

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

CDP Network.setUserAgentOverride

CDP fournit 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 les remplacements au niveau du framework mais présente encore des lacunes :

• Nécessite Network.enable, ce qui peut affecter le fingerprinting
• Doit être défini par cible (page, worker)
• La génération de jetons GREASE n'est pas automatique
• L'alignement des versions est manuel et sujet aux erreurs

Injection manuelle d'en-têtes

Définir des en-têtes personnalisés avec page.setExtraHTTPHeaders() peut remplacer les en-têtes Sec-CH-UA, mais les API JavaScript (navigator.userAgentData) retournent toujours les valeurs originales. Cela crée une incohérence entre l'identité au niveau HTTP et au niveau JavaScript.

L'approche de BotBrowser

Configuration automatique basée sur le profil

Les profils BotBrowser contiennent des configurations complètes de UA et Client Hints capturées depuis de vrais environnements de navigateur. 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 (en-tête et JavaScript)
• Tous les en-têtes Client Hints par défaut
• Toutes les valeurs Client Hints à haute entropie
• navigator.userAgentData (marques, plateforme, mobile)
• Les jetons GREASE appropriés pour la version du navigateur
• Des valeurs cohérentes entre le thread principal, les workers et les en-têtes HTTP

Aucun flag supplémentaire n'est nécessaire pour la configuration standard UA/Client Hints.

Remplacements CLI pour les identités personnalisées

Lorsque vous avez besoin de construire une identité personnalisée au-delà de ce que le profil fournit, BotBrowser offre des flags CLI granulaires :

Flags d'identité principaux :

• --bot-config-browser-brand=chrome|edge|brave|opera|webview (ENT Tier2) : Changer la marque du navigateur
• --bot-config-ua-full-version=142.0.7444.60 (ENT Tier2) : Définir la version complète Chromium
• --bot-config-brand-full-version=142.0.3595.65 (ENT Tier2) : Définir la version spécifique à la marque (pour Edge, Opera, etc.)

Flags de plateforme et d'appareil (ENT Tier3) :

• --bot-config-platform=Windows|Android|macOS|Linux : Nom de la plateforme
• --bot-config-platform-version=13 : Chaîne de version du système d'exploitation
• --bot-config-model=SM-G991B : Modèle d'appareil (mobile)
• --bot-config-architecture=x86|arm|arm64 : Architecture CPU
• --bot-config-bitness=32|64 : Nombre de bits du système
• --bot-config-mobile=true|false : Flag d'appareil mobile

User-Agent personnalisé avec espaces réservés :

Le flag --user-agent supporte des espaces réservés remplacés à l'exécution :

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 {platform-version}, {model} et {ua-full-version} par les valeurs des flags correspondants, puis génère automatiquement les navigator.userAgentData et tous les en-têtes Client Hints correspondants.

Cohérence sur toutes les surfaces

BotBrowser assure la cohérence UA/Client Hints sur :

• Les en-têtes HTTP : Tous les en-têtes User-Agent et Sec-CH-UA-* sur chaque requête
• JavaScript du thread principal : navigator.userAgent, navigator.userAgentData
• Web Workers : navigator.userAgent et navigator.userAgentData dans les contextes worker
• Service Workers : Mêmes valeurs disponibles dans le scope du service worker
• Valeurs à haute entropie : getHighEntropyValues() retourne des valeurs cohérentes avec tous les autres signaux

Configuration et utilisation

Utilisation standard du profil

Pour la plupart des cas d'utilisation, le profil gère tout :

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

Remplacement de marque avec alignement de version

Lors du changement de marque, alignez les versions :

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

Exemple de vérification Playwright

const { chromium } = require('playwright-core');

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

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

  // Vérifier la chaîne UA
  const ua = await page.evaluate(() => navigator.userAgent);
  console.log('User-Agent:', ua);

  // Vérifier les Client Hints basse entropie
  const brands = await page.evaluate(() =>
    navigator.userAgentData.brands.map(b => `${b.brand} v${b.version}`)
  );
  console.log('Brands:', brands);

  // Vérifier les Client Hints haute entropie
  const highEntropy = await page.evaluate(async () => {
    return await navigator.userAgentData.getHighEntropyValues([
      'platformVersion', 'architecture', 'bitness',
      'fullVersionList', 'model'
    ]);
  });
  console.log('Platform:', highEntropy.platform);
  console.log('Platform Version:', highEntropy.platformVersion);
  console.log('Architecture:', highEntropy.architecture);
  console.log('Bitness:', highEntropy.bitness);
  console.log('Full Version List:', highEntropy.fullVersionList);

  await browser.close();
})();

Exemple de vérification Puppeteer

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

(async () => {
  const browser = await puppeteer.launch({
    executablePath: '/path/to/botbrowser/chrome',
    args: [
      '--bot-profile=/path/to/profile.enc',
      '--bot-config-browser-brand=edge',
    ],
    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)
  );
  console.log('User-Agent:', ua);
  console.log('Brands:', brands);

  await browser.close();
})();

Vérification

Après avoir configuré le UA et les Client Hints, vérifiez l'alignement :

1. Vérifiez que navigator.userAgent contient le bon nom et la bonne version du navigateur
2. Vérifiez que navigator.userAgentData.brands contient les bons jetons de marque
3. Confirmez que les en-têtes Sec-CH-UA correspondent aux marques rapportées par JavaScript
4. Testez getHighEntropyValues() pour les informations correctes de plateforme, d'architecture et de version
5. Vérifiez la cohérence dans un contexte de Web Worker

Pièges courants à vérifier :

• Windows 11 vs. Windows 10 : Sec-CH-UA-Platform-Version commençant à partir de "15.0.0" indique Windows 11. Les valeurs inférieures indiquent Windows 10. La valeur doit correspondre à la chaîne de version Windows du User-Agent.
• Ordre des jetons de marque : Chaque marque a un ordre spécifique. Vérifiez que le jeton GREASE, le jeton Chromium et le jeton de marque apparaissent dans la bonne séquence.
• Alignement des numéros de version : La version majeure dans la chaîne UA devrait correspondre à la version majeure dans les jetons de marque Sec-CH-UA.

Bonnes pratiques

1. Préférez les profils à la configuration manuelle. Les profils capturent des configurations UA/Client Hints complètes et cohérentes depuis de vrais navigateurs. La configuration manuelle nécessite un alignement minutieux des versions.

2. N'utilisez pas les remplacements UA de Playwright/Puppeteer. Ces remplacements au niveau du framework ne changent que la chaîne UA, pas les Client Hints. Avec les profils BotBrowser, vous n'en avez pas besoin.

3. Gardez des versions réalistes. Utilisez des versions de navigateur récentes et actuelles. Les versions obsolètes sont inhabituelles et attirent l'attention.

4. Alignez les versions spécifiques à la marque. Lors de l'utilisation de --bot-config-browser-brand=edge, définissez --bot-config-brand-full-version avec une vraie version Edge qui correspond à la version majeure Chromium.

5. Testez avec des outils de vérification d'empreinte. Vérifiez que tous les signaux UA et Client Hints s'alignent après chaque changement de configuration.

6. Mettez à jour les profils régulièrement. Les versions de navigateur changent fréquemment. Utilisez des profils actuels pour correspondre aux versions que la plupart des utilisateurs ont.

Questions fréquemment posées

BotBrowser gère-t-il la réduction UA (la chaîne User-Agent réduite de Chrome) ? Oui. Les profils BotBrowser reflètent le format réel de la chaîne UA de la version du navigateur qu'ils représentent, y compris les changements de réduction UA.

Puis-je définir des valeurs UA différentes par contexte de navigateur ? La personnalisation UA par contexte est disponible via l'option userAgent de Playwright, mais cela ne change que la chaîne UA. Pour une cohérence complète des Client Hints, utilisez des instances de navigateur séparées avec différents profils ou paramètres de marque.

Que se passe-t-il si je définis --user-agent sans flags Client Hints ? BotBrowser utilisera la chaîne UA personnalisée mais dérivera les Client Hints du profil. Si la chaîne UA personnalisée est incohérente avec les Client Hints du profil, une incohérence peut survenir. Il est préférable d'utiliser la syntaxe des espaces réservés avec les flags --bot-config-* correspondants.

navigator.userAgentData fonctionne-t-il dans les workers ? Oui. BotBrowser garantit que navigator.userAgentData retourne des valeurs cohérentes dans le thread principal, les web workers et les service workers.

Comment BotBrowser gère-t-il les jetons GREASE ? BotBrowser génère des jetons GREASE correspondant aux schémas observés dans les instances réelles de navigateur pour chaque marque et version. Le format GREASE, le numéro de version et la position sont tous corrects.

Puis-je utiliser des chaînes UA personnalisées avec des caractères spéciaux ? Oui. Le flag --user-agent accepte des chaînes arbitraires. Lors de l'utilisation d'espaces réservés comme {platform-version}, ils sont remplacés par les valeurs des flags correspondants.

getHighEntropyValues() est-il affecté par le consentement utilisateur ? Dans le Chromium standard, getHighEntropyValues() retourne une Promise qui se résout avec les valeurs demandées. Les profils BotBrowser incluent toutes les valeurs à haute entropie du navigateur source, donc la Promise se résout avec des données cohérentes définies par le profil.

Qu'en est-il de l'en-tête Sec-CH-UA-WoW64 ? BotBrowser inclut tous les en-têtes Client Hints standard pour la plateforme. Les hints liés à WoW64 sont correctement définis pour les profils Windows le cas échéant.

Résumé

Les chaînes User-Agent et les Client Hints sont le fondement de l'identité du navigateur au niveau réseau. BotBrowser gère les deux via des profils qui capturent de vraies configurations de navigateur et des flags CLI qui fournissent une personnalisation à l'exécution. Tous les signaux, des en-têtes HTTP aux API JavaScript en passant par les contextes worker, sont cohérents et alignés automatiquement.

Pour le contrôle de l'identité de marque, consultez Changement de marque de navigateur. Pour l'identité géographique, consultez Configuration du fuseau horaire, de la locale et de la langue. Pour l'isolation complète de l'identité, consultez Isolation multi-comptes du navigateur.