User-Agent Client Hints API の移行

ユーザー エージェント文字列への依存から新しい User-Agent Client Hints への移行をサポートする戦略。

公開日: 2021 年 5 月 19 日

ユーザー エージェント文字列は、ブラウザにおける重要なパッシブ フィンガープリント サーフェスであり、処理が困難です。しかし、ユーザー エージェント データを収集して処理する理由はさまざまです。必要なのは、より良いソリューションへの道です。User-Agent Client Hints を使用すると、User-Agent データの必要性を明示的に宣言する方法と、使いやすい形式でデータを返す方法の両方が提供されます。

ここでは、ユーザー エージェント データへのアクセスの監査と、ユーザー エージェント文字列の使用から User-Agent Client Hints への移行について説明します。

Browser Support

  • Chrome: 90.
  • Edge: 90.
  • Firefox: not supported.
  • Safari: not supported.

Source

ユーザー エージェント データの収集と使用を監査する

あらゆる形式のデータの収集と同様に、収集する理由を常に理解しておく必要があります。最初の手順は、何らかのアクションを行うかどうかに関係なく、ユーザー エージェント データをどこで、なぜ使用しているかを把握することです。

ユーザー エージェント データが使用されているかどうか、またはどこで使用されているかわからない場合は、フロントエンド コードで navigator.userAgent の使用を検索し、バックエンド コードで User-Agent HTTP ヘッダーの使用を検索することを検討してください。また、navigator.platform や navigator.appVersion など、すでに非推奨になっている機能が使用されていないか、フロントエンド コードを確認する必要があります。

機能的な観点から、コード内で記録または処理を行っている場所を検討します。

  • ブラウザ名またはバージョン
  • オペレーティング システムの名前またはバージョン
  • デバイスのメーカーとモデル
  • CPU のタイプ、アーキテクチャ、ビット数(64 ビットなど)

また、サードパーティのライブラリやサービスを使用してユーザー エージェントを処理している可能性もあります。この場合は、User-Agent Client Hints をサポートするように更新されているかどうかを確認してください。

基本的なユーザー エージェント データのみを使用していますか?

デフォルトの User-Agent Client Hints には、次のものが含まれます。

  • Sec-CH-UA: ブラウザ名とメジャー / 重要なバージョン
  • Sec-CH-UA-Mobile: モバイル デバイスを示すブール値
  • Sec-CH-UA-Platform: オペレーティング システム名

提案されている情報量削減後のユーザー エージェント文字列でも、この基本情報は下位互換性を維持した形で保持されます。たとえば、Chrome/90.0.4430.85 ではなく、文字列に Chrome/90.0.0.0 が含まれます。

ブラウザ名、メジャー バージョン、オペレーティング システムのユーザー エージェント文字列のみを確認している場合は、非推奨の警告が表示される可能性がありますが、コードは引き続き機能します。

User-Agent Client Hints への移行は可能であり、推奨されますが、レガシーコードやリソースの制約により移行できない場合があります。この下位互換性のある方法でユーザー エージェント文字列の情報を削減することで、既存のコードが受け取る情報は詳細ではなくなりますが、基本的な機能は維持されます。

戦略

ユーザー エージェント文字列の使用を User-Agent Client Hints に移行するには、いくつかの方法があります。

オンデマンドのクライアントサイド JavaScript API

navigator.userAgent を使用している場合は、ユーザー エージェント文字列の解析にフォールバックする前に、navigator.userAgentData を優先するように移行する必要があります。

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

モバイルまたはパソコンを確認する場合は、ブール値 mobile を使用します。

const isMobile = navigator.userAgentData.mobile;

userAgentData.brands は、brand プロパティと version プロパティを持つオブジェクトの配列です。ブラウザは、これらのブランドとの互換性を一覧表示できます。配列として直接アクセスすることも、some() 呼び出しを使用して特定のエントリが存在するかどうかを確認することもできます。

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
}

