Userlist::Rails
This gem helps with integrating Userlist.io into Ruby on Rails applications.
Installation
Add this line to your application's Gemfile:
gem 'userlist-rails'
And then execute:
$ bundle
Or install it yourself as:
$ gem install userlist-rails
Configuration
The only required configuration is the Push API key. You can get your Push API key via the Push API settings in your Userlist.io 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:
USERLIST_PUSH_KEY=401e5c498be718c0a38b7da7f1ce5b409c56132a49246c435ee296e07bf2be39
Configuration via an initializer:
# config/initializer/userlist.rb
Userlist.configure do |config|
config.push_key = '401e5c498be718c0a38b7da7f1ce5b409c56132a49246c435ee296e07bf2be39'
end
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?
end
Usage
Tracking Users
Sending user data automatically
By default, this gem will automatically detect your User
model and create and update 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 }
end
def userlist_identifier
"user-#{id}"
end
def userlist_email
email
end
end
Sending user data manually
To manually send user data into Userlist, use the Userlist::Push.user
method.
Userlist::Push.user(identifier: user.id, email: user.email, properties: { first_name: user.first_name, last_name: user.last_name })
Tracking Events
To track custom events use the Userlist::Push.event
method.
Userlist::Push.event(name: 'project_created', user: current_user, properties: { project_name: 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)
end
end
This simplifies the tracking call for the current request.
Userlist::Push.event(name: 'project_created', properties: { project_name: 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
Development
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 rubygems.org.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/userlistio/userlist-rails. 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.
License
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.