PostHog Ruby SDK

https://posthog.com/docs/libraries/ruby
Admin
PostHog Ruby SDK provides server-side event tracking and analytics for Ruby applications with fast,...
Tokens:9,586
Snippets:130
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### Bundle Install

Source: https://posthog.com/docs/libraries/ruby-on-rails

Install the added gems into your project.

```bash
bundle install
```

--------------------------------

### Install Gems

Source: https://posthog.com/docs/libraries/ruby-on-rails

Add the required gems to your Gemfile.

```ruby
gem 'posthog-ruby', require: 'posthog'
gem 'posthog-rails'
```

--------------------------------

### Install the Ruby SDK

Source: https://posthog.com/docs/libraries/ruby

Add the posthog-ruby gem to your Gemfile.

```bash
gem "posthog-ruby"
```

--------------------------------

### Verify Middleware Installation

Source: https://posthog.com/docs/libraries/ruby-on-rails

Inspect the application middleware stack to ensure PostHog is properly registered.

```ruby
Rails.application.middleware
```

--------------------------------

### Initialize the PostHog Client

Source: https://posthog.com/docs/libraries/ruby

Create a client instance using your project token. Ensure the host includes the protocol.

```ruby
require 'posthog'
posthog = PostHog::Client.new({
  api_key: "<ph_project_token>",
  host: "https://us.i.posthog.com",
  on_error: Proc.new { |status, msg| print msg }
})
```

```ruby
require 'posthog'
posthog = PostHog::Client.new({
  api_key: '<ph_project_token>',
  host: 'https://us.i.posthog.com',
  on_error: Proc.new { |status, msg| print msg }
})
```

--------------------------------

### Run Wizard

Source: https://posthog.com/docs/libraries/ruby-on-rails

Execute the PostHog wizard to automatically integrate the library.

```bash
npx @posthog/wizard
```

--------------------------------

### Initialize PostHog client in Unicorn server

Source: https://posthog.com/docs/libraries/ruby

Use the after_fork hook in the Unicorn configuration to initialize the PostHog client when using preload_app true.

```ruby
after_fork do |_server, _worker|
  $posthog = PostHog::Client.new({
    api_key: '<ph_project_token>',
    personal_api_key: '<ph_personal_api_key>',
    host: 'https://us.i.posthog.com',
    on_error: Proc.new { |status, msg| print msg }
  })
end
```

--------------------------------

### PostHog::Client.new

Source: https://posthog.com/docs/libraries/ruby

Initializes a new PostHog client instance. It is recommended to use a single client instance (singleton) throughout your application.

```APIDOC
## PostHog::Client.new

### Description
Initializes the PostHog client with the required project token and optional configuration settings.

### Parameters
- **api_key** (String) - Required - Your PostHog project token.
- **host** (String) - Optional - Fully qualified PostHog API host (default: https://us.i.posthog.com).
- **personal_api_key** (String) - Optional - Personal API key for local feature flag evaluation.
- **max_queue_size** (Integer) - Optional - Max events in async queue (default: 10000).
- **batch_size** (Integer) - Optional - Max events per async batch (default: 100).
- **test_mode** (Boolean) - Optional - If true, events are queued but not sent (default: false).
- **sync_mode** (Boolean) - Optional - If true, sends events synchronously (default: false).
- **on_error** (Proc) - Optional - Callback for API or serialization errors.
- **before_send** (Proc) - Optional - Callback to modify or drop events before sending.
```

--------------------------------

### Initialize PostHog client in Puma server

Source: https://posthog.com/docs/libraries/ruby

Use the on_worker_boot hook in the Puma configuration to initialize the PostHog client when running with multiple workers.

```ruby
on_worker_boot do
  $posthog = PostHog::Client.new({
    api_key: '<ph_project_token>',
    personal_api_key: '<ph_personal_api_key>',
    host: 'https://us.i.posthog.com',
    on_error: Proc.new { |status, msg| print msg }
  })
end
```

--------------------------------

### Generate PostHog Initializer

Source: https://posthog.com/docs/libraries/ruby-on-rails

Run this command to create the configuration file for PostHog in a Rails application.

```bash
rails generate posthog:install
```

--------------------------------

### Configure PostHog Initializer

Source: https://posthog.com/docs/libraries/ruby-on-rails

