Skip to content
Rails integration for
Ruby Shell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Userlist::Rails Build Status

This gem helps with integrating into Ruby on Rails applications.


Add this line to your application's Gemfile:

gem 'userlist-rails'

And then execute:

$ bundle

Or install it yourself as:

$ gem install userlist-rails


The only required configuration is the Push API key. You can get your Push API key via the Push API settings in your account.

Configuration values can either be set via an initializer or as environment variables. The environment take precedence over configuration values from the initializer. Please refer to the userlist-ruby gem for additional configuration options.

Configuration via environment variables:


Configuration via an initializer:

# config/initializer/userlist.rb
Userlist.configure do |config|
  config.push_key = '401e5c498be718c0a38b7da7f1ce5b409c56132a49246c435ee296e07bf2be39'

Disabling in development and test environments

As sending test and development data into data into Userlist isn't very desireable, you can disable transmissions by setting the push strategy to :null.

# config/initializer/userlist.rb
Userlist.configure do |config|
  config.push_strategy = :null unless Rails.env.production?


Tracking Users

Sending user data automatically

By default, this gem will automatically detect your User model and create, update, and delete the corresponding user inside of Userlist. To customize the identifier, email, or properties transmitted for a user, you can overwrite the according methods in your User model.

class User < ApplicationRecord
  def userlist_properties
    { first_name: first_name, last_name: last_name }

  def userlist_identifier

  def userlist_email

Sending user data manually

To manually send user data into Userlist, use the Userlist::Push.users.push method.

Userlist::Push.users.push(identifier:, email:, properties: { first_name: user.first_name, last_name: user.last_name })

It's also possible to delete a user from Userlist, using the Userlist::Push.users.delete method.


Tracking Events

To track custom events use the method. 'project_created', user: current_user, properties: { project_name: })

It is possible to make the user property optional by setting it for the entire request using an around_action callback in your ApplicationController.

class ApplicationController < ActionController::Base
  around_action :setup_userlist_current_user

  def setup_userlist_current_user(&block)
    Userlist::Rails.with_current_user(current_user, &block)

This simplifies the tracking call for the current request. 'project_created', properties: { project_name: })

Batch importing

You can import (and update) all your existing users and companies into Userlist by running the import rake task:

rake userlist:import


After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to


Bug reports and pull requests are welcome on GitHub at This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.


The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Userlist::Rails project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

You can’t perform that action at this time.