Intégration PostHog pour Ruby on Rails

Cette skill vous aide à ajouter PostHog analytics à vos applications Ruby on Rails.

Workflow

Suivez ces étapes dans l'ordre pour compléter l'intégration :

1. basic-integration-1.0-begin.md - PostHog Setup - Begin ← Commencez ici
2. basic-integration-1.1-edit.md - PostHog Setup - Edit
3. basic-integration-1.2-revise.md - PostHog Setup - Revise
4. basic-integration-1.3-conclude.md - PostHog Setup - Conclusion

Fichiers de référence

• references/EXAMPLE.md - Exemple de code de projet Ruby on Rails
• references/ruby-on-rails.md - Ruby on rails - docs
• references/ruby.md - Ruby - docs
• references/identify-users.md - Identify users - docs
• references/basic-integration-1.0-begin.md - PostHog setup - begin
• references/basic-integration-1.1-edit.md - PostHog setup - edit
• references/basic-integration-1.2-revise.md - PostHog setup - revise
• references/basic-integration-1.3-conclude.md - PostHog setup - conclusion

Le projet exemple montre le pattern d'implémentation cible. Consultez la documentation pour les détails de l'API.

Principes clés

• Variables d'environnement : Utilisez toujours des variables d'environnement pour les clés PostHog. Ne les codez jamais en dur.
• Changements minimaux : Ajoutez le code PostHog aux côtés des intégrations existantes. Ne remplacez ou restructurez pas le code existant.
• Respectez l'exemple : Votre implémentation doit suivre les patterns du projet exemple aussi fidèlement que possible.

Recommandations du framework

• Utilisez la gem posthog-rails aux côtés de posthog-ruby pour la capture automatique d'exceptions et l'instrumentation ActiveJob
• Exécutez rails generate posthog:install pour créer l'initializer, ou créez manuellement config/initializers/posthog.rb
• Configurez auto_capture_exceptions: true pour tracker automatiquement les exceptions non gérées dans les controllers
• Configurez report_rescued_exceptions: true pour capturer aussi les exceptions que Rails gère (par ex. avec rescue_from)
• Configurez auto_instrument_active_job: true pour tracker les échecs des background jobs avec la classe du job, la queue et les arguments
• Utilisez les méthodes de niveau classe PostHog.capture() et PostHog.identify() (PAS les méthodes d'instance) — la gem posthog-rails gère le cycle de vie du client via PostHog.init
• Ne créez PAS manuellement d'instances PostHog::Client dans Rails — utilisez PostHog.init dans l'initializer et PostHog.capture/identify partout ailleurs
• capture_exception prend des arguments POSITIONNELS : PostHog.capture_exception(exception, distinct_id, additional_properties) — n'utilisez PAS les arguments nommés
• Définissez posthog_distinct_id sur le modèle User pour l'association automatique de l'utilisateur dans les rapports d'erreur — posthog-rails détecte automatiquement en essayant : posthog_distinct_id, distinct_id, id, pk, uuid (dans cet ordre)
• Pour l'association d'utilisateur avec ActiveJob, utilisez le DSL de niveau classe posthog_distinct_id ->(user) { user.email } ou passez user_id: dans un argument hash
• Stockez la clé API dans les credentials Rails ou les variables d'environnement, ne la codez jamais en dur
• Pour le tracking frontend aux côtés de posthog-rails, ajoutez le snippet posthog-js au template de layout — posthog-js gère les pageviews, la session replay et les erreurs côté client tandis que posthog-ruby gère les événements backend, les erreurs serveur, les feature flags et les background jobs
• posthog-ruby est le nom de la gem SDK Ruby (ajoutez gem 'posthog-ruby' au Gemfile) mais importez-la avec require 'posthog' (PAS require 'posthog-ruby')
• Utilisez PostHog::Client.new(api_key: key, host: host) pour l'initialisation basée instance dans les scripts et CLIs
• Dans les CLIs et scripts : VOUS DEVEZ appeler client.shutdown avant la sortie ou tous les événements sont perdus
• capture et identify prennent un unique argument hash : client.capture(distinct_id: 'user_123', event: 'my_event', properties: { key: 'value' })
• capture_exception prend des arguments POSITIONNELS (pas nommés) : client.capture_exception(exception, distinct_id, additional_properties) — n'utilisez PAS la syntaxe distinct_id: nommée

Identification des utilisateurs

Identifiez les utilisateurs lors des événements de login et signup. Consultez le code exemple et la documentation pour le pattern d'identification correct pour ce framework. Si du code frontend et backend existe, passez la session côté client et l'ID distinct en utilisant les headers X-POSTHOG-DISTINCT-ID et X-POSTHOG-SESSION-ID pour maintenir la corrélation.

Tracking des erreurs

Ajoutez le tracking PostHog des erreurs aux fichiers pertinents, particulièrement autour des flux utilisateur critiques et des limites d'API.