api-analytics-posthog-analytics

PostHog アナリティクスのパターン

クイックガイド： PostHog を使用してプロダクトアナリティクスを実施します。イベントには構造化された命名規則（category:object_action）を使用し、信頼性を高めるためにサーバーサイドでトラッキングし、認証フローと連携して適切にユーザーを識別します。UI の操作にはクライアントサイド、ビジネスイベントにはサーバーサイドを使用します。ログアウト時には必ず reset() を呼び出し、イベントプロパティに PII を保存しないでください。サーバーレス環境では captureImmediate() または await shutdown() を使用します。

詳細なリソース：

• examples/core.md - イベントの命名、ユーザー識別、プロパティの規則
• examples/client-tracking.md - React フック、プロバイダーのセットアップ、コンポーネントのトラッキング
• examples/server-tracking.md - posthog-node、サーバーレスのパターン、認証イベント
• examples/group-analytics.md - B2B 組織のトラッキング
• examples/privacy-gdpr.md - GDPR の同意、Cookie を使用しないモード、PII のフィルタリング
• reference.md - 判断の枠組み、アンチパターン、イベントの分類体系

---

<critical_requirements>

重要：このスキルを使用する前に

すべてのコードは CLAUDE.md のプロジェクト規約に従う必要があります（kebab-case、名前付きエクスポート、インポート順序、import type、名前付き定数）

（posthog.identify() を呼び出すのは、ユーザーがサインアップまたはログインした場合に限ってください。ページ読み込みごとには呼び出さないでください）

（すべてのサーバーサイドイベントで、ユーザーのデータベース ID を distinct_id として指定する必要があります）

（ユーザーがログアウトしたときは posthog.reset() を呼び出し、以降のイベントとの関連付けを解除する必要があります）

（すべてのカスタムイベントに category:object_action の命名規則を使用する必要があります）

（イベントプロパティに PII（メールアドレス、名前、電話番号）を絶対に含めないでください。ユーザー ID のみを使用してください）

</critical_requirements>

---

自動検出： PostHog、posthog-js、posthog-node、usePostHog、PostHogProvider、capture、identify、グループアナリティクス、プロダクトアナリティクス、イベントトラッキング、ファネル分析

使用する場面：

• ユーザーの行動とプロダクトアナリティクスをトラッキングする
• コンバージョンファネルとリテンション分析を設定する
• B2B マルチテナントアプリにグループアナリティクスを実装する
• 機能の利用状況とユーザージャーニーを把握する
• A/B テストを分析する（フィーチャーフラグと併用）

使用しない場面：

• フィーチャーフラグの実装（別の用途です）
• エラーのトラッキングとログ記録（専用のエラートラッキングツールを使用してください）
• インフラストラクチャの監視（オブザーバビリティツールを使用してください）

対象となる主なパターン：

• イベントの命名規則（category:object_action）
• プロパティの命名パターン（object_adjective、is_／has_ の真偽値）
• 認証フローとの連携によるユーザー識別
• React フックを使ったクライアントサイドのトラッキング
• posthog-node を使ったサーバーサイドのトラッキング
• B2B 組織向けのグループアナリティクス
• プライバシーと GDPR 同意のパターン
• 型安全なイベントのための TypeScript パターン

---

基本方針

PostHog のアナリティクスでは、構造化された分類体系を採用します。一貫した命名規則、意味のあるプロパティ、適切な配置（クライアントサイドかサーバーサイドか）が重要です。すべてをトラッキングするのではなく、プロダクトに関する意思決定に役立つ情報をトラッキングします。

主な原則：

1. ビジネスイベントにはサーバーサイドを使用する - ユーザー登録、購入、サブスクリプション（信頼性が高く、ブロックされない）
2. UI の操作にはクライアントサイドを使用する - ボタンのクリック、ページビュー、フォームの操作
3. セッションごとに一度だけ識別する - ページ読み込みごとには識別しない
4. 構造化された命名を使用する - 大規模な環境でもクエリと分析が可能になります

---

基本パターン

パターン 1：イベント命名規則

一貫性があり、クエリ可能なイベント名にするため、category:object_action のフレームワークを使用します。

// category: Context (signup_flow, settings, dashboard)
// object: Component/location (password_button, pricing_page)
// action: Present-tense verb (click, submit, view)

"signup_flow:email_form_submit";
"dashboard:project_create";
"settings:billing_plan_upgrade";

// Simpler alternative: object_verb
"project_created";
"user_signed_up";

優れている理由： カテゴリーのプレフィックスによって PostHog UI で関連イベントがグループ化され、signup_flow:* のようなワイルドカードクエリが可能になります。また、一貫した命名によって大規模な分析が可能になります。

プロパティの命名規則：

• object_adjective：project_id、plan_name、item_count
• ブール値には is_ / has_：is_first_purchase、has_completed_onboarding
• _date / _timestamp のサフィックス：trial_end_date、last_login_timestamp

命名例の全容については、examples/core.md を参照してください。

---

パターン 2：認証を使ったユーザー識別

identify() は認証状態が変化したときにのみ呼び出します（レンダリングごとには呼び出しません）。データベースのユーザー ID を distinct_id として使用します。ログアウト時に reset() を呼び出します。

// Check _isIdentified() to prevent duplicate calls
useEffect(() => {
  if (session?.user && !posthog._isIdentified()) {
    posthog.identify(session.user.id, {
      plan: session.user.plan ?? "free",
      created_at: session.user.createdAt,
      is_verified: session.user.emailVerified ?? false,
    });
  }
}, [session?.user]);

// Always reset on logout
posthog?.capture("user_logged_out");
posthog?.reset(); // Unlink future events from this user

