instrument-integration

PostHog SDK 統合の追加

このスキルを使って、アプリケーションに PostHog SDK を追加します。PostHog を初めて設定するときや、PostHog の初期化が必要な PR をレビューするときに使用してください。SDK のインストール、プロバイダーの設定、基本的な構成を扱います。あらゆるフレームワークや言語に対応しています。

対応するフレームワークと言語：Next.js、React、React Router、Vue、Nuxt、TanStack Start、SvelteKit、Astro、Angular、Django、Flask、FastAPI、Laravel、PHP、Ruby on Rails、Go、Elixir、Android、iOS、Swift、Flutter、React Native、Expo、Node.js、vanilla JavaScript。

手順

以下の手順を順番どおりに実行してください。

STEP 1: コードベースを分析し、プラットフォームを特定します。

依存関係ファイル（package.json、pubspec.yaml、Podfile、Package.swift、requirements.txt、Gemfile、composer.json、go.mod、mix.exs など）を確認し、フレームワークと言語を特定します。

ロックファイル（pnpm-lock.yaml、package-lock.json、yarn.lock、bun.lockb、go.sum、pubspec.lock、Podfile.lock、Package.resolved、mix.lock）を確認し、パッケージマネージャーを特定します。

• 既存の PostHog 設定を確認します。PostHog がすでにインストールされ、初期化されている場合は、コードを変更しないでください。その旨をユーザーに伝え、検証に進みます。

STEP 2: 統合方法を調査します。 2.1. 特定したフレームワークに一致する以下のリファレンスファイルを探してください。このファイルは、SDK の初期化、プロバイダーの設定、構成パターンの信頼できる情報源です。今すぐ読み込んでください。 2.2. 一致するリファレンスがない場合は、一般知識とウェブ検索を使ってください。主な検索先として posthog.com/docs を使用してください。

STEP 3: PostHog SDK をインストールします。

• 特定したプラットフォーム用の PostHog SDK パッケージを追加します。package.json を手動で編集せず、パッケージマネージャーのインストールコマンドを使用してください。

STEP 4: PostHog を初期化します。

• 初期化する場所と方法は、フレームワークのリファレンスに従ってください。フレームワークによって大きく異なります（例：Next.js 15.3 以降では instrumentation-client.ts、Django では AppConfig.ready()、Flask では create_app()）。
• フレームワークで必要な場合は、PostHog のプロバイダー／ラッパーコンポーネントを設定します。

STEP 5: ユーザーを識別します。

• ログインおよびサインアップのイベント時に、クライアント側で PostHog identify() を呼び出します。
• フロントエンドとバックエンドの両方がある場合は、クライアント側のセッションと distinct ID を X-POSTHOG-DISTINCT-ID および X-POSTHOG-SESSION-ID ヘッダーを使ってサーバー側のコードに渡します。

STEP 6: 環境変数を設定します。

• プロジェクトに PostHog の環境変数がすでに設定されているか確認します（例：.env、.env.local、またはフレームワーク固有の環境ファイル）。有効な値がすでにある場合は、この手順をスキップします。
• PostHog プロジェクトトークンがない場合は、PostHog MCP サーバーの projects-get ツールを使って、プロジェクトの api_token を取得します。複数のプロジェクトが返された場合は、どのプロジェクトを使うかユーザーに尋ねます。MCP サーバーに接続されていない、または認証されていない場合は、代わりに PostHog プロジェクトトークンをユーザーに尋ねます。
• PostHog ホスト URL については、projects-get の MCP レスポンスに region フィールドがあるか確認します。US は https://us.i.posthog.com、EU は https://eu.i.posthog.com に対応します。MCP レスポンスにも既存のプロジェクト設定にもリージョンがない場合は、ユーザーに「PostHog の US Cloud と EU Cloud のどちらを利用していますか？」と尋ねます。US Cloud と決めつけないでください。
• これらの値を、適切な環境ファイル（例：Next.js では .env.local、その他では .env）に、フレームワークの命名規則に従って書き込みます。
• 値をハードコードせず、コード内でこれらの環境変数を参照します。

STEP 7: 検証し、クリーンアップします。

• プロジェクトにエラーがないか確認します。package.json に型チェックやビルドのスクリプトがあるか確認してください。
• 作成したコンポーネントが実際に使用されていることを確認します。
• package.json にあるリンターや Prettier に類するスクリプトを実行します。ただし、今回のセッションで編集または作成したファイルに限ります。プロジェクト全体に対してフォーマットやリンティングを実行してはいけません。

リファレンスファイル

