tracker

Tracker SDKは、Vibe CodingなどのAI支援ツールで作られるモダンなWebアプリケーションへの迅速な統合を目的とした、最小サイズのウェブ分析ライブラリです。シンプルさを重視し、単一の`init`コールでコレクターエンドポイントを構成するだけで、ページビューは自動的に記録され、`track(eventName, data)`でカスタムイベントを送信できます。 **主な機能** - **ゼロ構成スタート** – スクリプトタグを1つ追加するか、npm importするだけでデータ収集を開始できます。 - **自動ページビュー検出** – SDKはナビゲーションイベントを監視し、追加コードなしで`pageview`ペイロードを送信します。 - **カスタムイベント追跡** – 開発者は名前とオプションのペイロードを指定して`track`を呼び出すことで、あらゆるインタラクションをログ記録できます。 - **デバイス指紋** – キャンバスベースの指紋がプライバシーを尊重しながら訪問者を一意に識別します。 - **オフラインキュー** – 送信に失敗したイベントはローカルストレージに保存され、後で再試行され、データ損失を最小限に抑えます。 - **セッション管理** – セッションは自動的に作成され、設定可能なタイムアウト（デフォルト30分）後に期限切れになります。 - **設定可能なバッチ処理** – イベントは1つのリクエストにグループ化され、ネットワークオーバーヘッドが削減されます。 **インストール** - **CDN** – HTMLでUMDバンドルを直接読み込み、`WFTK.init({ endpoint: 'https://your-api.com/api/v1/collect/event', debug: true })` を呼び出します。 - **npm** – `npm install @weavefox/tracker`、その後 `import { init, track, setUserId } from '@weavefox/tracker';` でインポートします。 **公開API** | メソッド | 目的 | |--------|---------| | `init(config)` | エンドポイント、appId、およびオプションのフラグでSDKを初期化します。 | | `track(eventName, data)` | カスタムイベントを送信します。 | | `trackPageview(data)` | ページビューを手動で記録します（デフォルトで自動有効）。 | | `setUserId(userId)` | ログオン済みのユーザーを後のイベントに関連付けます。 | | `getFingerprint()` | 生成されたデバイス指紋を取得します。 | | `flush()` | キューのすべてのイベントを即座に送信します。 | **設定オプション** ```javascript WFTK.init({ endpoint: 'required', // コレクターサービスのURL appId: 'optional', // アプリケーションの識別子 autoPageview: true, // ページビューの自動追跡 debug: false, // コンソールデバッグを有効化 enableQueue: true, // ネットワーク失敗時にイベントをオフライン保存 sessionTimeout: 1800000, // セッションアイドルタイムアウト（ms、デフォルト30分） maxEventsPerSession: 1000 // セッションあたりの最大イベント数 }); ``` **ペイロード形式** – 各リクエストには、オプションの`appId`と`events`配列を含むJSON本文が含まれます。各イベントには必須の`event`名、`timestamp`、`nonce`（重複除去用）、`fingerprint`、およびシステム収集コンテキスト（URL、タイトル、デバイス情報など）を含む`data`オブジェクトが含まれます。ユーザー定義フィールドは`biz`サブオブジェクトに配置し、分析データとビジネスデータを分離します。 **サーバーサイドの考慮事項** - **タイムスタンプ検証** – リプレイ攻撃を防ぐため、5分以上前のイベントを拒否します。 - **Nonce重複除去** – Nonce（例：Redis）を24時間のTTLで保存し、冪等性を保証します。 - **レート制限** – 不正利用を防ぐためIPごとおよびフィンガープリントごとの制限を適用します。 - **アプリ識別** – ペイロード内の明示的な`appId`を優先し、必要に応じてリクエストの`Referer`ホストにフォールバックします。 - **Expressハンドラー例** – READMEには、タイムスタンプの検証、Nonceの確認、イベントの永続化を行う簡潔なNode.jsスニペットが掲載されています。 **ライセンス** – MITライセンスの下で配布され、オープンソースおよび商業プロジェクトの両方で無制限の使用が許可されています。 総合的に、Tracker SDKは重厚なプラットフォームのオーバーヘッドなしに、信頼性の高いクライアントサイド分析を必要とする開発者向けの、シンプルでプライバシーを考慮したソリューションを提供します。