User-Agent Client Hints API の移行

ユーザー エージェント文字列に依存しないサイトを移行するための戦略は、 新しい User-Agent Client Hints API について説明します。

Rowan Merewood

User-Agent string は 重要なパッシブ フィンガープリント として認識され、 処理が困難ですただし、Google Cloud で有効なあらゆる種類の ユーザー エージェント データを収集して処理する理由が決まるため、 より優れたソリューションへの道筋を示します。User-Agent Client Hints API を使用すると、 ユーザー エージェントのデータと、そのデータを返すメソッドの必要性を 作成します。

この記事では、user-agent データへのアクセスを監査し、 ユーザー エージェント文字列の使用を User-Agent Client Hints に移行。

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

どのようなデータ収集においても、行動を起こす理由を常に理解する必要があります。 収集します。最初のステップは、 とはいえ、ユーザー エージェント データをどこで、なぜ使用しているのかを把握することです。

user-agent データが使用されているかどうかや、どこで使われているかわからない場合は、検索を検討してください。 navigator.userAgent を使用するためのフロントエンド コードと、 User-Agent HTTP ヘッダーの使用。フロントエンドのコードも確認します。 （すでにサポートが終了している機能（navigator.platform や navigator.appVersion。

機能面では、コード内のどの部分が 記録または処理:

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

また、サードパーティのライブラリまたはサービスを使用して、 処理します。この場合は、最新バージョンに更新されているかどうかを確認します。 User-Agent Client Hints API をサポートしています。

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

User-Agent Client Hints のデフォルトのセットには次のものがあります。

  • Sec-CH-UA: ブラウザ名とメジャー/重要なバージョン
  • Sec-CH-UA-Mobile: モバイル デバイスを示すブール値
  • Sec-CH-UA-Platform: オペレーティング システム名 <ph type="x-smartling-placeholder">
      </ph>
    • これは仕様で更新されており、反映される Chrome その他の Chromium ベースのブラウザについても近日中に対応する予定です。

提案されたユーザー エージェント文字列の短縮版も、 下位互換性が確保されます。たとえば、 Chrome/90.0.4430.85: 文字列には Chrome/90.0.0.0 が含まれます。

ユーザー エージェント文字列のブラウザ名、メジャー バージョン、 動作している場合でも、おそらくはコードを実行しても 非推奨の警告を確認してください。

User-Agent Client Hints に移行することは可能ですが、以前の コードやリソースの制約があるためです。情報量の低減により、 下位互換性のある方法でユーザー エージェント文字列は、 既存のコードでは詳細な情報を受け取らなくてもかまいませんが、 維持します。

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

現在 navigator.userAgent を使用している場合は、 の解析にフォールバックする前に navigator.userAgentData を優先する user-agent 文字列。

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 の値は できます。

戦略: Static server-side ヘッダー

サーバーで User-Agent リクエスト ヘッダーを使用していて、 サイト全体で比較的一貫性がある場合は 必要な Client Hints をレスポンスで静的なセットとして指定するこれは 通常は 1 つのコンテナにのみ構成する必要があるため、比較的シンプルな あります。たとえば、ウェブサーバーの構成に含まれている可能性があります。 ヘッダー、ホスティング構成、トップレベル構成を フレームワークまたはプラットフォームを 変更する必要があります

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

ブラウザや他のクライアントでは、それぞれ異なるデフォルトのヒントが提供されることがあるため、 必要なすべてのものを指定することを推奨します。通常、 あります。

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

⬇️ レスポンス ヘッダー

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

レスポンスでデバイスモデルも受け取りたい場合は、次のようにします。 send:

⬇️ レスポンス ヘッダー

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 API がリクエストで送信される場合は、以下を行う必要があります。 権限ポリシーを使用して目的のヒントを明示的に指定する

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

⬇️ ヒントを委任している 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 属性は、次のすべての Accept-CH ヘッダーをオーバーライドします。 widget.site 自体が送信されることがあるため、 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 と同じ形式です。 ただし、ブラウザには、最初のリクエストが成功した場合はすぐにリクエストを再試行するよう指示します。 1 つは重要なヒントなしで送信されました

😝?️ 最初のリクエスト

[With default headers]

⬇️ レスポンス ヘッダー

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

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

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

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

非常に詳細なヒントが必要な場合は、 Client Hints の信頼性 提案 接続レベルの設定にヒントを指定するため、ルートをレイアウトします。この Application-Layer Protocol を使用する Settings（ALPS）の TLS 拡張機能 HTTP/2 接続と HTTP/3 接続でヒントのこの早期受け渡しを有効にする方法。この まだ初期段階にありますが、独自の TLS とネットワークを 設定が完了していれば、今こそ活動に貢献する絶好の機会です。

戦略: レガシー サポート

サイト内に、 navigator.userAgent（ユーザー エージェント文字列の一部を含む） 削減されます長期的には同等の SKU への移行を計画する必要がある navigator.userAgentData を呼び出しますが、暫定的な解決策があります。

UA-CH レトロフィルは、 navigator.userAgent を新しい文字列で上書きできるライブラリ リクエストされた navigator.userAgentData 値からビルドされます。

たとえば、このコードはユーザー エージェント文字列を生成し、 「モデル」が含まれるヒント:

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 リポジトリ お知らせください。

写真撮影: Ricardo Rocha Unsplash より