より詳細な高エントロピーのユーザー エージェント値が必要な場合は、その値を指定して、返された Promise の結果を確認する必要があります。

navigator.userAgentData.getHighEntropyValues(['model'])
  .then(ua => {
    // requested hints available as attributes
    const model = ua.model
  });

この戦略は、サーバーサイド処理からクライアントサイド処理に移行する場合にも使用できます。JavaScript API は HTTP リクエスト ヘッダーへのアクセスを必要としないため、ユーザー エージェント値はいつでもリクエストできます。

静的サーバーサイド ヘッダー

サーバーで User-Agent リクエスト ヘッダーを使用しており、そのデータのニーズがサイト全体で比較的安定している場合は、レスポンスで Client Hints を静的セットとして指定できます。通常は 1 か所で構成するだけでよいため、比較的簡単なアプローチです。たとえば、ウェブサーバーの構成にヘッダーを追加している場合は、その構成、ホスティング構成、またはサイトで使用しているフレームワークやプラットフォームの最上位の構成にヘッダーを追加します。

ユーザー エージェント データに基づいて提供されるレスポンスを変換またはカスタマイズする場合は、この戦略を検討してください。

ブラウザやその他のクライアントは、異なるデフォルトのヒントを提供することを選択する場合があります。そのため、一般的にデフォルトで提供されている場合でも、必要なものをすべて指定することをおすすめします。

たとえば、Chrome の現在のデフォルトは次のように表されます。

⬇️ レスポンス ヘッダー

Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Platform, Sec-CH-UA

レスポンスでデバイスモデルも受け取る場合は、次のように送信します。

⬇️ レスポンス ヘッダー

Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Model, Sec-CH-UA-Platform, Sec-CH-UA

サーバーサイドでこれを処理する場合は、まず目的の Sec-CH-UA ヘッダーが送信されているかどうかを確認し、送信されていない場合は User-Agent ヘッダーの解析にフォールバックする必要があります。

クロスオリジン リクエストにヒントを委任する

リクエストで User-Agent Client Hints を送信する必要があるクロスオリジンまたはクロスサイトのサブリソースをリクエストする場合は、権限ポリシーを使用して、必要なヒントを明示的に指定する必要があります。

たとえば、https://blog.site が https://cdn.site でリソースをホストし、特定のデバイスに最適化されたリソースを返すことができるとします。https://blog.site は Sec-CH-UA-Model ヒントをリクエストできますが、Permissions-Policy ヘッダーを使用して https://cdn.site に明示的に委任する必要があります。ポリシーで制御されるヒントのリストは、Client Hints Infrastructure のドラフトで確認できます。

⬇️ ヒントを委任する blog.site からのレスポンス

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

⬆️ cdn.site のサブリソースへのリクエストに委任されたヒントが含まれる

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

ch-ua 範囲だけでなく、複数のオリジンに複数のヒントを指定できます。

⬇️ 複数のヒントを複数のオリジンに委任する blog.site からのレスポンス

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")

iframe にヒントを委任する

クロスオリジンの iframe は、クロスオリジンのリソースと同様に機能しますが、委任するヒントを allow 属性で指定します。

⬇️ blog.site からの回答

Accept-CH: Sec-CH-UA-Model

↪️ blog.site の HTML

<iframe src="https://widget.site" allow="ch-ua-model"></iframe>

⬆️ widget.site へのリクエスト

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

iframe の allow 属性は、widget.site が自身で送信する Accept-CH ヘッダーをオーバーライドします。そのため、iframe のサイトが必要とするすべてのものを指定してください。

動的なサーバーサイド ヒント

ユーザー ジャーニーの特定の部分で、サイトの他の部分よりも多くのヒントが必要な場合は、サイト全体で静的にリクエストするのではなく、オンデマンドでリクエストできます。この方法は管理が複雑になりますが、ルートごとに異なるヘッダーをすでに設定している場合は、実現可能かもしれません。

