agent-analytics

エージェント分析 — エージェントが実際に活用できる分析

Agent Analytics を使って分析トラッキングを追加します。Agent Analytics は、AI エージェントが実際に活用できる分析プラットフォームです。多くのプロジェクトをリリースし、AI エージェントにすべてのプロジェクトの追跡、分析、実験、最適化を任せたい開発者向けに構築されています。

ウェブサイト： agentanalytics.sh GitHub： Agent-Analytics/agent-analytics ドキュメント： docs.agentanalytics.sh

このスキルを使う場面

• ユーザーがウェブサイトやアプリに分析トラッキングを追加したい
• ユーザーがプロジェクトの状況（トラフィック、コンバージョン、エンゲージメント）を確認したい
• ユーザーが見出し、CTA、フローの A/B 実験を実施したい
• ユーザーがファネル分析、リテンションコホート、トラフィックの内訳を確認したい
• ユーザーが「サイトの調子はどう？」や「訪問者はいる？」と尋ねた

基本方針

Mixpanel のように、すべてをトラッキングするわけではありません。トラッキングするのは、**「このプロジェクトは稼働し、成長しているか？」**に答えるものだけです。

一般的なサイトなら、自動で記録されるページビューに加えるカスタムイベントは、最大でも 3〜5 個です。

初回セットアップ

API キーを取得する： agentanalytics.sh で登録し、ダッシュボードからキーを生成します。または、GitHub からオープンソース版をセルフホストできます。

プロジェクトにまだトラッキングが設定されていない場合：

# 1. Login (one time — uses your API key)
npx @agent-analytics/cli login --token aak_YOUR_API_KEY

# 2. Create the project (returns a project write token)
npx @agent-analytics/cli create my-site --domain https://mysite.com

# 3. Add the snippet using the returned token
# 4. Deploy, click around, verify:
npx @agent-analytics/cli events my-site

create コマンドはプロジェクト書き込みトークンを返します。スニペットの data-token に設定してください。これは API キー（読み取り／クエリ用）とは別のものです。

ステップ 1：トラッキングスニペットを追加する

create コマンドが返す、プロジェクトトークンを含むトラッキングスニペットを </body> の前に追加します。このスニペットは、パス、リファラー、ブラウザー、OS、デバイス、画面サイズ、UTM パラメーターを含む page_view イベントを自動でトラッキングします。カスタムの page_view イベントを追加する必要はありません。

ステップ 1b：既存のイベントを確認する（既存プロジェクトの場合）

すでにトラッキングが設定されている場合は、イベントとプロパティキーの命名をそろえられるよう、現在使われているものを確認します。

npx @agent-analytics/cli properties-received PROJECT_NAME

ステップ 2：重要なアクションにカスタムイベントを追加する

重要な要素には onclick ハンドラーを使います。

<a href="..." onclick="window.aa?.track('EVENT_NAME', {id: 'ELEMENT_ID'})">

SaaS サイトの 80％で使える標準イベント

該当するものを選んでください。ほとんどのサイトでは 2〜4 個必要です。

イベント	発生させるタイミング	プロパティ
cta_click	ユーザーが行動喚起ボタンをクリックしたとき	id（どのボタンか）
signup	ユーザーがアカウントを作成したとき	method（github/google/email）
login	ユーザーが再訪してログインしたとき	method
feature_used	ユーザーが主要機能を利用したとき	feature（どの機能か）
checkout	ユーザーが支払いフローを開始したとき	plan（free/pro/etc）
error	目に見える形で問題が発生したとき	message、page

トラッキングしないもの

• すべてのリンクやボタン（ノイズが多すぎます）
• スクロール深度（実行可能なアクションにつながりません）
• フォームフィールドの操作（細かすぎます）
• フッターのリンク（有益な情報が少ないため）

プロパティの命名ルール

• snake_case を使います。heroGetStarted ではなく hero_get_started とします
• id プロパティは、どの要素かを識別します。短く、わかりやすい名前にします
• ID は section_action の形式で付けます。例：hero_signup、pricing_pro、nav_dashboard

ステップ 2b：A/B 実験を実施する

実験では、ページ要素のどのバリアントのコンバージョン率が高いかを検証できます。ライフサイクル全体を API で操作できるため、ダッシュボードの UI は必要ありません。

