Migrer vers les indicateurs client user-agent

Stratégies pour faire passer votre site de la chaîne user-agent au code de nouveaux indicateurs client User-Agent.

Rowan Merewood

Le User-Agent chaîne est le fingerprinting passif de Google surface dans les navigateurs, tout en étant difficile à traiter. Cependant, il existe toutes sortes des raisons de collecter et de traiter les données des user-agents. Vous devez donc sur la voie d'une meilleure solution. Les indicateurs client user-agent fournissent à la fois un moyen explicite de déclarer votre besoin de données et de méthodes user-agent pour renvoyer les données dans un facile à utiliser.

Cet article vous explique comment vérifier votre accès aux données des user-agents et la migration de l'utilisation des chaînes user-agent vers les hints client user-agent.

Auditer la collecte et l'utilisation des données des user-agents

Comme pour toute forme de collecte de données, vous devez toujours comprendre pourquoi vous les collectent. La première étape, que vous soyez est de comprendre où et pourquoi vous utilisez les données des user-agents.

Si vous ne savez pas si ou où les données des user-agents sont utilisées, lancez une recherche votre code d'interface pour utiliser navigator.userAgent et votre code backend pour l'utilisation de l'en-tête HTTP User-Agent. Vous devez également vérifier votre code d'interface pour l'utilisation de fonctionnalités déjà obsolètes, telles que navigator.platform et navigator.appVersion

D'un point de vue fonctionnel, pensez à toutes les parties du code où vous vous trouvez enregistrement ou traitement:

  • Nom ou version du navigateur
  • Nom ou version du système d'exploitation
  • Marque ou modèle de l'appareil
  • Type de processeur, architecture ou débit (par exemple, 64 bits)

Il est également probable que vous utilisiez une bibliothèque ou un service tiers pour pour traiter le user-agent. Dans ce cas, vérifiez s'ils passent à la version prend en charge les hints client user-agent.

Utilisez-vous uniquement des données user-agent de base ?

L'ensemble par défaut d'indicateurs client User-Agent comprend les éléments suivants:

  • Sec-CH-UA: nom du navigateur et version majeure/significative
  • Sec-CH-UA-Mobile: valeur booléenne indiquant un appareil mobile
  • Sec-CH-UA-Platform: nom du système d'exploitation <ph type="x-smartling-placeholder">
      </ph>
    • Notez que cela a été mis à jour dans les spécifications et qu'il sera reflété dans Chrome et d'autres navigateurs basés sur Chromium prochainement.

La version réduite de la chaîne de user-agent proposée ces informations de base d'une manière rétrocompatible. Par exemple, au lieu de Chrome/90.0.4430.85, la chaîne comprend Chrome/90.0.0.0.

Si vous ne vérifiez que la chaîne du user-agent pour le nom du navigateur, la version majeure ou système d'exploitation, votre code continuera à fonctionner, même si vous êtes pour afficher les avertissements d'abandon.

Bien que vous puissiez et devriez migrer vers les hints client user-agent, vous disposez peut-être les contraintes de code ou de ressources qui empêchent cela. La réduction de l'information la chaîne user-agent de cette manière rétrocompatible vise à garantir que le code existant recevra des informations moins détaillées, et conservent les fonctionnalités de base.

Stratégie: API JavaScript côté client à la demande

Si vous utilisez actuellement navigator.userAgent, vous devriez passer à en privilégiant navigator.userAgentData avant de revenir à l'analyse du de la chaîne user-agent.

if (navigator.userAgentData) {
  // use new hints
} else {
  // fall back to user-agent string parsing
}

Si vous recherchez un appareil mobile ou un ordinateur, utilisez la valeur booléenne mobile:

const isMobile = navigator.userAgentData.mobile;

userAgentData.brands est un tableau d'objets avec brand et version. propriétés permettant au navigateur de répertorier sa compatibilité avec celles marques. Vous pouvez y accéder directement sous forme de tableau ou utiliser un 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 de l'une des valeurs de user-agent les 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 du traitement côté serveur au traitement côté client. L'API JavaScript ne permet pas ont besoin d'accéder aux en-têtes de requêtes HTTP. Les valeurs de user-agent peuvent donc être demandées à l'adresse à tout moment.

Stratégie: en-tête statique côté serveur

Si vous utilisez l'en-tête de requête User-Agent sur le serveur et selon vos besoins pour ces données sont relativement cohérentes sur l'ensemble de votre site, vous pouvez spécifier les hints client souhaités sous forme d'ensemble statique dans vos réponses. Il s'agit d'un cette approche est relativement simple, car il suffit généralement de la configurer l'emplacement. Par exemple, il se peut qu'elle figure dans la configuration de votre serveur Web si vous avez déjà ajoutez-y les en-têtes, la configuration d'hébergement ou la configuration de premier niveau le framework ou la plate-forme que vous utilisez pour votre site.

Utilisez cette stratégie si vous transformez ou personnalisez les réponses. diffusées en fonction des données du user-agent.

