Stratégies pour migrer votre site de la chaîne user-agent vers les nouveaux User-Agent Client Hints.
Date de publication : 19 mai 2021
La chaîne User-Agent est une surface d'empreinte passive importante dans les navigateurs, et elle est difficile à traiter. Cependant, il existe toutes sortes de raisons valables de collecter et de traiter les données user-agent. Il est donc nécessaire de trouver une meilleure solution. Les User-Agent Client Hints permettent de déclarer explicitement votre besoin de données user-agent et de renvoyer les données dans un format facile à utiliser.
Nous allons vous expliquer comment auditer votre accès aux données user-agent et migrer l'utilisation des chaînes user-agent vers les User-Agent Client Hints.
Auditer la collecte et l'utilisation des données user-agent
Comme pour toute forme de collecte de données, vous devez toujours comprendre pourquoi vous les collectez. La première étape, que vous preniez ou non des mesures, consiste à comprendre où et pourquoi vous utilisez les données user-agent.
Si vous ne savez pas si les données user-agent sont utilisées ou à quel endroit, recherchez l'utilisation de navigator.userAgent dans votre code d'interface et l'utilisation de l'en-tête HTTP User-Agent dans votre code de backend. Vous devez également vérifier que votre code d'interface n'utilise pas de fonctionnalités déjà obsolètes, telles que navigator.platform et navigator.appVersion.
D'un point de vue fonctionnel, pensez à tous les endroits de votre code où vous enregistrez ou traitez :
- Nom ou version du navigateur
- Nom ou version du système d'exploitation
- Marque ou modèle de l'appareil
- Type, architecture ou nombre de bits du processeur (par exemple, 64 bits)
Il est également probable que vous utilisiez une bibliothèque ou un service tiers pour traiter le user-agent. Dans ce cas, vérifiez s'ils sont mis à jour pour prendre en charge les User-Agent Client Hints.
Utilisez-vous uniquement les données de base du user-agent ?
L'ensemble par défaut de User-Agent Client Hints comprend :
Sec-CH-UA: nom du navigateur et version majeure/significativeSec-CH-UA-Mobile: valeur booléenne indiquant un appareil mobileSec-CH-UA-Platform: nom du système d'exploitation
La version réduite de la chaîne user-agent proposée conservera également ces informations de base de manière rétrocompatible. Par exemple, au lieu de Chrome/90.0.4430.85, la chaîne inclurait Chrome/90.0.0.0.
Si vous ne vérifiez que le nom du navigateur, la version majeure ou le système d'exploitation dans la chaîne user-agent, votre code continuera de fonctionner, même si vous verrez probablement des avertissements d'abandon.
Bien que vous puissiez et deviez migrer vers les User-Agent Client Hints, il est possible que vous ayez du code ancien ou des contraintes de ressources qui vous en empêchent. La réduction des informations dans la chaîne user-agent de manière rétrocompatible vise à garantir que, même si le code existant reçoit des informations moins détaillées, il conserve ses fonctionnalités de base.
Stratégies
Il existe plusieurs stratégies pour migrer l'utilisation de la chaîne user-agent vers les User-Agent Client Hints.
API JavaScript côté client à la demande
Si vous utilisez navigator.userAgent, vous devez passer à navigator.userAgentData avant de revenir à l'analyse de la chaîne user-agent.
if (navigator.userAgentData) {
// use new hints
} else {
// fall back to user-agent string parsing
}
Si vous effectuez une vérification pour mobile ou ordinateur, utilisez la valeur booléenne mobile :
const isMobile = navigator.userAgentData.mobile;
userAgentData.brands est un tableau d'objets avec les propriétés brand et version, où le navigateur peut lister sa compatibilité avec ces marques. Vous pouvez y accéder directement en tant que tableau ou utiliser un appel some() pour vérifier si une entrée spécifique est présente :
function isCompatible(item) {
// In real life you most likely have more complex rules here
return ['Chromium', 'Google Chrome', 'NewBrowser'].includes(item.brand);
}
if (navigator.userAgentData.brands.some(isCompatible)) {
// browser reports as compatible
}
Si vous avez besoin d'une des valeurs de user-agent plus détaillées et à entropie élevée, vous devez la spécifier et vérifier le résultat dans le Promise renvoyé :
navigator.userAgentData.getHighEntropyValues(['model'])
.then(ua => {
// requested hints available as attributes
const model = ua.model
});
Vous pouvez également utiliser cette stratégie si vous souhaitez passer du traitement côté serveur au traitement côté client. L'API JavaScript ne nécessite pas d'accès aux en-têtes de requête HTTP. Les valeurs user-agent peuvent donc être demandées à tout moment.
En-tête statique côté serveur
Si vous utilisez l'en-tête de requête User-Agent sur le serveur et que vos besoins concernant ces données sont relativement cohérents sur l'ensemble de votre site, vous pouvez spécifier les indications du client sous forme d'ensemble statique dans vos réponses. Il s'agit d'une approche relativement simple, car vous n'avez généralement besoin de la configurer qu'à un seul endroit. Par exemple, il peut se trouver dans la configuration de votre serveur Web si vous y ajoutez déjà des en-têtes, dans la configuration de votre hébergement ou dans la configuration de premier niveau du framework ou de la plate-forme que vous utilisez pour votre site.
Envisagez cette stratégie si vous transformez ou personnalisez les réponses diffusées en fonction des données de l'user-agent.
Les navigateurs ou d'autres clients peuvent choisir de fournir des indications par défaut différentes. Il est donc recommandé de spécifier tout ce dont vous avez besoin, même si cela est généralement fourni par défaut.
Par exemple, les valeurs par défaut actuelles pour Chrome seraient représentées comme suit :
⬇️ En-têtes de réponse
Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Platform, Sec-CH-UA
Si vous souhaitez également recevoir le modèle de l'appareil dans les réponses, vous devez envoyer :
⬇️ En-têtes de réponse
Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Model, Sec-CH-UA-Platform, Sec-CH-UA
Lors du traitement côté serveur, vous devez d'abord vérifier si l'en-tête Sec-CH-UA souhaité a été envoyé, puis revenir à l'analyse de l'en-tête User-Agent s'il n'est pas disponible.
Déléguer des indications aux requêtes multi-origines
Si vous demandez des sous-ressources interorigines ou intersites qui nécessitent l'envoi de User-Agent Client Hints dans leurs requêtes, vous devez spécifier explicitement les hints souhaités à l'aide d'une règle d'autorisation.
Par exemple, supposons que https://blog.site héberge des ressources sur https://cdn.site, qui peut renvoyer des ressources optimisées pour un appareil spécifique.
https://blog.site peut demander l'indice Sec-CH-UA-Model, mais doit le déléguer explicitement à https://cdn.site à l'aide de l'en-tête Permissions-Policy. La liste des indices contrôlés par des règles est disponible dans le brouillon de l'infrastructure Client Hints.
⬇️ Réponse de blog.site déléguant l'indice
Accept-CH: Sec-CH-UA-Model
Permissions-Policy: ch-ua-model=(self "https://cdn.site")
⬆️ Les requêtes adressées aux sous-ressources sur cdn.site incluent l'indice délégué
Sec-CH-UA-Model: "Pixel 5"
Vous pouvez spécifier plusieurs indications pour plusieurs origines, et pas seulement à partir de la plage ch-ua :
⬇️ Réponse de blog.site déléguant plusieurs indices à plusieurs origines
Accept-CH: Sec-CH-UA-Model, DPR
Permissions-Policy: ch-ua-model=(self "https://cdn.site"),
ch-dpr=(self "https://cdn.site" "https://img.site")
Déléguer des indices aux iFrames
Les iFrames interorigines fonctionnent de la même manière que les ressources interorigines, mais vous spécifiez les indices que vous souhaitez déléguer dans l'attribut allow.
⬇️ Réponse de blog.site
Accept-CH: Sec-CH-UA-Model
↪️ HTML pour blog.site
<iframe src="https://widget.site" allow="ch-ua-model"></iframe>
⬆️ Demande envoyée à widget.site
Sec-CH-UA-Model: "Pixel 5"
L'attribut allow de l'iframe remplace tout en-tête Accept-CH que widget.site peut envoyer lui-même. Assurez-vous donc d'avoir spécifié tout ce dont le site de l'iframe aura besoin.
Conseils dynamiques côté serveur
Si vous avez besoin d'une plus grande sélection d'indices dans certaines parties du parcours utilisateur que dans le reste du site, vous pouvez choisir de demander ces indices à la demande plutôt que de manière statique sur l'ensemble du site. Cette méthode est plus complexe à gérer, mais si vous définissez déjà des en-têtes différents par route, elle peut être envisageable.
Il est important de noter que chaque instance de l'en-tête Accept-CH écrasera l'ensemble existant. Par conséquent, si vous définissez l'en-tête de manière dynamique, chaque page doit demander l'ensemble complet des indices requis.
Par exemple, vous pouvez avoir une section sur votre site où vous souhaitez fournir des icônes et des commandes correspondant au système d'exploitation de l'utilisateur. Pour cela, vous pouvez également extraire Sec-CH-UA-Platform-Version pour diffuser les sous-ressources appropriées.
⬇️ En-têtes de réponse pour /blog
Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Platform, Sec-CH-UA
⬇️ En-têtes de réponse pour /app
Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Platform, Sec-CH-UA-Platform-Version, Sec-CH-UA
Résoudre le problème des indications côté serveur requises lors de la première requête
Dans certains cas, vous aurez peut-être besoin d'un ensemble d'indications plus important que celui par défaut dès la première requête. Toutefois, cela devrait être rare. Assurez-vous donc d'avoir bien examiné le raisonnement.
La première requête correspond à la toute première requête de niveau supérieur pour cette origine envoyée au cours de cette session de navigation. L'ensemble d'indices par défaut inclut le nom du navigateur avec la version majeure, la plate-forme et l'indicateur mobile. La question à se poser est la suivante : avez-vous besoin de données étendues lors du chargement initial de la page ?
Pour obtenir des conseils supplémentaires sur la première requête, deux options s'offrent à vous. Tout d'abord, vous pouvez utiliser l'en-tête Critical-CH. Il utilise le même format que Accept-CH, mais indique au navigateur qu'il doit immédiatement relancer la requête si la première a été envoyée sans l'indice critique.
⬆️ Requête initiale
[With default headers]
⬇️ En-têtes de réponse
Accept-CH: Sec-CH-UA-Model
Critical-CH: Sec-CH-UA-Model
🔃 Le navigateur relance la requête initiale avec l'en-tête supplémentaire.
[With default headers + …]
Sec-CH-UA-Model: Pixel 5
Cela entraîne des frais généraux de nouvelle tentative dès la première requête, mais le coût de mise en œuvre est relativement faible. Envoyez l'en-tête supplémentaire et le navigateur s'occupera du reste.
Si vous avez vraiment besoin d'indices supplémentaires lors du tout premier chargement de la page, la proposition de fiabilité des indices client définit une méthode pour spécifier des indices dans les paramètres au niveau de la connexion. Cette fonctionnalité utilise l'extension ALPS (Application-Layer Protocol Settings) de TLS 1.3 pour permettre la transmission anticipée d'indices sur les connexions HTTP/2 et HTTP/3. Cette fonctionnalité n'en est qu'à ses débuts, mais si vous gérez activement vos propres paramètres TLS et de connexion, c'est le moment idéal pour contribuer.
Compatibilité héritée
Il est possible que votre site contienne du code ancien ou tiers qui dépend de navigator.userAgent, y compris des parties de la chaîne user-agent qui seront réduites. Vous devez prévoir de passer aux appels navigator.userAgentData équivalents, mais il existe une solution provisoire.
UA-CH retrofill est une petite bibliothèque qui vous permet de remplacer navigator.userAgent par une nouvelle chaîne créée à partir des valeurs navigator.userAgentData demandées.
Par exemple, ce code génère une chaîne user-agent qui inclut également l'indice "model" :
import { overrideUserAgentUsingClientHints } from './uach-retrofill.js';
overrideUserAgentUsingClientHints(['model'])
.then(() => { console.log(navigator.userAgent); });
La chaîne obtenue affiche le modèle Pixel 5, mais affiche toujours la valeur 92.0.0.0 réduite, car l'indice uaFullVersion n'a pas été demandé :
Mozilla/5.0 (Linux; Android 10.0; Pixel 5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.0.0 Mobile Safari/537.36
Assistance supplémentaire
Si ces stratégies ne répondent pas à votre cas d'utilisation, lancez une discussion dans le dépôt privacy-sandbox-dev-support afin que nous puissions examiner votre problème ensemble.