Define Rails-specific settings and core PostHog client options in the generated initializer file.

```ruby
# Rails-specific configuration
PostHog::Rails.configure do |config|
  config.auto_capture_exceptions = true           # Enable automatic exception capture (default: false)
  config.report_rescued_exceptions = true         # Report exceptions Rails rescues (default: false)
  config.auto_instrument_active_job = true        # Instrument background jobs (default: false)
  config.use_tracing_headers = true               # Use PostHog tracing headers for identity/session context (default: true)
  config.capture_user_context = true              # Include authenticated user info in exceptions (default: true)
  config.current_user_method = :current_user      # Method to get current user (default: :current_user)
  config.user_id_method = nil                     # Method to get ID from user object (default: auto-detect)
  # Add additional exceptions to ignore
  config.excluded_exceptions = ['MyCustomError']
end
# Core PostHog client initialization
PostHog.init do |config|
  # Required: Your PostHog project API key
  config.api_key = '<ph_project_token>'
  # Optional: Your PostHog instance URL
  config.host = 'https://us.i.posthog.com'
  # Optional: Personal API key for feature flags
  config.personal_api_key = 'phx_xxxxxxxxx'
  # Maximum number of events to queue before dropping (default: 10000)
  config.max_queue_size = 10_000
  # Send events synchronously on the calling thread (default: false)
  config.sync_mode = false
  # Feature flags polling interval in seconds (default: 30)
  config.feature_flags_polling_interval = 30
  # Feature flag request timeout in seconds (default: 3)
  config.feature_flag_request_timeout_seconds = 3
  # Error callback to detect misconfiguration
  config.on_error = proc { |status, msg|
    Rails.logger.error("PostHog error: #{msg}")
  }
  # Before-send callback to modify or drop events
  config.before_send = proc { |event|
    event[:properties] ||= {}
    event[:properties]['environment'] = Rails.env
    event
  }
  # Disable network calls in test mode
  config.test_mode = true if Rails.env.test?
end
```

--------------------------------

### Verify PostHog Initialization

Source: https://posthog.com/docs/libraries/ruby-on-rails

Use the Rails console to check if the PostHog client is correctly initialized.

```ruby
Rails.console
> PostHog.initialized?
=> true
```

--------------------------------

### Test Helpers

Source: https://posthog.com/docs/libraries/ruby

Methods for inspecting and managing event queues when the client is initialized in test mode.

```APIDOC
## Test Helpers

### Description
When initialized with `test_mode: true`, events are queued instead of sent. Use these methods to verify event capture in tests.

### Methods
- `queued_messages`: Returns the list of currently queued messages.
- `dequeue_last_message`: Removes and returns the last message from the queue.
- `clear`: Clears all messages from the queue.

### Example
```ruby
posthog = PostHog::Client.new({ api_key: '<ph_project_token>', test_mode: true })
posthog.capture({ distinct_id: 'user_123', event: 'test_event' })

# Inspect queue
posthog.queued_messages

# Clear queue
posthog.clear
```
```

--------------------------------

### Manage Credentials with Rails

Source: https://posthog.com/docs/libraries/ruby-on-rails

Use Rails credentials to securely store and reference sensitive API keys.

```bash
rails credentials:edit
```

```yaml
posthog:
  api_key: <ph_project_token>
  host: https://us.i.posthog.com
  personal_api_key: phx_xxxxxxxxx
```

```ruby
config.api_key = Rails.application.credentials.posthog[:api_key]
config.host = Rails.application.credentials.posthog[:host]
config.personal_api_key = Rails.application.credentials.posthog[:personal_api_key]
```

--------------------------------

### Enable PostHog test mode

Source: https://posthog.com/docs/libraries/ruby-on-rails

Configure the PostHog client to run in test mode within the test environment configuration.

```ruby
PostHog.init do |config|
  config.api_key = '<ph_project_token>'
  config.test_mode = true
end
```

--------------------------------

### Configuring User Context

Source: https://posthog.com/docs/libraries/ruby-on-rails

Customize how user identity and distinct IDs are resolved for exception tracking.

```ruby
PostHog::Rails.config.current_user_method = :logged_in_user
```

```ruby
PostHog::Rails.config.user_id_method = :email
```

