integration-ruby-on-rails

Ruby on Rails 向け PostHog 統合

このスキルでは、Ruby on Rails アプリケーションに 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 - Ruby on Rails のサンプルプロジェクトコード
• references/ruby-on-rails.md - Ruby on Rails - ドキュメント
• references/ruby.md - Ruby - ドキュメント
• 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 のコードを追加してください。既存のコードを置き換えたり、構成し直したりしないでください。
• サンプルに合わせる：実装では、できる限りサンプルプロジェクトのパターンに従ってください。

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

• 例外の自動取得と ActiveJob の計測には、posthog-ruby と併せて posthog-rails gem を使用してください
• rails generate posthog:install を実行してイニシャライザーを作成するか、config/initializers/posthog.rb を手動で作成してください
• auto_capture_exceptions: true を設定して、コントローラー内の未処理例外を自動的に追跡してください
• report_rescued_exceptions: true を設定して、Rails が救済する例外（例：rescue_from を使用した場合）も取得してください
• auto_instrument_active_job: true を設定して、ジョブクラス、キュー、引数とともにバックグラウンドジョブの失敗を追跡してください
• PostHog.capture() と PostHog.identify() のクラスメソッドを使用してください（インスタンスメソッドではありません）。posthog-rails gem は PostHog.init を通じてクライアントのライフサイクルを管理します
• Rails では PostHog::Client インスタンスを手動で作成しないでください。イニシャライザーでは PostHog.init を使用し、それ以外の箇所では PostHog.capture/identify を使用してください
• capture_exception は位置引数を取ります：PostHog.capture_exception(exception, distinct_id, additional_properties)。キーワード引数は使用しないでください
• エラーレポートでユーザーを自動的に関連付けるには、User モデルに posthog_distinct_id を定義してください。posthog-rails は次の順に試して自動検出します：posthog_distinct_id、distinct_id、id、pk、uuid
• ActiveJob でユーザーを関連付けるには、クラスレベルの DSL posthog_distinct_id ->(user) { user.email } を使用するか、ハッシュ引数に user_id: を渡してください
• API キーは Rails credentials または環境変数に保存し、ハードコードしないでください
• posthog-rails と併せてフロントエンドのトラッキングを行う場合は、レイアウトテンプレートに posthog-js のスニペットを追加してください。posthog-js はページビュー、セッションリプレイ、クライアント側のエラーを処理し、posthog-ruby はバックエンドのイベント、サーバーエラー、フィーチャーフラグ、バックグラウンドジョブを処理します
• posthog-ruby は Ruby SDK の gem 名です（Gemfile に gem 'posthog-ruby' を追加します）が、require には require 'posthog' を使用してください（require 'posthog-ruby' ではありません）
• スクリプトや CLI でインスタンスベースの初期化を行うには、PostHog::Client.new(api_key: key, host: host) を使用してください
• CLI とスクリプトでは、終了前に client.shutdown を必ず呼び出してください。呼び出さないと、すべてのイベントが失われます
• 適切にクリーンアップするには、ensure ブロック内で shutdown を実行する begin/rescue/ensure を使用してください
• capture と identify は単一のハッシュ引数を取ります：client.capture(distinct_id: 'user_123', event: 'my_event', properties: { key: 'value' })
• capture_exception は位置引数（キーワード引数ではありません）を取ります：client.capture_exception(exception, distinct_id, additional_properties)。distinct_id: のキーワード構文は使用しないでください

ユーザーの識別

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

エラートラッキング

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