integration-ruby-on-rails

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PostHog integration for Ruby on Rails

Ruby on Rails应用的PostHog集成

This skill helps you add PostHog analytics to Ruby on Rails applications.

本技能可帮助你为Ruby on Rails应用添加PostHog分析功能。

Workflow

操作流程

Follow these steps in order to complete the integration:

```
basic-integration-1.0-begin.md
```
- PostHog Setup - Begin ← Start here
```
basic-integration-1.1-edit.md
```
- PostHog Setup - Edit
```
basic-integration-1.2-revise.md
```
- PostHog Setup - Revise
```
basic-integration-1.3-conclude.md
```
- PostHog Setup - Conclusion

请按以下步骤完成集成：

```
basic-integration-1.0-begin.md
```
- PostHog 设置 - 开始 ← 从此处启动
```
basic-integration-1.1-edit.md
```
- PostHog 设置 - 编辑
```
basic-integration-1.2-revise.md
```
- PostHog 设置 - 修改
```
basic-integration-1.3-conclude.md
```
- PostHog 设置 - 总结

Reference files

参考文件

```
references/EXAMPLE.md
```
- Ruby on Rails example project code
```
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

The example project shows the target implementation pattern. Consult the documentation for API details.

```
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详情，请查阅相关文档。

Key principles

核心原则

Environment variables: Always use environment variables for PostHog keys. Never hardcode them.
Minimal changes: Add PostHog code alongside existing integrations. Don't replace or restructure existing code.
Match the example: Your implementation should follow the example project's patterns as closely as possible.

环境变量：始终使用环境变量存储PostHog密钥，绝对不要硬编码。
最小改动：在现有集成代码旁添加PostHog代码，不要替换或重构现有代码。
匹配示例：你的实现应尽可能贴近示例项目的模式。

Framework guidelines

框架指南

Use posthog-rails gem alongside posthog-ruby for automatic exception capture and ActiveJob instrumentation
Run
```
rails generate posthog:install
```
to create the initializer, or manually create config/initializers/posthog.rb
Configure auto_capture_exceptions: true to automatically track unhandled exceptions in controllers
Configure report_rescued_exceptions: true to also capture exceptions that Rails rescues (e.g. with rescue_from)
Configure auto_instrument_active_job: true to track background job failures with job class, queue, and arguments
Use PostHog.capture() and PostHog.identify() class-level methods (NOT instance methods) — the posthog-rails gem manages the client lifecycle via PostHog.init
Do NOT manually create PostHog::Client instances in Rails — use PostHog.init in the initializer and PostHog.capture/identify everywhere else
capture_exception takes POSITIONAL args: PostHog.capture_exception(exception, distinct_id, additional_properties) — do NOT use keyword args
Define posthog_distinct_id on the User model for automatic user association in error reports — posthog-rails auto-detects by trying: posthog_distinct_id, distinct_id, id, pk, uuid (in order)
For ActiveJob user association, use the class-level DSL
```
posthog_distinct_id ->(user) { user.email }
```
or pass user_id: in a hash argument
Store API key in Rails credentials or environment variables, never hardcode
For frontend tracking alongside posthog-rails, add the posthog-js snippet to the layout template — posthog-js handles pageviews, session replay, and client-side errors while posthog-ruby handles backend events, server errors, feature flags, and background jobs
posthog-ruby is the Ruby SDK gem name (add
```
gem 'posthog-ruby'
```
to Gemfile) but require it with
```
require 'posthog'
```
(NOT
```
require 'posthog-ruby'
```
)
Use PostHog::Client.new(api_key: key, host: host) for instance-based initialization in scripts and CLIs
In CLIs and scripts: MUST call client.shutdown before exit or all events are lost
Use begin/rescue/ensure with shutdown in the ensure block for proper cleanup
capture and identify take a single hash argument: client.capture(distinct_id: 'user_123', event: 'my_event', properties: { key: 'value' })
capture_exception takes POSITIONAL args (not keyword): client.capture_exception(exception, distinct_id, additional_properties) — do NOT use
```
distinct_id:
```
keyword syntax

搭配使用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:
```
关键字语法

Identifying users

用户识别

Identify users during login and signup events. Refer to the example code and documentation for the correct identify pattern for this framework. If both frontend and backend code exist, pass the client-side session and distinct ID using

X-POSTHOG-DISTINCT-ID

and

X-POSTHOG-SESSION-ID

headers to maintain correlation.

在登录和注册事件中识别用户。请参考示例代码和文档，了解该框架的正确识别模式。如果同时存在前端和后端代码，使用

X-POSTHOG-DISTINCT-ID

和

X-POSTHOG-SESSION-ID

头传递客户端会话和唯一ID，以保持关联。

Error tracking

错误追踪

Add PostHog error tracking to relevant files, particularly around critical user flows and API boundaries.

为相关文件添加PostHog错误追踪，尤其是关键用户流程和API边界处的文件。