```ruby
class User < ApplicationRecord
  def posthog_distinct_id
    "user_#{id}"  # or external_id, or any unique identifier
  end
end
```

--------------------------------

### Configure SDK Logging

Source: https://posthog.com/docs/libraries/ruby

Adjust the logger level to DEBUG to troubleshoot client issues.

```ruby
posthog.logger.level = Logger::DEBUG
```

--------------------------------

### Send backend pageviews with Ruby

Source: https://posthog.com/docs/libraries/ruby

Track pageviews from the backend by capturing the $pageview event with a $current_url property.

```ruby
posthog.capture({
    distinct_id: 'distinct_id_of_the_user',
    event: '$pageview',
    properties: {
        '$current_url': 'https://example.com'
    }
})
```

--------------------------------

### Configure personal API key for local evaluation

Source: https://posthog.com/docs/libraries/ruby-on-rails

Set the personal_api_key in your configuration to enable local evaluation of feature flags.

```ruby
config.personal_api_key = Rails.application.credentials.posthog[:personal_api_key]
```

--------------------------------

### Logging Configuration

Source: https://posthog.com/docs/libraries/ruby

Methods to configure the SDK logger for debugging or integration with existing application loggers.

```APIDOC
## Logging Configuration

### Description
Configure the PostHog Ruby SDK logger to debug client issues or redirect logs to your application's logger.

### Usage
```ruby
# Set log level to DEBUG
posthog.logger.level = Logger::DEBUG

# Replace SDK logger globally
PostHog::Logging.logger = Rails.logger
```
```

--------------------------------

### posthog.flush / posthog.shutdown

Source: https://posthog.com/docs/libraries/ruby

Methods to manage the lifecycle of the event queue and background resources.

```APIDOC
## posthog.flush

### Description
Forces the client to send all pending events in the queue immediately.

## posthog.shutdown

### Description
Flushes all pending events and stops background resources. Should be called when the application is stopping.
```

--------------------------------

### Capture custom events with Ruby

Source: https://posthog.com/docs/libraries/ruby

Send custom events using the capture method. Event names should follow an [object] [verb] format.

```ruby
posthog.capture({
    distinct_id: 'distinct_id_of_the_user',
    event: 'user_signed_up'
})
```

--------------------------------

### posthog.capture

Source: https://posthog.com/docs/libraries/ruby

Captures an event and adds it to the internal queue for processing.

```APIDOC
## posthog.capture

### Description
Records an event for a specific user.

### Parameters
- **distinct_id** (String) - Required - The unique identifier for the user.
- **event** (String) - Required - The name of the event to track.
```

--------------------------------

### Associating Background Jobs with Users

Source: https://posthog.com/docs/libraries/ruby-on-rails

Configure how distinct IDs are extracted from background job arguments.

```ruby
# PostHog will automatically use options[:user_id] as the distinct_id
ProcessOrderJob.perform_later(order.id, user_id: current_user.id)
```

```ruby
class SendWelcomeEmailJob < ApplicationJob
  posthog_distinct_id ->(user, _options) { user.id }
  def perform(user, options = {})
    UserMailer.welcome(user).deliver_now
  end
end
```

```ruby
class ProcessOrderJob < ApplicationJob
  posthog_distinct_id do |_order, notify_user_id|
    notify_user_id
  end
  def perform(order, notify_user_id)
    # Process the order...
  end
end
```

--------------------------------

### Set event properties with Ruby

Source: https://posthog.com/docs/libraries/ruby

Include a properties object in the capture call to attach additional metadata to an event.

```ruby
posthog.capture({
    distinct_id: 'distinct_id_of_the_user',
    event: 'user_signed_up',
    properties: {
        login_type: 'email',
        is_free_trial: true
    }
})
```

--------------------------------

### Manual Exception Capture

Source: https://posthog.com/docs/libraries/ruby-on-rails

Manually report exceptions to PostHog, optionally including feature flag snapshots for context.

```ruby
PostHog.capture_exception(
  exception,
  current_user.id,
  { custom_property: 'value' }
)
```

```ruby
flags = PostHog.evaluate_flags(current_user.id)
PostHog.capture_exception(
  exception,
  current_user.id,
  { custom_property: 'value' },
  flags: flags
)
```

--------------------------------

### Configure feature flag request timeout

Source: https://posthog.com/docs/libraries/ruby

