User-Agent et Client Hints : garder une identité cohérente

Une même identité doit rester identique dans l'en-tête User-Agent, les Client Hints et navigator.userAgentData. BotBrowser aligne ces surfaces, y compris celles des workers ; il ne peut pas changer ce qu'un serveur fait de cette identité ni vous dispenser d'aligner la version complète sur la version majeure de Chromium du binaire.

Résumé rapide

Comparez quatre surfaces : la chaîne navigator.userAgent, les Client Hints à faible et haute entropie, les valeurs d'un Worker et les en-têtes de la requête. Si l'une diffère, retirez toute surcharge de page ou de CDP et laissez les flags du navigateur fixer l'identité.

Sommaire du guide

• Pourquoi l'en-tête User-Agent, les Client Hints et userAgentData doivent concorder
• Les surfaces qui doivent concorder
• Pourquoi une surcharge de framework ou de CDP laisse des écarts
• Régler un User-Agent personnalisé dans BotBrowser
• Vérifier l'identité dans la page, dans un worker et dans la requête
• Choisir les valeurs et planifier selon les limites

Pourquoi l'en-tête User-Agent, les Client Hints et userAgentData doivent concorder

L'en-tête User-Agent est la plus ancienne manière pour un navigateur de se décrire auprès d'un site web. Pendant des années, c'était une longue chaîne regroupant le nom du navigateur, la version complète, le système d'exploitation et le moteur de rendu. Chrome a depuis réduit le niveau de détail de cette chaîne, et les informations structurées sont passées aux User-Agent Client Hints, généralement abrégés en UA-CH. Une même identité de navigateur s'exprime donc désormais à plusieurs endroits à la fois : l'en-tête de requête User-Agent, la famille d'en-têtes de requête Sec-CH-UA, la chaîne navigator.userAgent et l'API navigator.userAgentData. BotBrowser peut garder cohérents la chaîne User-Agent, les Client Hints et les valeurs navigator d’un profil dans un contexte contrôlé ; il ne peut pas changer ce qu’un serveur décide de faire de cette identité.

Une identité personnalisée vaut donc ce que vaut sa surface la plus faible. Si vous ne changez que la chaîne, l'en-tête dit une chose, Sec-CH-UA en dit une autre et navigator.userAgentData une troisième. Chaque surface est valide isolément, mais ensemble elles décrivent un navigateur qui n'existe pas.

Cela compte pour la confidentialité comme pour le simple confort d'usage. L'en-tête User-Agent et les indices à faible entropie arrivent avec la première requête, avant l'exécution du moindre script, si bien que le serveur les voit avant le chargement de la page. Les pages et les scripts d'analyse peuvent ensuite relire les mêmes faits par JavaScript et les comparer. Lorsque les réponses diffèrent, la combinaison est en elle-même inhabituelle et rend la session plus facile à distinguer. Cela provoque aussi des pannes ordinaires, par exemple un serveur qui choisit une mise en page mobile d'après l'en-tête User-Agent alors qu'un script lit une plateforme de bureau dans navigator.userAgentData.

Trois groupes de lecteurs rencontrent ce problème le plus souvent. Les équipes qui testent un site pour des visiteurs Android ou Edge ont besoin que le navigateur se décrive partout comme ce type de visiteur. Les personnes qui gardent plusieurs identités de navigation séparées pour des raisons de confidentialité ont besoin que chaque identité reste stable et cohérente en elle-même. Les ingénieurs du support qui reproduisent le signalement d'un client ont besoin que la reproduction porte la même identité que celle du client. Tous dépendent de la concordance entre surfaces, pas d'une valeur isolée.

Avant de modifier quoi que ce soit, trois questions sont utiles :

• Quelles surfaces rapportent l'identité, et changeront-elles toutes ensemble ?
• Tous les numéros de version appartiennent-ils à la même version majeure de Chromium ?
• Le reste de la configuration, comme la langue régionale, le fuseau horaire et la route réseau, décrit-il toujours un navigateur cohérent ?

Les surfaces qui doivent concorder

Les navigateurs basés sur Chromium se décrivent au moyen de quatre groupes de valeurs. Chacun est présenté ci-dessous, suivi d'une courte liste des concordances que vous pouvez vérifier.