Les navigateurs ou autres clients peuvent choisir de fournir des indications par défaut différentes. il est recommandé de spécifier tout ce dont vous avez besoin, même s'ils sont généralement fournis par par défaut.

Par exemple, les valeurs par défaut actuelles de Chrome sont 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 d'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 les fichiers L'en-tête Sec-CH-UA a été envoyé, puis l'en-tête User-Agent a été remplacé s'il n'est pas disponible.

Stratégie: déléguer des indices aux demandes d'origine croisée

Si vous demandez des sous-ressources multi-origines ou intersites qui nécessitent utiliser les hints client user-agent dans leurs demandes, vous devrez alors spécifier explicitement les indications souhaitées à 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 la déléguer explicitement à https://cdn.site à l'aide de Permissions-Policy en-tête. La liste des suggestions contrôlées par des règles est disponible dans la section Clients Hints Infrastructure brouillon

⬇️ Réponse de blog.site qui délègue l'indice

Accept-CH: Sec-CH-UA-Model
Permissions-Policy: ch-ua-model=(self "https://cdn.site")

⩍️ Les demandes de sous-ressources sur cdn.site incluent l'indice délégué

Sec-CH-UA-Model: "Pixel 5"

Vous pouvez spécifier plusieurs suggestions pour plusieurs origines, et pas seulement à partir de la plage ch-ua:

⬇️ Réponse de blog.site qui délègue 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")

Stratégie: déléguer des suggestions à des cadres iFrame

Les iFrames multi-origines fonctionnent de la même manière que les ressources multi-origines, spécifiez les optimisations 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 à widget.site

Sec-CH-UA-Model: "Pixel 5"

L'attribut allow dans l'iFrame remplace tout en-tête Accept-CH qui widget.site peut s'envoyer automatiquement. Assurez-vous donc d'avoir spécifié tous les éléments du site avec des cadres iFrame.

Stratégie: conseils dynamiques côté serveur

Si vous avez des parties spécifiques du parcours utilisateur où vous avez besoin d'une plus grande sélection que sur le reste du site, vous pouvez choisir de les demander à la demande plutôt que de manière statique sur l'ensemble du site. C'est plus complexe à mais si vous avez déjà défini différents en-têtes pour chaque route, réalisables.

N'oubliez pas que chaque instance de Accept-CH va écraser l'ensemble existant. Ainsi, si vous êtes dynamiquement définir l'en-tête, chaque page doit demander l'ensemble complet d'indications requises.

Par exemple, votre site peut contenir une section des icônes et des commandes correspondant au système d'exploitation de l'utilisateur. Pour cela, vous pouvez souhaitez également extraire Sec-CH-UA-Platform-Version pour diffuser les bonnes sous-ressources.

⬇️ 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

Stratégie: conseils côté serveur requis lors de la première demande

Dans certains cas, vous avez besoin d'autres indications que celles par défaut sur la de votre première demande, mais cela risque d'être rare. examiné le raisonnement.

La première requête correspond en fait à la toute première requête de niveau supérieur pour cette origine. envoyé dans cette session de navigation. Par défaut, les optimisations incluent le navigateur avec la version majeure, la plate-forme et l'indicateur pour mobile. Donc la question posez-vous la question 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 utilisez l'en-tête Critical-CH. Son format est identique à Accept-CH. mais indique au navigateur qu'il doit immédiatement relancer la requête une a été envoyée sans l'indice critique.

⧖️ Demande 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 liés à la nouvelle tentative lors de la toute première requête, mais le coût d'implémentation est relativement faible. Envoyer l'en-tête supplémentaire et le navigateur s'occupe du reste.

Dans les cas où vous avez besoin de conseils supplémentaires chargement de la première page, la section Client Hints Reliability proposition une route pour spécifier des indications dans les paramètres de connexion. Ce utilise le protocole de couche application Settings(ALPS) du protocole TLS. 1.3 pour permettre le transfert anticipé d'indications sur les connexions HTTP/2 et HTTP/3. Ce n’en est encore qu’à un stade précoce, mais si vous gérez activement vos propres paramètres de connexion, c'est le moment idéal pour apporter votre contribution.

Stratégie: compatibilité avec les anciennes versions

Il est possible que votre site contienne du code ancien ou tiers qui dépend navigator.userAgent, y compris les parties de la chaîne user-agent qui seront réduit. À long terme, il est préférable de prévoir de passer à une solution navigator.userAgentData, mais il existe une solution provisoire.

Le remplissage UA-CH est un petit fichier permettant d'écraser navigator.userAgent par une nouvelle chaîne créé à partir des valeurs navigator.userAgentData demandées.

Par exemple, ce code génère une chaîne user-agent qui, en plus inclut le "modèle" Indice:

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 le modèle réduit 92.0.0.0 en tant qu'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 correspondent pas à votre cas d'utilisation, veuillez démarrer une discussion dans privacy-sandbox-dev-support dépôt et nous pourrons examiner ensemble votre problème.

Photo par Ricardo Rocha sur Unsplash