識別フックとログアウトハンドラーの全容については、examples/core.md を参照してください。

---

パターン 3：サーバーサイドトラッキング

posthog-node を使って、バックエンドからビジネスイベントを確実にトラッキングします。

// Serverless: use captureImmediate (guarantees HTTP completion)
await posthogServer.captureImmediate({
  distinctId: user.id,
  event: "subscription_created",
  properties: { plan: "pro", is_annual: true },
});

// Always call shutdown before returning in serverless
await posthogServer.shutdown();

主なルール：

1. 常に distinctId（ユーザーのデータベース ID）を含めます
2. サーバーレスでは captureImmediate() を使用します（HTTP 処理の完了を保証します）
3. サーバーレスでは、返却する前に必ず shutdown() を呼び出します
4. サーバーレスでは flushAt: 1 と flushInterval: 0 を設定します

サーバーのセットアップとルートの例の全容については、examples/server-tracking.md を参照してください。

---

パターン 4：グループ分析（B2B）

PostHog のグループ機能を使ってイベントを組織に関連付け、B2B メトリクスを計測します。

// Client-side: identify organization
posthog.group("company", org.id, {
  name: org.name,
  plan: org.plan ?? "free",
  member_count: org.memberCount,
});

// Server-side: include groups in event
posthogServer.capture({
  distinctId: user.id,
  event: "organization:member_invited",
  properties: { role: data.role },
  groups: { company: data.organizationId },
});

制限事項： プロジェクトごとに最大 5 種類のグループを設定できます。イベントごとに各種類のグループを 1 つ指定できます。

グループのパターンの全容については、examples/group-analytics.md を参照してください。

---

パターン 5：プライバシーと GDPR の同意

PostHog は Cookie を使用しないトラッキングと同意管理をサポートしています。

// Cookieless mode: "always" (no consent needed) or "on_reject" (with banner)
posthog.init(POSTHOG_KEY, {
  cookieless_mode: "on_reject",
  person_profiles: "identified_only",
});

// Consent methods
posthog.opt_in_capturing(); // User accepts
posthog.opt_out_capturing(); // User rejects

主なルール： イベントプロパティに個人を特定できる情報（メールアドレス、氏名、電話番号、IP アドレス、住所）を保存しないでください。仮名化された ID のみを使用します。

同意バナーとの連携と before_send によるフィルタリングについては、examples/privacy-gdpr.md を参照してください。

---

パフォーマンスの最適化

ウェブアプリ（デフォルトのバッチ処理）： デフォルト設定を使用します。PostHog は最初から効率的にイベントをバッチ処理します。

サーバーレス（即時配信）：

const posthogServer = new PostHog(POSTHOG_KEY, {
  flushAt: 1, // Flush after 1 event
  flushInterval: 0, // No interval batching
});
// Use captureImmediate() or capture() + await shutdown()

コストの削減：

posthog.init(POSTHOG_KEY, {
  person_profiles: "identified_only", // Anonymous events 4x cheaper
  autocapture: false, // Disable for high-traffic sites
});

---

<red_flags>

要注意事項

優先度の高い問題：

• distinct_id にメールアドレスを使用している — 個人を特定できる情報を識別子にしないでください
• ログアウト時に posthog.reset() を呼び出していない — ユーザーのデータが混在します
• サーバーレスで await shutdown() を呼び出していない — イベントが失われます
• イベントプロパティに個人を特定できる情報が含まれている — GDPR 違反のリスクがあります
• レンダリングごとに identify() を呼び出している — パフォーマンスが低下します

よくある間違い：

• React で usePostHog フックを使わず、posthog を直接インポートしている
• リバースプロキシ（api_host: "/ingest"）を設定していない — 広告ブロッカーによってイベントがブロックされます
• フロントエンドとバックエンドで同じアクションに異なるイベント名を使用している
• person_profiles: "identified_only" を使用していない — 匿名イベントのコストが 4 倍になります
• サーバーレスで captureImmediate() ではなく capture() を使用している — イベント処理が完了しない可能性があります

注意点とエッジケース：

• distinct_id はすべてのサーバーサイドイベントで必須です（自動生成されるクライアントサイドとは異なります）
• group() ではイベントごとにグループ ID を指定する必要があります（identify() のように保持されません）
• プロジェクトごとに最大 5 種類のグループを設定できます
• cookieless_mode: "always" を設定すると identify() が完全に無効になります — プライバシーとのトレードオフです
• PostHog のウェブ SDK はクライアントサイド専用であり、サーバーコンポーネントでは動作しません
• セッションを関連付けるには、サーバーサイドイベントにセッション ID を手動で渡す必要があります

</red_flags>

---

<critical_reminders>

重要な注意事項

すべてのコードは CLAUDE.md のプロジェクト規約（kebab-case、名前付きエクスポート、インポート順序、import type、名前付き定数）に従う必要があります

（ユーザーがサインアップまたはログインしたときにのみ posthog.identify() を呼び出してください。ページが読み込まれるたびに呼び出してはいけません）

（すべてのサーバーサイドイベントで、ユーザーのデータベース ID を distinct_id として含める必要があります）

（ユーザーがログアウトしたときは、今後のイベントとの関連付けを解除するために posthog.reset() を呼び出す必要があります）

（すべてのカスタムイベントで category:object_action の命名規則を使用する必要があります）

（イベントプロパティに個人識別情報（メールアドレス、名前、電話番号）を含めてはいけません。ユーザー ID のみを使用してください）

これらのルールに従わないと、分析データの品質問題、プライバシー侵害、またはイベントの消失につながります。