オープンソースのユーザーエージェント ルックアップテーブル

このリポジトリには、正規化され、厳選されたユーザーエージェント文字列のデータセットが含まれており、JSONファイルとして保存されています。ルックアップテーブルとして利用し、ユーザーエージェントクライアントやオペレーティングシステムといった、シンプルなデータを導出することを目的としています。

PageviewsOnline のコンポーネントとして使用されますが、ここでは汎用用途として公開されています。

データセットは、データを検証し、他のフォーマットやプログラミング言語（例：Java）へエクスポートするための、シンプルなヘルパースクリプトによって補完されています。

プロジェクトの理念

このプロジェクトの目的は、完璧に正確なユーザーエージェント検出システムを提供することではなく、実用的でベストエフォートな解決策を提供し、実世界での利用とコミュニティの貢献を通じて時間とともに改善していくことです。

ユーザーエージェントの検出は本来不完全です。完全な正確さを追求する代わりに、このプロジェクトは次の点に焦点を当てています：

• 実用的
• 保守性が高い
• 透明
• 現実世界の分析と分類にも十分対応できます。

正確さは、厳選された更新、実世界での使用、そしてコミュニティの貢献を通じて、時間とともに向上します。

ヒューリスティック解析と複雑な正規表現は、しばしば予測可能性を犠牲にして、わずかな精度向上を得る。

このプロジェクトは以下を重視しています：

• 透明性は魔法より大切
• 不透明なロジックより、厳選されたデータ
• 推測的な検出よりも、説明可能な結果を重視

機能

• 正規化済みで、人の手によって検証されたユーザーエージェントデータセット
• シンプルで予測可能なルックアップ動作
• JSONベースの形式、閲覧がしやすく、バージョン管理もしやすい
• 軽量な検証スクリプト
• 他の言語向けのヘルパーをエクスポート（例：Java）
• 本番環境のSaaSで積極的に活用されています

正規化されたユーザーエージェント文字列

このプロジェクトの主な目的は、ユーザーエージェント文字列から高レベルかつ安定した情報を、迅速かつ予測可能な方法で抽出することです。

この目的を実現するため、処理前に各ユーザーエージェント文字列を正規化します。正規化は、バージョン番号や大文字小文字の差異といった不安定な変動を取り除く一方で、ユーザーエージェントの構造的・意味論的意味を保持します。

ユーザーエージェント文字列は、以下の手順で正規化されます。

• すべての数字 (0-9) をプレースホルダー文字の x に置換します。これにより、バージョン変更によるノイズを取り除きつつ、トークンの構造と長さを維持します。
• 文字列全体を小文字に変換します。User agent tokensは慣例として大文字と小文字を区別しません。小文字化は一貫性のある信頼性の高い検索を保証します。

例えば、以下のユーザーエージェント文字列です：

以下の値に正規化されます：

この正規化アプローチは、ユーザーエージェントを時間とともにグループ化・比較・維持しやすくします。一方で、高レベルのクライアントおよびOSの分類にも十分な精度を保ちます。

バージョン固有の差異や大文字小文字のばらつきを排除することで、ルックアップ処理をより予測可能にし、今後のユーザーエージェントの変更にも耐性を高めます。

データ形式

各正規化されたユーザーエージェントエントリには、次の項目が含まれます:

• id - 正規化されたユーザーエージェント文字列
• client_family - ハイレベルなクライアント分類（例：ブラウザ、ボット、アプリ）
• os_family - 高レベルのOS分類

データセットの成長に伴い、正確なフィールドは時間とともに変化することがあります。

ルックアップの挙動

ユーザーエージェントのマッチングは、正規化された文字列に対して行われます。

正確な一致を優先します。部分一致やヒューリスティックなマッチングは、挙動を予測可能でデバッグしやすくするため、意図的に避けられています。

貢献

ご協力を歓迎します。本プロジェクトの品質と正確さの向上に役立ちます。

最も効果的な貢献の方法は、user_agents.json ファイルに正規化済みのユーザーエージェントエントリを追加または更新し、関連する分類データも合わせて提供することです。

変更の準備が整い次第、必要なデータおよび/またはコードの更新を含むプルリクエストを提出してください。

部分的または不完全な情報でも有用で、感謝されています。すべての貢献が、網羅性と長期的な信頼性の向上に役立ちます。

はじめに（クイックガイド）

このプロジェクトの核は、data/ ディレクトリにある一連の JSON データファイルです。

このデータの維持と再利用を支援するため、リポジトリには基本的な検証とエクスポート作業を行う、いくつかのシンプルな Node.js スクリプトが含まれています。

よく使われるコマンド:

• npm run test - JSONデータを検証し、構造的エラーまたは整合性エラーをチェックします。
• npm run build - 正規化したデータをビルドし、整理・ソートして、Java などの他のプログラミング言語のフォーマットへエクスポートし、統合をより容易にします。

これらのツールは意図的に最小限に抑えられており、データの正確性と移植性に焦点を当て、複雑な処理にはこだわっていません。

ユーザーエージェント文字列は信頼できません

ユーザーエージェント文字列から正確な情報を導き出すことは、いくつかの理由により本質的に信頼性が低いです:

• ユーザーエージェント文字列の構造や内容を規定する公式な標準や仕様は存在しません。
• 多くのユーザーエージェントは、互換性とレガシー対応のために、意図的に他のユーザーエージェントを偽装または模倣します。

そのため、ユーザーエージェントデータを完全に正確かつ一貫して特定することは極めて難しいです。

このライブラリは、保証された事実や権威ある情報の源ではなく、最善を尽くした解決策として捉えるべきです。

継続的な使用とコミュニティの貢献により、時間の経過とともに精度は向上することがあります。

バージョン管理と安定性

ユーザーエージェントの進化に伴い、データセットは時間とともに変化することがあります。

分類は、マイナーバージョン間でも破壊的な変更とはみなされません。

結果は最善の努力によるヒントとして扱うべきで、契約上の保証にはなりません。

ライセンス

このプロジェクトとそのデータは、Apache License 2.0（Apache-2-0）に基づいて公開されています。

商業利用、改変、および再配布を許可します。

ご協力を歓迎し、感謝しています。

商標

PageviewsOnline、Two-Dot-Oh、および関連するロゴ、サービス名、またはブランドはTwo-Dot-Ohの商標です。

このプロジェクトはオープンソースです。ただし、PageviewsOnline の名称や関連ブランド表現を、製品・サービス・提供物と関連づけて使用することは、事前の書面による同意がない限り許可されません。

フォーク（分岐）および派生作品は、別の名称とブランディングを使用し、PageviewsOnline または Two-Dot-Oh からの承認を示唆したり、同社との提携を示唆してはならない。