Set the feature_flag_request_timeout_seconds parameter during client initialization to control how long the SDK waits for a response.

```ruby
posthog = PostHog::Client.new({
    # rest of your configuration...
    feature_flag_request_timeout_seconds: 3 # Time in seconds. Defaults to 3.
})
```

--------------------------------

### Capture events with flag snapshots

Source: https://posthog.com/docs/libraries/ruby-on-rails

Include the flags snapshot in event capture to ensure the event reflects the exact flag values used during execution.

```ruby
flags = PostHog.evaluate_flags(current_user.id)
PostHog.capture({
  distinct_id: current_user.id,
  event: 'checkout_started',
  flags: flags.only_accessed
})
```

--------------------------------

### posthog.capture

Source: https://posthog.com/docs/libraries/ruby

Captures an event and associates it with one or more groups.

```APIDOC
## posthog.capture(options)

### Description
Captures an event and associates it with a group.

### Parameters
- **options** (hash) - Required - Contains distinct_id, event, properties, and groups.

### Example
```ruby
posthog.capture({
    distinct_id: 'distinct_id_of_the_user',
    event: 'movie_played',
    properties: {
        movie_id: '123',
        category: 'romcom'
    },
    groups: {
        'company': 'company_id_in_your_db'
    }
})
```
```

--------------------------------

### Set person properties during event capture

Source: https://posthog.com/docs/libraries/ruby

Use $set to update properties and $set_once to set properties only if they do not already exist.

```ruby
posthog.capture({
    distinct_id: 'distinct_id',
    event: 'event_name',
    properties: {
        '$set': { name: 'Max Hedgehog' },
        '$set_once': { initial_url: '/blog' }
    }
})
```

--------------------------------

### posthog.capture

Source: https://posthog.com/docs/libraries/ruby

Captures an event and optionally updates person properties or disables person profile creation.

```APIDOC
## posthog.capture

### Description
Captures an event. You can include `$set` or `$set_once` in the properties to update person profiles, or set `$process_person_profile` to false to skip profile creation.

### Parameters
- **distinct_id** (string) - Required - The unique identifier for the user.
- **event** (string) - Required - The name of the event.
- **properties** (hash) - Optional - A hash containing event properties, including special keys like `$set`, `$set_once`, or `$process_person_profile`.

### Request Example
```ruby
posthog.capture({
    distinct_id: 'distinct_id',
    event: 'event_name',
    properties: {
        '$set': { name: 'Max Hedgehog' },
        '$set_once': { initial_url: '/blog' }
    }
})
```
```

--------------------------------

### Identify users

Source: https://posthog.com/docs/libraries/ruby-on-rails

Associate a user with their unique ID and set person properties.

```ruby
PostHog.identify({
  distinct_id: current_user.id,
  properties: {
    email: current_user.email,
    plan: current_user.plan
  }
})
```

--------------------------------

### posthog.identify

Source: https://posthog.com/docs/libraries/ruby

Identifies a user and sets their person properties. This is required to link backend events to frontend user sessions.

```APIDOC
## posthog.identify

### Description
Identifies a user and sets their person properties. This is required to link backend events to frontend user sessions.

### Parameters
- **distinct_id** (String) - Required - The unique ID of the user.
- **properties** (Hash) - Optional - Key-value pairs of user properties.
```

--------------------------------

### capture_exception(exception, distinct_id, additional_properties, flags:)

Source: https://posthog.com/docs/libraries/ruby

Manually capture an exception in non-Rails Ruby applications to track errors and stack traces in PostHog.

```APIDOC
## capture_exception

### Description
Captures an exception event to PostHog, allowing for stack trace analysis and error debugging.

### Method
`posthog.capture_exception(exception, distinct_id, additional_properties, flags: nil)`

### Parameters
- **exception** (Exception, String, or exception-like object) - Required - The exception to capture.
- **distinct_id** (String) - Optional - The distinct ID of the user. If not provided, the SDK generates a UUID.
- **additional_properties** (Hash) - Optional - Additional properties to attach to the exception event.
- **flags** (PostHog::FeatureFlagEvaluations) - Optional - Keyword argument to add feature flag properties.

### Usage Example
```ruby
begin
  raise StandardError, 'Something went wrong'