ここで重要なのは、Accept-CH ヘッダーの各インスタンスが既存のセットを効果的に上書きすることです。したがって、ヘッダーを動的に設定する場合は、各ページで必要なヒントの完全なセットをリクエストする必要があります。

たとえば、サイトの 1 つのセクションで、ユーザーのオペレーティング システムに一致するアイコンとコントロールを提供するとします。この場合、適切なサブリソースを提供するために、Sec-CH-UA-Platform-Version を追加で pull することをおすすめします。

⬇️ /blog のレスポンス ヘッダー

Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Platform, Sec-CH-UA

⬇️ /app のレスポンス ヘッダー

Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Platform, Sec-CH-UA-Platform-Version, Sec-CH-UA

最初のリクエストで必要なサーバーサイドのヒントに対処する

最初の要求でデフォルトのヒントセットよりも多くのヒントが必要になる場合もありますが、これはまれなケースであるため、理由をよく確認してください。

最初のリクエストとは、そのブラウジング セッションで送信された、そのオリジンに対する最初のトップレベル リクエストを意味します。デフォルトのヒントセットには、メジャー バージョンを含むブラウザ名、プラットフォーム、モバイル インジケーターが含まれます。ここで考えるべきことは、最初のページ読み込み時に拡張データが必要かどうかです。

最初のヒント リクエストには 2 つのオプションがあります。まず、Critical-CH ヘッダーを使用できます。これは Accept-CH と同じ形式ですが、最初のリクエストが重要なヒントなしで送信された場合は、すぐにリクエストを再試行する必要があることをブラウザに伝えます。

⬆️ 初回リクエスト

[With default headers]

⬇️ レスポンス ヘッダー

Accept-CH: Sec-CH-UA-Model
Critical-CH: Sec-CH-UA-Model

🔃 ブラウザが追加のヘッダーを使用して最初のリクエストを再試行する

[With default headers + …]
Sec-CH-UA-Model: Pixel 5

これにより、最初のリクエストで再試行のオーバーヘッドが発生しますが、実装コストは比較的低くなります。追加のヘッダーを送信すると、残りの処理はブラウザが行います。

最初のページ読み込みで追加のヒントが本当に必要な状況では、Client Hints Reliability の提案により、接続レベルの設定でヒントを指定するルートが提示されています。これは、TLS 1.3 のアプリケーション レイヤ プロトコル設定(ALPS)拡張機能を利用して、HTTP/2 接続と HTTP/3 接続でヒントを早期に渡すことができるようにします。これはまだ初期段階ですが、独自の TLS と接続設定を積極的に管理している場合は、今が貢献する絶好の機会です。

従来のサポート

サイトに、navigator.userAgent に依存する以前のコードやサードパーティ コードが存在する可能性があります。これには、削減されるユーザー エージェント文字列の一部が含まれます。同等の navigator.userAgentData 呼び出しに移行することを計画する必要がありますが、暫定的な解決策があります。

UA-CH retrofill は、リクエストされた navigator.userAgentData 値から作成された新しい文字列で navigator.userAgent を上書きできる小さなライブラリです。

たとえば、次のコードは、「model」ヒントを含むユーザー エージェント文字列を生成します。

import { overrideUserAgentUsingClientHints } from './uach-retrofill.js';
overrideUserAgentUsingClientHints(['model'])
  .then(() => { console.log(navigator.userAgent); });

結果の文字列には Pixel 5 モデルが表示されますが、uaFullVersion ヒントがリクエストされなかったため、縮小された 92.0.0.0 が表示されます。

Mozilla/5.0 (Linux; Android 10.0; Pixel 5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.0.0 Mobile Safari/537.36

その他のサポート

これらの戦略でユースケースに対応できない場合は、privacy-sandbox-dev-support リポジトリでディスカッションを開始してください。一緒に問題を調査いたします。