La chaîne User-Agent

L'en-tête de requête User-Agent et navigator.userAgent portent la même chaîne. Sur Chrome de bureau, elle ressemble à ceci :

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

Avec la réduction du User-Agent de Chrome, les parties système d'exploitation et version de cette chaîne sont maintenues à des valeurs génériques, et les parties mineures de la version sont figées. La chaîne est toujours envoyée avec chaque requête et reste la première chose lue par la plupart des serveurs. Elle doit donc rester alignée sur les valeurs structurées qui ont remplacé le détail qu'elle ne porte plus. Pour le contexte des standards et une migration pas à pas de l’analyse du User-Agent vers les Client Hints, consultez Migrer de User-Agent Reduction vers Client Hints.

Les en-têtes de requête Client Hints

Les Client Hints exposent les mêmes faits sous forme structurée. Les indices à faible entropie sont envoyés par défaut avec les requêtes :

• Sec-CH-UA liste des jetons de marque avec leur version majeure, par exemple "Chromium";v="142", "Google Chrome";v="142", "Not:A-Brand";v="99".
• Sec-CH-UA-Mobile indique si le navigateur est mobile, par exemple ?0.
• Sec-CH-UA-Platform nomme le système d'exploitation, par exemple "Windows".

Les indices à haute entropie ne sont envoyés qu'après qu'un serveur les a demandés avec un en-tête de réponse Accept-CH :

• Sec-CH-UA-Full-Version-List porte les versions complètes de chaque marque.
• Sec-CH-UA-Platform-Version porte la version du système d'exploitation.
• Sec-CH-UA-Arch et Sec-CH-UA-Bitness portent l'architecture du processeur et le nombre de bits.
• Sec-CH-UA-Model porte le modèle de l'appareil, surtout utile sur mobile.

Comme les indices détaillés sont envoyés sur demande, un écart dans ces valeurs peut rester invisible jusqu'à ce qu'un site les demande. Une configuration qui semble correcte au premier chargement peut se contredire au second. Pour voir comment ces en-têtes sont utilisés et où ils divergent, consultez Client Hints Fingerprinting : en-têtes HTTP et identité, qui compare les valeurs des en-têtes à celles de JavaScript pour une même session.

navigator.userAgentData et getHighEntropyValues

Le pendant JavaScript de ces informations est navigator.userAgentData. Ses propriétés brands, mobile et platform reprennent les en-têtes à faible entropie. Les valeurs détaillées viennent de getHighEntropyValues(), qui renvoie une promesse :

navigator.userAgentData.brands;
navigator.userAgentData.mobile;
navigator.userAgentData.platform;
await navigator.userAgentData.getHighEntropyValues([
  'platformVersion',
  'architecture',
  'bitness',
  'fullVersionList',
  'model',
]);

Ce que disent les en-têtes, ces propriétés doivent le dire aussi. La spécification définit l'API et les noms d'en-têtes ensemble, ce qui explique pourquoi les deux se lisent comme une seule description.

Portée des Workers

Un worker dédié, un worker partagé et un service worker ont chacun leur propre objet navigator. Un worker qui rapporte un User-Agent ou un userAgentData différent de ceux de la page qui l'a lancé constitue une incohérence nette, puisque le worker appartient au même navigateur. Toute approche qui modifie les valeurs sur la page seulement, et non dans la portée du worker, laisse cet écart ouvert.

Entrées GREASE et alignement des versions

Chromium ajoute à la liste des marques une entrée GREASE volontairement dépourvue de sens, comme "Not:A-Brand";v="99". Son texte, sa version et sa position changent d'une version du navigateur à l'autre. Le but est d'empêcher les serveurs de dépendre d'un format de liste figé : une liste écrite à la main qui se trompe sur l'entrée ou la place au mauvais endroit se distingue donc d'une liste réelle.

Les numéros de version demandent le même soin. La version majeure de la chaîne User-Agent, les versions de Sec-CH-UA et les entrées de fullVersionList doivent toutes décrire la même version de Chromium. Une version complète 142.0.7444.60 à un endroit et une version majeure 140 à un autre forment un désaccord, même si tous les noms de marque sont justes.

