integration-flask

Flask 向け PostHog インテグレーション

このスキルは、Flask アプリケーションに PostHog アナリティクスを追加するためのものです。

ワークフロー

インテグレーションを完了するには、次の手順を順番に実行してください。

1. basic-integration-1.0-begin.md - PostHog のセットアップ - 開始 ← ここから始めてください
2. basic-integration-1.1-edit.md - PostHog のセットアップ - 編集
3. basic-integration-1.2-revise.md - PostHog のセットアップ - 修正
4. basic-integration-1.3-conclude.md - PostHog のセットアップ - 完了

参照ファイル

• references/EXAMPLE.md - Flask のサンプルプロジェクトコード
• references/flask.md - Flask - ドキュメント
• references/identify-users.md - ユーザーの識別 - ドキュメント
• references/basic-integration-1.0-begin.md - PostHog のセットアップ - 開始
• references/basic-integration-1.1-edit.md - PostHog のセットアップ - 編集
• references/basic-integration-1.2-revise.md - PostHog のセットアップ - 修正
• references/basic-integration-1.3-conclude.md - PostHog のセットアップ - 完了

サンプルプロジェクトは、目標とする実装パターンを示しています。API の詳細についてはドキュメントを参照してください。

重要な原則

• 環境変数：PostHog のキーには必ず環境変数を使用してください。ハードコードしないでください。
• 最小限の変更：既存のインテグレーションに PostHog のコードを追加してください。既存のコードを置き換えたり、構成を変更したりしないでください。
• サンプルに合わせる：実装は、できる限りサンプルプロジェクトのパターンに従ってください。

フレームワークのガイドライン

• posthog.api_key と posthog.host を使用して、create_app() 内で PostHog をグローバルに初期化してください（リクエストごとには初期化しないでください）。
• Flask には組み込みのエラーハンドラーがあるため、エラートラッキングには posthog.capture_exception(e) を使って例外を手動で記録してください。
• create_app() では、PostHog の初期化後に Blueprint を登録してください。
• ソースコードは venv/site-packages ディレクトリにあることを忘れないでください。
• posthog は Python SDK のパッケージ名です。
• pip install posthog または pip install -r requirements.txt で依存関係をインストールしてください。シェルコマンドで、引用符なしのバージョン指定子（>= など）を直接使用しないでください。
• CLI やスクリプトでは、終了前に必ず posthog.shutdown() を呼び出してください。呼び出さないと、すべてのイベントが失われます。
• モジュールレベルの posthog.api_key 設定ではなく、必ず Posthog() クラスコンストラクター（インスタンスベースの API）を使用してください。
• 例外を自動的にトラッキングするため、必ず Posthog() コンストラクターに enable_exception_autocapture=True を含めてください。
• capture() イベントプロパティには、PII を絶対に送信しないでください。メールアドレス、氏名、電話番号、住所、IP アドレス、ユーザー生成コンテンツは含めないでください。
• PII は capture() イベントプロパティではなく、identify() の人物プロパティに含めてください。安全なイベントプロパティは、message_length、form_type、真偽値フラグなどのメタデータです。
• 終了時にすべてのイベントがフラッシュされるよう、posthog_client.shutdown を atexit.register() に登録してください。
• Python SDK には identify() メソッドがありません。人物プロパティの設定には posthog_client.set(distinct_id=user_id, properties={...}) を使うか、コンテキスト内で identify_context(user_id) を使用してください。

ユーザーの識別

ログインイベントとサインアップイベントでユーザーを識別してください。このフレームワークで正しい識別パターンを確認するには、サンプルコードとドキュメントを参照してください。フロントエンドコードとバックエンドコードの両方がある場合は、相関関係を維持するため、X-POSTHOG-DISTINCT-ID ヘッダーと X-POSTHOG-SESSION-ID ヘッダーを使ってクライアント側のセッションと distinct ID を渡してください。

エラートラッキング

関連ファイル、特に重要なユーザーフローや API の境界で、PostHog のエラートラッキングを追加してください。