This gem helps with integrating Userlist into Ruby applications.
To integrate Userlist into a Ruby on Rails application, please use userlist-rails
Add this line to your application's Gemfile:
gem 'userlist'
And then execute:
$ bundle
Or install it yourself as:
$ gem install userlist
The only required configuration is the Push API key. You can get your Push API key via the Push API settings in your Userlist account.
Configuration values can either be set via the Userlist.configure
method or as environment variables. The environment variables take precedence over configuration values from the initializer.
Configuration via environment variables:
USERLIST_PUSH_KEY=VvB7pjDrv0V2hoaOCeZ5rIiUEPbEhSUN
USERLIST_PUSH_ID=6vPkJl44cm82y4aLBIzaOhuEHJd0Bm7b
Configuration via an initializer:
Userlist.configure do |config|
config.push_key = 'VvB7pjDrv0V2hoaOCeZ5rIiUEPbEhSUN'
config.push_id = '6vPkJl44cm82y4aLBIzaOhuEHJd0Bm7b'
end
The possible configuration values are listed in the table below.
Name | Default value | Description |
---|---|---|
push_key |
nil |
The push key for your account. See Push API settings. |
push_id |
nil |
The push id for your account. See Push API settings. |
push_endpoint |
https://push.userlist.com/ |
The HTTP endpoint that the library will send data to. |
push_strategy |
:threaded |
The strategy to use to send data to the HTTP endpoint. Possible values are :threaded , :sidekiq , :active_job , :direct , and :null . |
push_strategy_options |
{} |
Any additional options for the push strategy. |
log_level |
:warn |
The log level for Userlist related log messages. Possible values are :debug , :error , :fatal , :info , and :warn |
token_lifetime |
3600 |
The lifetime of generated in-app messages tokens in seconds |
As sending test and development data into data into Userlist isn't very desirable, you can disable transmissions by setting the push strategy to :null
.
Userlist.configure do |config|
config.push_strategy = :null
end
This library is a wrapper for Userlist's Push API. For details about the accepted payloads, please check its documentation.
To manually send user data into Userlist, use the Userlist::Push.users.push
method.
Userlist::Push.users.push(
identifier: 'user-1',
email: 'foo@example.com',
properties: {
first_name: 'Foo',
last_name: 'Example'
}
)
It's also possible to delete a user from Userlist, using the Userlist::Push.users.delete
method.
Userlist::Push.users.delete('user-1')
To manually send company data into Userlist, use the Userlist::Push.companies.push
method.
Userlist::Push.companies.push(
identifier: 'company-1',
email: 'Example, Inc.',
properties: {
industry: 'Software Testing'
}
)
It's also possible to delete a user from Userlist, using the Userlist::Push.companies.delete
method.
Userlist::Push.companies.delete('user-1')
Tracking relationships can either be done using nested properties in user or company payloads or via the Userlist::Push.relationships.push
method.
Userlist::Push.relationships.push(
user: 'user-1',
company: 'company-1',
properties: {
role: 'owner'
}
)
This is equivalent to specifying the relationship on the user model.
Userlist::Push.users.push(
identifier: 'user-1',
relationships: [
{
company: 'company-1',
properties: {
role: 'owner'
}
}
]
)
It's also equivalent specifying the relationship on the company model.
Userlist::Push.companies.push(
identifier: 'company-1',
relationships: [
{
user: 'user-1',
properties: {
role: 'owner'
}
}
]
)
To track custom events use the Userlist::Push.events.push
method.
Userlist::Push.events.push(
name: 'project_created',
user: 'user-1',
properties: {
project_name: 'Example project'
}
)
Instead of just sending a user or company identifier, it's also possible to expand the properties into objects. This will update the user / company record as well as trigger the event in one operation.
Userlist::Push.events.push(
name: 'project_created',
user: {
identifier: 'user-1',
properties: {
projects: 5
}
},
properties: {
project_name: 'Example project'
}
)
In order to use in-app messages, you must create a JWT token for the currently signed in user on the server side. To do this, please configure both the push_key
and the push_id
configuration variables. Afterwards, you can use the Userlist::Token.generate
method to get a signed token for the given user identifier.
Userlist::Token.generate('user-1')
# => "eyJraWQiOiI2dlBrSmw0NGNtODJ5NGFMQkl6YU9odU...kPGe8KX8JZBTQ"
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.
Bug reports and pull requests are welcome on GitHub at https://github.com/userlist/userlist-ruby. 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.
Everyone interacting in the Userlist project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.
Userlist allows you to onboard and engage your SaaS users with targeted behavior-based campaigns using email or in-app messages.
Userlist was started in 2017 as an alternative to bulky enterprise messaging tools. We believe that running SaaS products should be more enjoyable. Learn more about us.