• references/EXAMPLE-next-app-router.md - next-app-router のサンプルプロジェクトコード
• references/EXAMPLE-next-pages-router.md - next-pages-router のサンプルプロジェクトコード
• references/EXAMPLE-react-react-router-6.md - react-react-router-6 のサンプルプロジェクトコード
• references/EXAMPLE-react-react-router-7-framework.md - react-react-router-7-framework のサンプルプロジェクトコード
• references/EXAMPLE-react-react-router-7-data.md - react-react-router-7-data のサンプルプロジェクトコード
• references/EXAMPLE-react-react-router-7-declarative.md - react-react-router-7-declarative のサンプルプロジェクトコード
• references/EXAMPLE-react-vite.md - react-vite のサンプルプロジェクトコード
• references/EXAMPLE-nuxt-3-6.md - nuxt-3-6 のサンプルプロジェクトコード
• references/EXAMPLE-nuxt-4.md - nuxt-4 のサンプルプロジェクトコード
• references/EXAMPLE-vue-3.md - vue-3 のサンプルプロジェクトコード
• references/EXAMPLE-react-tanstack-router-file-based.md - react-tanstack-router-file-based のサンプルプロジェクトコード
• references/EXAMPLE-react-tanstack-router-code-based.md - react-tanstack-router-code-based のサンプルプロジェクトコード
• references/EXAMPLE-tanstack-start.md - tanstack-start のサンプルプロジェクトコード
• references/EXAMPLE-sveltekit.md - sveltekit のサンプルプロジェクトコード
• references/EXAMPLE-astro-static.md - astro-static のサンプルプロジェクトコード
• references/EXAMPLE-astro-view-transitions.md - astro-view-transitions のサンプルプロジェクトコード
• references/EXAMPLE-astro-ssr.md - astro-ssr のサンプルプロジェクトコード
• references/EXAMPLE-astro-hybrid.md - astro-hybrid のサンプルプロジェクトコード
• references/EXAMPLE-angular.md - angular のサンプルプロジェクトコード
• references/EXAMPLE-javascript-node.md - javascript-node のサンプルプロジェクトコード
• references/EXAMPLE-javascript-web.md - javascript-web のサンプルプロジェクトコード
• references/EXAMPLE-django.md - django のサンプルプロジェクトコード
• references/EXAMPLE-flask.md - flask のサンプルプロジェクトコード
• references/EXAMPLE-fastapi.md - fastapi のサンプルプロジェクトコード
• references/EXAMPLE-python.md - python のサンプルプロジェクトコード
• references/EXAMPLE-laravel.md - laravel のサンプルプロジェクトコード
• references/EXAMPLE-php.md - php のサンプルプロジェクトコード
• references/EXAMPLE-ruby-on-rails.md - ruby-on-rails のサンプルプロジェクトコード
• references/EXAMPLE-ruby.md - ruby のサンプルプロジェクトコード
• references/EXAMPLE-android.md - android のサンプルプロジェクトコード
• references/EXAMPLE-swift.md - swift のサンプルプロジェクトコード
• references/EXAMPLE-react-native.md - react-native のサンプルプロジェクトコード
• references/EXAMPLE-expo.md - expo のサンプルプロジェクトコード
• references/next-js.md - Next.js
• references/react.md - React
• references/react-router-v6.md - React router v6
• references/react-router-v7-framework-mode.md - React router v7 framework mode（remix v3）
• references/react-router-v7-data-mode.md - React router v7 data mode
• references/react-router-v7-declarative-mode.md - React router v7 declarative mode
• references/nuxt-js-3-6.md - Nuxt.js（v3.0 から v3.6）
• references/nuxt-js.md - Nuxt.js
• references/vue-js.md - Vue.js
• references/tanstack-start.md - Tanstack start
• references/svelte.md - Svelte
• references/astro.md - Astro
• references/angular.md - Angular
• references/js.md - JavaScript web
• references/posthog-js.md - PostHog JavaScript web SDK
• references/node.md - Node.js
• references/posthog-node.md - PostHog Node.js SDK
• references/django.md - Django
• references/flask.md - Flask
• references/python.md - Python
• references/posthog-python.md - PostHog python SDK
• references/dotnet.md - .net
• references/elixir.md - Elixir
• references/go.md - Go
• references/laravel.md - Laravel
• references/php.md - Php
• references/ruby-on-rails.md - Ruby on rails
• references/ruby.md - Ruby
• references/android.md - Android
• references/ios.md - Ios
• references/usage.md - Ios SDK の使用方法
• references/configuration.md - Ios SDK の設定
• references/flutter.md - Flutter
• references/react-native.md - React native
• references/identify-users.md - ユーザーの識別
• references/COMMANDMENTS.md - 統合が従う必要のあるフレームワーク固有のルール 各フレームワークのリファレンスには、SDK 固有のインストール、初期化、使用方法が記載されています。ユーザーのスタックに合ったものを選んでください。

主な原則

• 環境変数：PostHog のキーには必ず環境変数を使用してください。ハードコードしないでください。
• 変更は最小限に：既存の連携に PostHog のコードを追加してください。既存のコードを置き換えたり、再構成したりしないでください。
• サンプルに合わせる：実装は、できるだけサンプルプロジェクトのパターンに沿ってください。
• アナリティクスの契約：イベント名、プロパティ名、フィーチャーフラグのキーは、アナリティクスの契約の一部として扱ってください。プロジェクト内に既存の名前やパターンがあれば再利用してください。新たに導入する場合は、明確で説明的な名前にし、既存の規則と一貫性を持たせてください。