rescue => e
  posthog.capture_exception(
    e,
    'user_distinct_id',
    {
      custom_property: 'custom_value'
    }
  )
end
```

### Fingerprint Customization
You can group exceptions by providing a custom fingerprint in the additional_properties hash:
```ruby
posthog.capture_exception(
  e,
  'user_distinct_id',
  {
    '$exception_fingerprint': 'CustomExceptionGroup'
  }
)
```
```

--------------------------------

### Manage Event Queue in Test Mode

Source: https://posthog.com/docs/libraries/ruby

Inspect and clear the event queue when test_mode is enabled to verify captured events.

```ruby
posthog = PostHog::Client.new({ api_key: '<ph_project_token>', test_mode: true })
posthog.capture({ distinct_id: 'user_123', event: 'test_event' })
posthog.queued_messages
posthog.dequeue_last_message
posthog.clear
```

--------------------------------

### Configure tracing headers

Source: https://posthog.com/docs/libraries/ruby-on-rails

Disable the automatic use of client-supplied tracing headers for server-side events.

```ruby
PostHog::Rails.config.use_tracing_headers = false
```

--------------------------------

### Flush and Shutdown Client

Source: https://posthog.com/docs/libraries/ruby

Manually flush events or shut down the client to ensure all pending events are processed before script termination.

```ruby
posthog.capture({ distinct_id: 'user_123', event: 'script_finished' })
posthog.flush
posthog.shutdown
```

--------------------------------

### Evaluate flags locally

Source: https://posthog.com/docs/libraries/ruby

Skip remote requests by evaluating flags using only locally cached definitions.

```ruby
flags = posthog.evaluate_flags(
    'distinct_id_of_your_user',
    only_evaluate_locally: true,
)
```

--------------------------------

### Evaluate specific feature flags

Source: https://posthog.com/docs/libraries/ruby

Limit the evaluation to a specific list of flag keys to improve performance.

```ruby
flags = posthog.evaluate_flags(
    'distinct_id_of_your_user',
    flag_keys: ['checkout-flow', 'new-dashboard'],
)
```

--------------------------------

### posthog.evaluate_flags(distinct_id, options)

Source: https://posthog.com/docs/libraries/ruby

Evaluates feature flags for a specific user. Returns a snapshot object that can be used to check flag status and capture event properties.

```APIDOC
## posthog.evaluate_flags(distinct_id, options)

### Description
Evaluates feature flags for a given user. This method should be called once per user to retrieve a snapshot of flag values.

### Parameters
- **distinct_id** (string) - Required - The unique identifier of the user.
- **flag_keys** (array) - Optional - A list of specific flag keys to evaluate.
- **only_evaluate_locally** (boolean) - Optional - If true, skips remote requests and uses locally cached definitions.
- **disable_geoip** (boolean) - Optional - If true, disables GeoIP lookup for remote evaluation.

### Usage Example
```ruby
flags = posthog.evaluate_flags('distinct_id_of_your_user', flag_keys: ['checkout-flow'])
if flags.enabled?('checkout-flow')
  # Logic for enabled flag
end
```
```

--------------------------------

### Replace SDK Logger

Source: https://posthog.com/docs/libraries/ruby

Override the default SDK logger with a custom logger, such as the Rails logger.

```ruby
PostHog::Logging.logger = Rails.logger
```

--------------------------------

### posthog.capture

Source: https://posthog.com/docs/libraries/ruby

Sends custom events to PostHog. Supports additional event properties, group analytics, and custom timestamps.

```APIDOC
## posthog.capture

### Description
Sends custom events to PostHog. Supports additional event properties, group analytics, and custom timestamps.

### Parameters
- **distinct_id** (String) - Optional - The user ID.
- **event** (String) - Required - The name of the event.
- **properties** (Hash) - Optional - Event properties.
- **groups** (Hash) - Optional - Group analytics mapping.
- **timestamp** (Time) - Optional - When the event occurred.
- **message_id** (String) - Optional - Message ID.
- **uuid** (String) - Optional - Event UUID for deduplication.
- **flags** (PostHog::FeatureFlagEvaluations) - Optional - Snapshot of feature flag evaluations.
```

--------------------------------

### Capture custom events

Source: https://posthog.com/docs/libraries/ruby-on-rails

Track custom events within a Rails application using the PostHog client.