Les concordances que vous pouvez vérifier

Mise bout à bout, une identité crédible satisfait cette liste :

1. L'en-tête User-Agent correspond à navigator.userAgent.
2. Les jetons de marque de Sec-CH-UA correspondent à navigator.userAgentData.brands.
3. La plateforme de Sec-CH-UA-Platform correspond à navigator.userAgentData.platform.
4. La version majeure de la chaîne User-Agent correspond aux versions des jetons de marque de Sec-CH-UA.
5. Les versions complètes de Sec-CH-UA-Full-Version-List correspondent à fullVersionList de getHighEntropyValues().
6. La version de plateforme est une valeur réelle pour le système d'exploitation annoncé.
7. L'architecture et le nombre de bits conviennent à la plateforme, par exemple x86 et 64 pour un poste Windows.
8. Chaque valeur est identique dans le fil principal, dans les workers et dans les en-têtes de requête HTTP.

Pourquoi une surcharge de framework ou de CDP laisse des écarts

Les frameworks d'automatisation rendent la chaîne facile à modifier. Playwright accepte une option userAgent à la création d'un contexte, et Puppeteer propose page.setUserAgent() :

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

Une surcharge limitée à la chaîne modifie toujours l'en-tête User-Agent et navigator.userAgent ; le reste dépend de l'appel. Mesuré le 2026-10-23 avec Playwright 1.58.0 et Puppeteer 24.40.0 :

• browser.newContext({ userAgent }) de Playwright a aussi dérivé des métadonnées de plateforme : la page et le Worker annonçaient alors la nouvelle plateforme, tandis que la marque et les versions pouvaient encore décrire le Chromium sous-jacent.
• page.setUserAgent('Custom UA String') de Puppeteer a laissé navigator.userAgentData avec des marques et des valeurs structurées vides, et non les valeurs d'origine.

Ne supposez donc ni « l'identité d'origine subsiste » ni « toute l'identité suit la chaîne ». Lisez la page, le Worker et les en-têtes de requête sur la build que vous utilisez ; c'est le relevé à quatre surfaces ci-dessus qui vous dit dans quel cas vous êtes.

Le Chrome DevTools Protocol propose Network.setUserAgentOverride avec un objet facultatif userAgentMetadata. C'est plus complet, car il peut porter les marques, la plateforme et les autres indices. Le travail revient pourtant sur vous. La liste des marques, l'entrée GREASE, les versions complètes et les champs de plateforme doivent être écrits à la main et tenus alignés sur la chaîne. La surcharge s'applique à la cible à laquelle elle a été envoyée, si bien que chaque page et chaque worker demande son propre appel, et une liste correcte pour une version de Chromium devient périmée à la suivante.

Définir des en-têtes supplémentaires pose le même genre de problème. Une règle qui réécrit Sec-CH-UA sur le réseau modifie la requête, mais pas ce que renvoie navigator.userAgentData dans la page. L'identité diffère alors entre la couche réseau et la couche script. Pour définir des en-têtes de requête supplémentaires dans BotBrowser par une option, un profil ou CDP, voir En-têtes HTTP personnalisés dans BotBrowser : option, profil ou CDP.

Ce sont des limites générales des approches qui réécrivent une surface à la fois. Une règle d'en-têtes, une surcharge de chaîne et un script qui modifie une propriété couvrent chacun leur propre surface, et rien ne garantit que les surfaces concordent encore ensuite. La solution fiable consiste à choisir l'identité une seule fois et à faire dériver chaque surface de ce choix.

Régler un User-Agent personnalisé dans BotBrowser

Un profil BotBrowser fournit déjà une base cohérente. Il contient une chaîne User-Agent, des valeurs Client Hints et des champs userAgentData qui concordent entre eux, de sorte que le charger évite de régler chaque surface séparément. Les options ci-dessous ne servent que lorsqu'un test doit représenter un environnement différent du profil conservé.

L'option --user-agent reçoit la chaîne brute et fonctionne avec un ensemble d'options --bot-* qui décrivent la partie structurée. Le User-Agent personnalisé et le contrôle complet de userAgentData nécessitent une licence ENT Tier3 :

