mcpField
I
integration-ruby-on-rails

integration-ruby-on-rails

github.com/posthog数据与数据库7692 次安装今天更新
代码仓库

关于 integration-ruby-on-rails

此技能帮助 Ruby on Rails 应用集成 PostHog 分析，提供分阶段流程、示例代码及异常捕获、ActiveJob 追踪、用户识别和后端事件指南。

主要功能

  1. 01四步集成流程
  2. 02Rails 与 Ruby 参考资料
  3. 03异常与 ActiveJob 追踪
  4. 04类级别的 capture 和 identify 方法
  5. 05通过环境变量或凭据存储密钥

适用场景

  1. 01为 Rails 应用添加 PostHog 分析
  2. 02追踪后台任务失败
  3. 03捕获已处理和未处理的异常
  4. 04在错误报告中关联用户

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/posthog/skills --skill integration-ruby-on-rails

安装后在 Claude Code 中输入/integration-ruby-on-rails确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
basic-integration-1.0-begin.md
basic-integration-1.1-edit.md
basic-integration-1.2-revise.md
basic-integration-1.3-conclude.md
EXAMPLE.md
identify-users.md
ruby-on-rails.md
ruby.md

详细介绍

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 代码。不要替换或重构现有代码。
  • 遵循示例：实现应尽可能贴合示例项目中的模式。

框架指南

  • 将 posthog-rails gem 与 posthog-ruby 配合使用，以自动捕获异常并监测 ActiveJob
  • 运行 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 凭据或环境变量中，切勿硬编码
  • 如果要将前端跟踪与 posthog-rails 配合使用，请将 posthog-js 代码片段添加到布局模板中——posthog-js 负责处理页面浏览、会话回放和客户端错误，posthog-ruby 则负责处理后端事件、服务器错误、功能开关和后台作业
  • posthog-ruby 是 Ruby SDK gem 的名称（在 Gemfile 中添加 gem 'posthog-ruby'），但需要通过 require 'posthog' 加载（而不是 require 'posthog-ruby'）
  • 在脚本和 CLI 中进行基于实例的初始化时，使用 PostHog::Client.new(api_key: key, host: host)
  • 在 CLI 和脚本中：退出前必须调用 client.shutdown，否则所有事件都会丢失
  • 使用 begin/rescue/ensure，并在 ensure 块中调用 shutdown，以确保正确清理
  • 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: 关键字语法

识别用户

在登录和注册事件期间识别用户。请参阅示例代码和文档，了解适用于此框架的正确识别模式。如果前端和后端代码都存在，请使用 X-POSTHOG-DISTINCT-ID 和 X-POSTHOG-SESSION-ID 标头传递客户端会话和 distinct ID，以保持关联。

错误追踪

在相关文件中添加 PostHog 错误追踪，尤其是在关键用户流程和 API 边界附近。

评论

支持 Markdown