Ruby

The OpenPanel Ruby SDK allows you to track user behavior in your Ruby applications. This guide provides instructions for installing and using the Ruby SDK in your project.

View the Ruby SDK on GitHub for the latest updates and source code.

Installation

Install dependencies

If you're using Bundler, add to your Gemfile:

bundle add openpanel-sdk

Or install the gem directly:

gem install openpanel-sdk

Set environment variables

Set your environment variables in a .env file:

OPENPANEL_TRACK_URL=https://api.openpanel.dev/track
OPENPANEL_CLIENT_ID=<YOUR_CLIENT_ID>
OPENPANEL_CLIENT_SECRET=<YOUR_CLIENT_SECRET>

Initialize

Require and initialize the OpenPanel SDK:

require 'openpanel-sdk'

tracker = OpenPanel::SDK::Tracker.new

Configuration Options

Common options

apiUrl - The url of the openpanel API or your self-hosted instance
clientId - The client id of your application
clientSecret - The client secret of your application (only required for server-side events)
filter - A function that will be called before sending an event. If it returns false, the event will not be sent
disabled - If true, the library will not send any events

Additional Ruby-specific options:

disabled - Set to true to disable all event tracking
env - Environment name (e.g., Rails.env.to_s)

tracker = OpenPanel::SDK::Tracker.new(
  { env: Rails.env.to_s },
  disabled: Rails.env.development?
)

Usage

Tracking Events

To track an event, use the track method:

tracker.track('test_event', payload: { name: 'test' })

Identifying Users

Create an IdentifyUser object and pass it to the identify method:

identify_user = OpenPanel::SDK::IdentifyUser.new
identify_user.profile_id = 'user_123'
identify_user.email = 'user@example.com'
identify_user.first_name = 'John'
identify_user.last_name = 'Doe'
identify_user.properties = { tier: 'premium', company: 'Acme Inc' }

response = tracker.identify(identify_user)

Incrementing Properties

To increment a numeric property on a user profile:

tracker.increment_property(identify_user, 'visits', 1)

Decrementing Properties

To decrement a numeric property on a user profile:

tracker.decrement_property(identify_user, 'credits', 1)

Filtering Events

Filters are used to prevent sending events to OpenPanel in certain cases. You can filter events by passing a filter lambda to the track method:

filter = lambda { |payload|
  # Return true to send the event, false to skip it
  payload[:name] == 'test'
}

response = tracker.track('test_event', payload: { name: 'test' }, filter: filter)
# If filter returns false, response will be nil

Rails Integration

Setting up the Tracker

Add the following to your application_controller.rb:

before_action :set_openpanel_tracker

protected

def set_openpanel_tracker
  @openpanel_tracker = OpenPanel::SDK::Tracker.new(
    { env: Rails.env.to_s },
    disabled: Rails.env.development?
  )
  @openpanel_tracker.set_header 'x-client-ip', request.ip
  @openpanel_tracker.set_header 'user-agent', request.user_agent
end

Tracking Events in Controllers

Use @openpanel_tracker in your controllers to track events:

def create
  @user = User.create(user_params)
  @openpanel_tracker.track('user_created', payload: { user_id: @user.id })
  redirect_to @user
end

Identifying Users

Create a helper method to convert your app's user model to an IdentifyUser:

def identify_user_from_app_user(user, properties: {})
  iu = OpenPanel::SDK::IdentifyUser.new
  iu.profile_id = user.id.to_s
  iu.email = user.email
  iu.first_name = user.first_name
  iu.last_name = user.last_name
  iu.properties = properties
  iu
end

# Usage in controller
def show
  iu = identify_user_from_app_user(current_user)
  @openpanel_tracker.identify(iu)
end

Advanced Usage

Setting Custom Headers

You can set custom headers for requests:

tracker.set_header 'x-client-ip', request.ip
tracker.set_header 'user-agent', request.user_agent

Error Handling

The SDK returns a Faraday::Response object. Check the response status:

response = tracker.track('event', payload: { name: 'test' })
if response&.status == 200
  puts 'Event tracked successfully'
else
  puts "Failed to track event: #{response&.status}"
end

Disabling Tracking

You can disable tracking during initialization or in specific environments:

# Disable during initialization
tracker = OpenPanel::SDK::Tracker.new({}, disabled: true)

# Or disable in development
tracker = OpenPanel::SDK::Tracker.new(
  { env: Rails.env.to_s },
  disabled: Rails.env.development?
)

Common options

On this page