Option	Contrôle	Exemple
--user-agent	La chaîne User-Agent brute	Mozilla/5.0 (Linux; ...)
--bot-platform	La plateforme dans userAgentData	Windows, Android
--bot-platform-version	La version du système d'exploitation	13, 10.0
--bot-model	Le modèle de l'appareil, surtout sur mobile	SM-G991B
--bot-architecture	L'architecture du processeur	x86, arm
--bot-bitness	Le nombre de bits du système	32, 64
--bot-mobile	L'indicateur mobile dans userAgentData	true, false

La valeur de --user-agent peut contenir des marqueurs remplacés au démarrage du navigateur. {platform}, {platform-version}, {model}, {architecture} et {bitness} prennent leur valeur dans les options --bot-* correspondantes, et {ua-full-version}, {ua-major-version} et {brand-full-version} la prennent dans les options de version. Les marqueurs gardent la chaîne et les valeurs structurées reliées à une seule source, de sorte que vous ne pouvez pas changer le modèle à un endroit et oublier l'autre.

Deux options complémentaires fixent les versions. --bot-ua-full-version (ENT Tier2) fixe la version complète de Chromium, et --bot-brand-full-version (ENT Tier2) fixe la version propre à la marque pour des marques comme Edge. La documentation recommande de garder --bot-ua-full-version aligné sur la version majeure de Chromium de votre binaire BotBrowser. Pour savoir comment la marque elle-même est choisie et vérifiée entre Chrome, Edge et Brave, consultez Changement de marque : Chrome, Edge, Brave, Opera, qui explique comment la définir au lancement.

Une identité Android sur un poste de bureau ressemble à ceci :

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

BotBrowser remplace {platform-version}, {model} et {ua-full-version} par les valeurs des options, puis génère le navigator.userAgentData correspondant, les marques avec une entrée GREASE correcte, les valeurs à haute entropie et les en-têtes de requête Client Hints. Selon la documentation de BotBrowser, le résultat reste cohérent dans le fil principal, les Workers et les requêtes HTTP.

Une identité de bureau Windows suit le même schéma avec d'autres valeurs :

chrome --bot-profile="path/to/windows-profile.enc" \
       --user-agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/{ua-full-version} Safari/537.36" \
       --bot-platform=Windows \
       --bot-platform-version=10.0 \
       --bot-architecture=x86 \
       --bot-bitness=64 \
       --bot-mobile=false \
       --bot-ua-full-version=142.0.7444.60

Playwright et Puppeteer transmettent les mêmes options par leur paramètre args, et non par un réglage userAgent du framework. Transmettez les options par args, comme le font les exemples de la documentation. Pour changer la marque elle-même, qui est un contrôle ENT Tier2 distinct, consultez l'article sur les marques cité à la fin.

Vérifier l'identité dans la page, dans un worker et dans la requête

Après le lancement, vous pouvez vérifier le résultat dans le navigateur sans outil supplémentaire. Le but est de lire la même identité dans chacun des trois endroits où un site peut la lire.

Commencez par la page. Ouvrez les outils de développement sur une page quelconque et exécutez ces lignes dans la console :

navigator.userAgent;
navigator.userAgentData.brands;
navigator.userAgentData.platform;
await navigator.userAgentData.getHighEntropyValues([
  'platformVersion',
  'architecture',
  'bitness',
  'fullVersionList',
  'model',
]);

Vérifiez ensuite la requête. Ouvrez le panneau Réseau, sélectionnez une requête HTTPS de premier niveau et lisez ses en-têtes. Les en-têtes User-Agent, Sec-CH-UA, Sec-CH-UA-Mobile et Sec-CH-UA-Platform doivent concorder avec ce que la console a affiché. Les en-têtes détaillés, comme Sec-CH-UA-Full-Version-List, n'apparaissent que lorsque le site les demande avec Accept-CH : leur absence sur une première requête est donc normale et ne constitue pas un désaccord.

Enfin, vérifiez la portée des workers. Ce court extrait démarre un worker dédié à partir d'un blob et affiche ce que le worker rapporte :