```ruby
PostHog.capture({
  distinct_id: current_user.id,
  event: 'post_created',
  properties: { title: @post.title }
})
```

--------------------------------

### Configure distributed flag definition caching

Source: https://posthog.com/docs/libraries/ruby

Pass a custom cache provider to the PostHog client to share feature flag definitions across multiple processes.

```ruby
posthog = PostHog::Client.new({
  api_key: '<ph_project_token>',
  personal_api_key: '<ph_personal_api_key>',
  flag_definition_cache_provider: my_cache_provider
})
```

--------------------------------

### Identify a user with Ruby

Source: https://posthog.com/docs/libraries/ruby

Use identify to associate a user with a distinct_id and set their person properties. This is required to link backend events to frontend sessions.

```ruby
posthog.identify({
  distinct_id: 'distinct_id_of_your_user',
  properties: {
    email: 'john@doe.com',
    pro_user: false
  }
})
```

--------------------------------

### Manually include feature flag properties

Source: https://posthog.com/docs/libraries/ruby

Include specific feature flag variants in the event properties manually.

```ruby
posthog.capture({
    distinct_id: 'distinct_id_of_your_user',
    event: 'event_name',
    properties: {
        # Replace feature-flag-key with your flag key and 'variant-key' with the key of your variant
        '$feature/feature-flag-key': 'variant-key',
    },
})
```

--------------------------------

### Capture events with group association in Ruby

Source: https://posthog.com/docs/libraries/ruby

Associate an event with a specific group by including the groups property in the capture call.

```ruby
posthog.capture({
    distinct_id: 'distinct_id_of_the_user',
    event: 'movie_played',
    properties: {
        movie_id: '123',
        category: 'romcom'
    },
    groups: {
        'company': 'company_id_in_your_db'
    }
})
```

--------------------------------

### Background Job Exception Tracking

Source: https://posthog.com/docs/libraries/ruby-on-rails

ActiveJob exceptions are captured automatically when auto_instrument_active_job is enabled.

```ruby
class EmailJob < ApplicationJob
  def perform(user_id)
    user = User.find(user_id)
    UserMailer.welcome(user).deliver_now
    # Exceptions are automatically captured
  end
end
```

--------------------------------

### Capture events with filtered flag snapshots

Source: https://posthog.com/docs/libraries/ruby

Reduce event property size by attaching only accessed flags or a specific subset of flags.

```ruby
# Attach only flags accessed with enabled?() or get_flag() before this call
posthog.capture({
    distinct_id: 'distinct_id_of_your_user',
    event: 'event_name',
    flags: flags.only_accessed,
})
# Attach only specific flags
posthog.capture({
    distinct_id: 'distinct_id_of_your_user',
    event: 'event_name',
    flags: flags.only(['checkout-flow', 'new-dashboard']),
})
```

--------------------------------

### Rails 7.0+ Error Reporter Integration

Source: https://posthog.com/docs/libraries/ruby-on-rails

Integrate with Rails' built-in error reporting to automatically send errors to PostHog.

```ruby
# These errors are automatically sent to PostHog
Rails.error.handle do
  # Code that might raise an error
end
Rails.error.record(exception, context: { user_id: current_user.id })
```

--------------------------------

### posthog.capture(event_data)

Source: https://posthog.com/docs/libraries/ruby

Captures an event and optionally attaches feature flag information to ensure correct attribution in insights.

```APIDOC
## posthog.capture(event_data)

### Description
Captures an event. To include feature flag information, pass the flags snapshot object or manually include flag properties.

### Parameters
- **distinct_id** (string) - Required - The unique identifier of the user.
- **event** (string) - Required - The name of the event.
- **flags** (object) - Optional - The flags snapshot object returned by evaluate_flags.
- **properties** (hash) - Optional - Custom properties, including manual feature flag keys prefixed with $feature/.

### Usage Example
```ruby
posthog.capture({
    distinct_id: 'user_123',
    event: 'purchase',
    flags: flags.only(['checkout-flow'])
})
```
```

--------------------------------

### posthog.evaluate_flags

Source: https://posthog.com/docs/libraries/ruby

Evaluates feature flags for a specific user to determine experiment variants.

