api-analytics-setup-posthog

PostHog アナリティクスとフィーチャーフラグのセットアップ

クイックガイド： PostHog のアナリティクスとフィーチャーフラグを一度だけセットアップします。posthog-js クライアントプロバイダー、posthog-node サーバークライアント、環境変数について説明します。PostHog はアナリティクスとフィーチャーフラグの両方に対応し、充実した無料プラン（月間 100 万イベント＋100 万回のフラグリクエスト）を提供しています。

---

<critical_requirements>

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

すべてのコードは、CLAUDE.md に記載されたプロジェクトの規約（ケバブケース、名前付きエクスポート、インポート順序、import type、名前付き定数）に従う必要があります。

（posthog-js は window や localStorage などのブラウザー API を必要とするため、クライアント／ブラウザーのコンテキストでのみ初期化する必要があります）

（サーバー側でイベントをキャプチャした後は、イベントの損失を防ぐため、posthog.shutdown()、posthog.flush() を呼び出すか、captureImmediate() を使用する必要があります）

（自動 SPA ページトラッキングと最新の推奨動作のために、defaults: '2026-01-30' を使用する必要があります）

</critical_requirements>

---

自動検出： PostHog のセットアップ、posthog-js、posthog-node、PostHogProvider、アナリティクスのセットアップ、フィーチャーフラグのセットアップ、イベントトラッキングのセットアップ、posthog.init

使用する場面：

• プロジェクトで PostHog を初めてセットアップするとき
• クライアント側のアナリティクス用に PostHogProvider を設定するとき
• サーバー側／API ルートでのイベントキャプチャ用に posthog-node をセットアップするとき
• PostHog の環境変数を設定するとき

使用しない場面：

• セットアップ後のイベントトラッキングのパターン（アナリティクスのイベントトラッキングスキルを使用）
• フィーチャーフラグの使用パターン（フィーチャーフラグのスキルを使用）
• ステージング用と本番用で別々のプロジェクトを使用する複雑なマルチ環境セットアップ

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

• PostHogProvider またはフレームワークの初期化フックを使用したクライアント側のセットアップ
• posthog-node を使用したサーバー側のセットアップ
• 環境変数（クライアント側とサーバー側のプレフィックス）
• ユーザーの識別とリセットのフロー
• サーバーレス環境でのフラッシュパターン（captureImmediate と flush）

詳細リソース：

• examples/core.md - プロバイダーのセットアップ、レイアウトへの組み込み、ユーザーの識別、環境変数
• examples/server.md - サーバークライアントのシングルトン、API ルート、サーバーレスのパターン
• reference.md - 選択の指針

---

基本理念

PostHog は、複数のツールをひとつにまとめた プロダクトアナリティクス＋フィーチャーフラグのプラットフォーム です。オープンソースで、セルフホストも可能なうえ、充実した無料プランを提供しています。個人開発者や小規模チームにとって、PostHog を使えば、アナリティクスとフィーチャーフラグのサービスを別々に用意する必要がなくなります。

基本原則：

1. アナリティクスとフィーチャーフラグをひとつのプラットフォームで提供 - ツールの乱立とコストを削減します
2. 利用量に基づく料金体系 - プロジェクトごとではなく、利用した分だけ支払います
3. デフォルトで自動キャプチャ - イベントを自動トラッキングし、手動での計測設定を減らします
4. サーバー用とクライアント用の SDK - SSR とクライアント側アプリを幅広くカバーします

PostHog を使用する場面：

• アナリティクスとフィーチャーフラグの両方をひとつのプラットフォームで利用したい場合
• 充実した無料プラン（月間 100 万イベント＋100 万回のフラグリクエスト）を利用したい場合
• オープンソースを好み、セルフホストの選択肢も必要な場合
• プロダクトアナリティクス（ファネル、継続率、セッション）を構築する場合

PostHog を使用しない場面：

• 統計的な厳密性を備えた高度な A/B テストが必要な場合
• リアルタイムのイベントストリーミングが必要な場合
• すでに確立されたアナリティクスとフラグのツールがある場合

---

基本パターン

パターン 1：PostHog のプロジェクト構成

アプリにはひとつの PostHog 組織を使用します。ひとつの組織にまとめることで、課金も一元化できます。アプリごとにプロジェクトを分けるか、ひとつのプロジェクトでカスタムプロパティを使ってフィルタリングします。

PostHog Organization: "Your Company"
├── Project: "Main App" (or separate per app)
│   ├── API Key: phc_xxx
│   └── Host: https://us.i.posthog.com (or eu.i.posthog.com)