const worker = new Worker(
  URL.createObjectURL(new Blob(['postMessage([navigator.userAgent, navigator.userAgentData.platform])']))
);
worker.onmessage = event => console.log(event.data);

Les deux valeurs affichées par le worker doivent correspondre à celles de la page. Si vos pages utilisent un service worker, inspectez-le depuis le panneau Application et exécutez les deux mêmes expressions dans sa console.

Quand quelque chose semble anormal, le symptôme désigne souvent la cause :

Symptôme	Cause probable	Ce qu'il faut ajuster
Un marqueur comme {model} apparaît tel quel dans la chaîne	L'option --bot-* correspondante est absente	Définissez --bot-model ou retirez le marqueur
L'en-tête indique Android mais userAgentData.platform indique Windows	--bot-platform n'a pas été défini	Ajoutez --bot-platform=Android et les autres options de plateforme
Les versions de Sec-CH-UA diffèrent de la chaîne User-Agent	L'option de version ne correspond pas à la version majeure de Chromium	Alignez --bot-ua-full-version sur la version de Chromium du binaire
La chaîne a changé mais les indices ne l'ont pas suivie	La chaîne a été définie par une option du framework	Passez-la avec --user-agent dans args
Le worker rapporte des valeurs différentes de celles de la page	Un script ou une surcharge de page n'a modifié que la page	Retirez la surcharge de page et gardez les options du navigateur

Répétez la vérification après chaque changement de profil, de version de Chromium ou d'options d'identité, car chacun peut déplacer une surface sans déplacer les autres. Une vérification réussie montre que le navigateur est cohérent avec lui-même. Elle ne montre pas comment un site particulier traitera la session, car les sites combinent de nombreuses entrées et changent leurs propres règles avec le temps.

Choisir les valeurs et planifier selon les limites

Les options font concorder les surfaces entre elles. Elles ne choisissent pas à votre place des valeurs raisonnables, et la qualité du résultat dépend donc de ce que vous saisissez :

• Utilisez des versions réalistes et actuelles. Une version de navigateur que presque plus personne n'utilise est inhabituelle en soi, alors suivez la version majeure de Chromium de votre binaire.
• Choisissez des valeurs qui vont ensemble. Une plateforme, une version de plateforme, un modèle, une architecture et un nombre de bits doivent décrire un type d'appareil réel.
• Accordez les réglages environnants. L'identité, le fuseau horaire, la langue régionale, la langue et la route réseau doivent décrire le même type de visiteur.
• Gardez une seule identité pendant toute la vie d'une session ou d'un compte. Changer la chaîne entre deux visites du même site crée un historique incohérent.
• Relancez la vérification après les mises à jour du navigateur ou des profils.

Un profil chargé contient déjà une identité cohérente, et omettre --user-agent évite donc une modification inutile. Présentez une autre identité seulement si le test l'exige, par exemple pour reproduire sur un poste de bureau un incident propre à Android, puis vérifiez chaque surface. Chaque surcharge ajoute une valeur à maintenir alignée ; limitez-la donc au besoin du test.

Quelques questions pratiques reviennent souvent :

• Que se passe-t-il si je définis --user-agent sans les options --bot-* correspondantes ? Définissez l'option --bot-* correspondant à chaque marqueur utilisé ; par exemple, {model} exige --bot-model. La documentation recommande d'utiliser la syntaxe des marqueurs avec les options correspondantes.
• L'identité atteint-elle les workers ? Oui. Selon la documentation, les valeurs restent cohérentes dans le fil principal, les Workers et les requêtes HTTP, et la vérification ci-dessus permet de le confirmer.
• Faut-il une licence pour une configuration limitée au profil ? Aucune option personnalisée n'intervient : les valeurs capturées dans le profil sont utilisées. Le contrôle complet de userAgentData avec un User-Agent personnalisé nécessite une licence ENT Tier3.
• Une identité personnalisée modifie-t-elle les fonctionnalités du navigateur ? Les options modifient les valeurs d'identité rapportées. Elles n'ajoutent pas de fonctionnalités que le navigateur sous-jacent n'a pas, alors testez les pages qui comptent pour vous après un changement.