実験を作成する

npx @agent-analytics/cli experiments create my-site \
  --name signup_cta --variants control,new_cta --goal signup

バリアントを実装する

宣言型（推奨）： data-aa-experiment と data-aa-variant-{key} の HTML 属性を使います。元のコンテンツが対照群になります。トラッカーが割り当てられたバリアントに応じて、テキストを自動的に置き換えます。

<h1 data-aa-experiment="signup_cta" data-aa-variant-new_cta="Start Free Trial">Sign Up</h1>

プログラム型（複雑なケース）： window.aa?.experiment(name, variants) を使います。判定は決定論的で、同じユーザーには常に同じバリアントが割り当てられます。

結果を確認する

npx @agent-analytics/cli experiments get exp_abc123

ベイズ推定による probability_best、lift、recommendation が返されます。結果が有意になるには、システムで各バリアントにつき約 100 回の表示が必要です。

ステップ 3：すぐにテストする

トラッキングを追加したら、動作を確認します。

# Click around, then check:
npx @agent-analytics/cli events PROJECT_NAME
# Events appear within seconds.

CLI リファレンス

すべてのコマンドで npx @agent-analytics/cli を使用します：

# Setup
login --token aak_YOUR_KEY           # Save API key (one time)
projects                              # List all projects
create my-site --domain https://...   # Create project

# Real-time
live                                  # Live TUI dashboard across ALL projects
live my-site                          # Live view for one project

# Analytics
stats my-site --days 7                # Overview: events, users, daily trends
insights my-site --period 7d          # Period-over-period comparison
breakdown my-site --property path --event page_view --limit 10  # Top pages/referrers/UTM
pages my-site --type entry            # Landing page performance & bounce rates
sessions-dist my-site                 # Session engagement histogram
heatmap my-site                       # Peak hours & busiest days
events my-site --days 30              # Raw event log
sessions my-site                      # Individual session records
properties my-site                    # Discover event names & property keys
funnel my-site --steps "page_view,signup,purchase"  # Funnel drop-off
retention my-site --period week --cohorts 8         # Cohort retention

# A/B experiments
experiments list my-site
experiments create my-site --name signup_cta --variants control,new_cta --goal signup
experiments get exp_abc123
experiments complete exp_abc123 --winner new_cta

質問別の使用エンドポイント

ユーザーの質問	呼び出し	理由
「サイトの調子はどうですか？」	insights + breakdown + pages（並列）	週全体の状況を把握できます
「今、訪問者はいますか？」	live	すべてのプロジェクトのリアルタイム訪問者を確認できます
「人気のページはどれですか？」	breakdown --property path --event page_view	ページをランキング形式で表示します
「トラフィックの流入元はどこですか？」	breakdown --property referrer --event page_view	リファラーの流入元を確認できます
「ユーザーは実際にエンゲージしていますか？」	sessions-dist	直帰とエンゲージメントの内訳を確認できます
「デプロイに適した時間はいつですか？」	heatmap	トラフィックの少ない時間帯を見つけます
「ユーザーはどこで離脱していますか？」	funnel --steps "page_view,signup,purchase"	ステップごとのコンバージョンを確認できます
「ユーザーは再訪していますか？」	retention --period week --cohorts 8	コホートのリテンションを確認できます
「どちらの CTA のコンバージョン率が高いですか？」	experiments create + experiments get	A/B テストのライフサイクルを管理できます

「X の調子はどうですか？」という質問には、必ず最初に insights を呼び出してください。これが最も役立つ単一のエンドポイントです。

例

window.aa?.track() でカスタムイベントを追跡します：

window.aa?.track('cta_click', {id: 'hero_get_started'});
window.aa?.track('signup', {method: 'github'});
window.aa?.track('feature_used', {feature: 'create_project'});
window.aa?.track('checkout', {plan: 'pro'});

このスキルでできないこと

• GUI ダッシュボードはありません。エージェントがダッシュボードです（リアルタイムの TUI には live を使用してください）
• ユーザー管理や請求には対応していません
• PII は保存されません。IP アドレスは記録も保持もされません。プライバシーを最優先に設計されています