推奨理由： ひとつの組織にまとめることで、すべてのプロジェクトの課金が一元化されます。利用量に基づく料金体系で、有料プランには 6 つのプロジェクトが含まれます。

---

パターン 2：クライアントサイドのセットアップ

posthog-js をインストールし、プロバイダーを設定するか、フレームワークのクライアントサイド初期化フックを使用します。

主な設定オプション：defaults: "2026-01-30" を指定すると推奨される動作が有効になり、person_profiles: "identified_only" を指定するとコストを削減できます。

両方の方法の完全な実装については、examples/core.md を参照してください。

推奨される理由： defaults の日付指定により SPA のページ表示／離脱を自動でトラッキングでき、person_profiles: "identified_only" によりイベントのコストを削減できます。また、開発時のデバッグモードはトラブルシューティングに役立ちます。

---

パターン 3：posthog-node によるサーバーサイドのセットアップ

posthog-node をインストールし、サーバーサイドでイベントをキャプチャするためのシングルトンを作成します。

サーバーレス環境でのフラッシュ方法：

• captureImmediate() - 最もシンプルな方法です。HTTP リクエストを直接待機します（イベントごとに 1 リクエスト）。
• capture() + await flush() - バッチ処理されます。レスポンスを返す前に明示的なフラッシュが必要です。

シングルトンのセットアップ、API ルートでの使用方法、フラッシュに関するアンチパターンについては、examples/server.md を参照してください。

推奨される理由： シングルトンにより複数のクライアントインスタンスの生成を防ぎ、flushInterval/flushAt でバッチ処理を設定できます。また、captureImmediate によりサーバーレス環境での使用が簡単になります。

---

<red_flags>

要注意事項

• posthog-js をサーバー上で初期化している（ブラウザー API が必要なため、クラッシュします）
• サーバーレス環境でサーバーサイドのイベントをキャプチャした後に flush() または captureImmediate() を呼び出していない（イベントが通知されずに失われます）
• クライアントサイドの環境変数がブラウザーバンドルに公開されていない（フレームワークのプレフィックス規則を確認してください）
• 環境変数ではなく、ソースコードに API キーをハードコードしている
• サインアウト時に posthog.reset() を呼び出していない（ユーザーの識別情報が次のセッションに引き継がれます）
• defaults の日付オプションを使用していない（手動でページビューをトラッキングする必要があり、推奨される動作も適用されません）
• 認証後に posthog.identify() を呼び出していない（匿名セッションと認証済みセッションが紐付けられません）
• person_profiles: 'identified_only' オプションを指定していない（不要な匿名プロファイルが作成され、コストが増加します）
• フックを使用しているのに、アプリを PostHogProvider でラップしていない（フックが null を返します）
• デプロイ先のプラットフォームに環境変数を追加し忘れている（イベントが通知されずに失敗します）
• 気づかないうちに開発環境と本番環境で異なる PostHog プロジェクトを使用している（データが分かれます）

注意点とエッジケース：

• posthog-js は window が使用可能になった後に初期化する必要があります（そのため、useEffect またはクライアントサイド初期化フックを使用します）
• サーバーサイド SDK はクライアントのように自動でフラッシュされません。明示的に flush() または shutdown() を呼び出すか、captureImmediate() を使用する必要があります
• サーバーレス環境では captureImmediate() のほうが簡単ですが、イベントごとに 1 件の HTTP リクエストを送信します（バッチ処理はされません）
• 無料プランの利用枠は毎月リセットされます（イベント数が 100 万件に達すると、翌月までキャプチャが停止します）
• person_profiles: 'identified_only' はコストを削減できますが、匿名ユーザープロファイルは作成されません
• 自動初期化フックを使用する場合、設定値はセッション中固定されます。ブートストラップが機能するのは、レンダリング前にサーバー上でフラグが評価される場合のみです

</red_flags>

---

<critical_reminders>

重要な注意事項

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

（posthog-js は、window や localStorage などのブラウザー API を必要とするため、クライアント／ブラウザーのコンテキストでのみ初期化する必要があります）

（イベントの損失を防ぐため、サーバーサイドでイベントをキャプチャした後は、posthog.shutdown() または posthog.flush() を呼び出すか、captureImmediate() を使用する必要があります）

（SPA のページを自動でトラッキングし、最新の推奨動作を適用するために、defaults: '2026-01-30' を使用する必要があります）

これらのルールに従わないと、分析イベントの損失、トラッキングの不具合、またはセキュリティ上の脆弱性が発生します。

</critical_reminders>

---

ソース

• PostHog JavaScript SDK
• PostHog JavaScript Configuration
• PostHog Node.js SDK