```APIDOC
## posthog.evaluate_flags(distinct_id)

### Description
Evaluates all feature flags for a given user distinct ID.

### Parameters
- **distinct_id** (string) - Required - The unique identifier for the user.

### Example
```ruby
flags = posthog.evaluate_flags('user_distinct_id')
variant = flags.get_flag('experiment-feature-flag-key')
```
```

--------------------------------

### Capture events with feature flag snapshot

Source: https://posthog.com/docs/libraries/ruby

Pass the evaluated flags object to the capture method to associate flag state with an event.

```ruby
flags = posthog.evaluate_flags('distinct_id_of_your_user')
if flags.enabled?('flag-key')
    # Do something differently for this user
end
posthog.capture({
    distinct_id: 'distinct_id_of_your_user',
    event: 'event_name',
    flags: flags,
})
```

--------------------------------

### posthog.alias

Source: https://posthog.com/docs/libraries/ruby

Assigns an additional distinct ID to a user, allowing multiple IDs to map to the same person profile.

```APIDOC
## posthog.alias

### Description
Links an alias to an existing distinct ID.

### Parameters
- **distinct_id** (string) - Required - The current distinct ID.
- **alias** (string) - Required - The new alias ID to associate with the user.

### Request Example
```ruby
posthog.alias({
  distinct_id: 'distinct_id',
  alias: 'alias_id'
})
```
```

--------------------------------

### Evaluate feature flags for experiments in Ruby

Source: https://posthog.com/docs/libraries/ruby

Use evaluate_flags to retrieve flag variants for a specific user distinct ID.

```ruby
flags = posthog.evaluate_flags('user_distinct_id')
variant = flags.get_flag('experiment-feature-flag-key')
if variant == 'variant-name'
    # Do something
end
```

--------------------------------

### Fetch remote config payload

Source: https://posthog.com/docs/libraries/ruby

Retrieve the decrypted remote configuration payload for a specific flag key. Requires a personal_api_key.

```ruby
payload = posthog.get_remote_config_payload('flag-key')
```

--------------------------------

### Customize exception grouping with fingerprints

Source: https://posthog.com/docs/libraries/ruby

Override the default exception grouping by providing a custom fingerprint in the additional properties hash.

```ruby
posthog.capture_exception(
  e,
  'user_distinct_id',
  {
    '$exception_fingerprint': 'CustomExceptionGroup'
  }
)
```

--------------------------------

### Mock PostHog capture in RSpec

Source: https://posthog.com/docs/libraries/ruby-on-rails

Use RSpec to stub the capture method during test execution.

```ruby
RSpec.configure do |config|
  config.before(:each) do
    allow(PostHog).to receive(:capture)
  end
end
```

--------------------------------

### Retrieve multivariate flag variants

Source: https://posthog.com/docs/libraries/ruby-on-rails

Use get_flag to determine the specific variant assigned to a user for experiments or multivariate flags.

```ruby
flags = PostHog.evaluate_flags(current_user.id)
variant = flags.get_flag('checkout-experiment')
if variant == 'test'
  # Do something differently
end
```

--------------------------------

### Alias distinct IDs

Source: https://posthog.com/docs/libraries/ruby

Use the alias method to associate an additional distinct ID with an existing user profile.

```ruby
posthog.alias({
  distinct_id: 'distinct_id',
  alias: 'alias_id'
})
```

--------------------------------

### Disable person profile creation

Source: https://posthog.com/docs/libraries/ruby

Set the $process_person_profile property to false to capture events without creating or updating a person profile.

```ruby
posthog.capture({
    distinct_id: 'distinct_id',
    event: 'event_name',
    properties: {
        '$process_person_profile': false
    }
})
```

--------------------------------

### get_remote_config_payload(flag_key)

Source: https://posthog.com/docs/libraries/ruby

Fetches the decrypted remote config payload for a specific feature flag. This method requires a personal_api_key to be configured in the client.

```APIDOC
## get_remote_config_payload(flag_key)

### Description
Fetches the decrypted remote config payload for a flag. This requires `personal_api_key` to be set in the PostHog client initialization.

### Parameters
- **flag_key** (string) - Required - The unique identifier for the feature flag.

### Response
- **payload** (hash/object) - The decrypted remote configuration data.
```

--------------------------------

### Filter or Modify Events

Source: https://posthog.com/docs/libraries/ruby