BotBrowser prend en charge un --user-agent personnalisé avec marqueurs, ainsi que --bot-platform, --bot-platform-version, --bot-model, --bot-architecture, --bot-bitness et --bot-mobile, et il génère des marques Client Hints, des valeurs à haute entropie et des en-têtes HTTP concordants, cohérents dans le fil principal, les Workers et les requêtes. Cela remplace la comptabilité manuelle décrite plus haut par une seule identité à vérifier au lieu de plusieurs. BotBrowser ne peut pas faire accepter à un site une identité choisie, ne remplace pas le choix de valeurs de version réalistes et actuelles, et un User-Agent personnalisé avec contrôle complet de userAgentData nécessite une licence ENT Tier3.

Pour changer la marque du navigateur, consultez Incohérences de marque de navigateur dans Chrome, Edge et Brave. Pour voir comment les sites utilisent les Client Hints, consultez Client Hints Fingerprinting : en-têtes HTTP et identité. Pour associer l'identité à des réglages géographiques, consultez Fuseau horaire, langue régionale et langue.

Ce que cette page ajoute à la référence

La page de référence énumère l’option User-Agent et les options associées. Elle ne fournit pas de relevé que vous puissiez comparer entre deux lancements, et un écart se lit mal sans lui, car une surcharge de framework masque la surface qui a réellement bougé.

Surface	Où la lire	Ce qu’un écart signale
Page	Console de la page	La surcharge a agi mais a laissé un jeu incomplet
Worker	Console du Worker	Un correctif au niveau page qui n’atteint pas le Worker
Requête	Panneau Réseau, requête	Une réécriture sur le fil que la page ne voit pas
Hints	getHighEntropyValues() dans la page	Une politique de permissions ou une surcharge qui a laissé l’ensemble à haute entropie incomplet

Enregistrez les quatre lectures avant de modifier le profil. Exécutez ces trois expressions dans la page, puis les deux mêmes dans un Worker, puis ouvrez le panneau Réseau et copiez les en-têtes de requête dans le même fichier. Gardez un fichier par lancement, nommé d’après mode, et comparez les deux fichiers plutôt que de refaire la vérification de mémoire.

// la page et le Worker acceptent cette forme
const identity = {
  ua: navigator.userAgent,
  brands: navigator.userAgentData?.brands?.map(b => `${b.brand}/${b.version}`),
  mobile: navigator.userAgentData?.mobile,
  platform: navigator.userAgentData?.platform,
};
identity.high = await navigator.userAgentData.getHighEntropyValues([
  'platformVersion',
  'architecture',
  'bitness',
  'fullVersionList',
]);
console.log(JSON.stringify(identity));

Si le relevé de la page et celui du Worker diffèrent, quelque chose sous la page réécrit l’identité. Dans un framework qui ne patche que le thread principal, c’est la cause habituelle ; dans la build que vous testez, confirmez-le en désactivant la surcharge et en répétant les deux relevés, car d’autres mécanismes peuvent produire le même écart. Tant que la surcharge reste en place, régler les options ne comblera pas l’écart. Si les en-têtes de requête et le relevé de la page diffèrent, le changement n’a eu lieu que sur le fil. Si high est vide, vérifiez la politique de permissions ch-ua-high-entropy-values de cette page : getHighEntropyValues() ne renvoie les valeurs que là où la politique les autorise. Une page qui n’a jamais demandé les indices détaillés au serveur peut tout de même les retourner, et une page qui a envoyé Accept-CH peut refuser l’API : vérifiez donc séparément l’API et les en-têtes de requête plutôt que de conclure que la configuration est cassée.

Sources

• Documentation BotBrowser : Custom User-Agent
• Chrome for Developers : réduction du User-Agent
• WICG : spécification User-Agent Client Hints
• MDN : NavigatorUAData
• RFC 8942 : HTTP Client Hints

Conclusion pratique

Traitez l'identité comme un enregistrement unique : chaîne, userAgentData, Worker et en-têtes doivent provenir des mêmes flags et de la même version. Si un worker renvoie des valeurs différentes de celles de la page, retirez d'abord la surcharge de page et gardez les quatre observations avant de modifier le profil.