Use the before_send callback to modify event properties or drop events by returning nil.

```ruby
posthog = PostHog::Client.new({
  api_key: '<ph_project_token>',
  before_send: Proc.new do |event|
    event[:properties] ||= {}
    event[:properties]['environment'] = ENV['RACK_ENV']
    # Return nil to drop the event
    event[:properties]['internal_user'] == true ? nil : event
  end
})
```

--------------------------------

### Capture exceptions manually in Ruby

Source: https://posthog.com/docs/libraries/ruby

Use this method to manually report exceptions in non-Rails applications. Ensure the exception is caught within a rescue block before passing it to the capture_exception method.

```ruby
begin
  # Code that might raise an exception
  raise StandardError, 'Something went wrong'
rescue => e
  posthog.capture_exception(
    e,
    'user_distinct_id',
    {
      custom_property: 'custom_value'
    }
  )
end
```

--------------------------------

### posthog.group_identify

Source: https://posthog.com/docs/libraries/ruby

Updates properties on a specific group.

```APIDOC
## posthog.group_identify(options)

### Description
Updates properties on a group. The 'name' property is used in the PostHog UI.

### Parameters
- **options** (hash) - Required - Contains group_type, group_key, and properties.

### Example
```ruby
posthog.group_identify({
  group_type: 'company',
  group_key: 'company_id_in_your_db',
  properties: {
    name: 'Awesome Inc.'
  }
})
```
```

--------------------------------

### Excluding Exceptions

Source: https://posthog.com/docs/libraries/ruby-on-rails

Add specific exception classes to the list of ignored errors.

```ruby
PostHog::Rails.config.excluded_exceptions = ['MyException']
```

--------------------------------

### Evaluate boolean feature flags

Source: https://posthog.com/docs/libraries/ruby

Use evaluate_flags to retrieve a snapshot and check if a specific boolean flag is enabled.

```ruby
flags = posthog.evaluate_flags('distinct_id_of_your_user')
if flags.enabled?('flag-key')
    # Do something differently for this user
    # Optional: fetch the payload
    matched_flag_payload = flags.get_flag_payload('flag-key')
end
```

--------------------------------

### Evaluate feature flags with overridden properties

Source: https://posthog.com/docs/libraries/ruby

Use evaluate_flags to manually provide person and group properties for flag evaluation, bypassing server-stored values.

```ruby
flags = posthog.evaluate_flags(
    'distinct_id_of_the_user',
    person_properties: {
        property_name: 'value'
    },
    groups: {
        your_group_type: 'your_group_id',
        another_group_type: 'your_group_id',
    },
    group_properties: {
        your_group_type: {
            group_property_name: 'value'
        },
        another_group_type: {
            group_property_name: 'value'
        },
    },
)
if flags.enabled?('flag-key')
    # Do something differently for this user
end
```

--------------------------------

### Automatic Exception Tracking in Rails Controllers

Source: https://posthog.com/docs/libraries/ruby-on-rails

Exceptions raised within controller actions are automatically captured when auto_capture_exceptions is enabled.

```ruby
class PostsController < ApplicationController
  def show
    @post = Post.find(params[:id])
    # Any exception here is automatically captured
  end
end
```

--------------------------------

### Update group properties in Ruby

Source: https://posthog.com/docs/libraries/ruby

Use group_identify to set or update properties for a specific group type and key.

```ruby
posthog.group_identify({
  group_type: 'company',
  group_key: 'company_id_in_your_db',
  properties: {
    name: 'Awesome Inc.'
  }
})
```

--------------------------------

### Disable GeoIP for flag evaluation

Source: https://posthog.com/docs/libraries/ruby

Prevent GeoIP lookup during remote flag evaluation.

```ruby
flags = posthog.evaluate_flags(
    'distinct_id_of_your_user',
    disable_geoip: true,
)
```

--------------------------------

### Evaluate feature flags in a Rails controller

Source: https://posthog.com/docs/libraries/ruby-on-rails

Use evaluate_flags to check if a feature is enabled for a specific user within a controller action.

```ruby
class PostsController < ApplicationController
  def show
    flags = PostHog.evaluate_flags(current_user.id)
    if flags.enabled?('new-post-design')
      render 'posts/show_new'
    else
      render 'posts/show'
    end
  end
end
```
Tokens:
Raw