Hey Product Hunt 👋 Get 30% off your first 3 months if you sign up using this link

Ruby Integration

This gem helps with integrating Userlist into Ruby applications. To integrate Userlist into a Ruby on Rails application, please see our Ruby on Rails Integration.

See more details on the customer data structure in our general integration guide.

Installation

Add this line to your application's Gemfile:

1
gem 'userlist'

And then execute:

1
$ bundle

Or install it yourself as:

1
$ gem install userlist

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 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:

1
2
USERLIST_PUSH_KEY=VvB7pjDrv0V2hoaOCeZ5rIiUEPbEhSUN
USERLIST_PUSH_ID=6vPkJl44cm82y4aLBIzaOhuEHJd0Bm7b

Configuration via an initializer:

1
2
3
4
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, :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

Disabling in development and test environments

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.

1
2
3
Userlist.configure do |config|
  config.push_strategy = :null
end

Usage

This library is a wrapper for Userlist's Push API. For details about the accepted payloads, please check its documentation.

Tracking Users

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

1
2
3
4
5
6
7
8
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.

1
Userlist::Push.users.delete('user-1')

Tracking Companies

To manually send company data into Userlist, use the Userlist::Push.companies.push method.

1
2
3
4
5
6
7
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.

1
Userlist::Push.companies.delete('user-1')

Tracking Relationships

Tracking relationships can either be done using nested properties in user or company payloads or via the Userlist::Push.relationships.push method.

1
2
3
4
5
6
7
Userlist::Push.relationships.push(
  user: 'user-1',
  company: 'company-1',
  properties: {
    role: 'owner'
  }
)

This is equivalent to specifying the relationship on the user model.

1
2
3
4
5
6
7
8
9
10
11
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.

1
2
3
4
5
6
7
8
9
10
11
Userlist::Push.companies.push(
  identifier: 'company-1',
  relationships: [
    {
      user: 'user-1',
      properties: {
        role: 'owner'
      }
    }
  ]
)

Tracking Events

To track custom events use the Userlist::Push.events.push method.

1
2
3
4
5
6
7
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.

1
2
3
4
5
6
7
8
9
10
11
12
Userlist::Push.events.push(
  name: 'project_created',
  user: {
    identifier: 'user-1',
    properties: {
      projects: 5
    }
  },
  properties: {
    project_name: 'Example project'
  }
)

Tokens for in-app messages

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.

1
2
Userlist::Token.generate('user-1')
# => "eyJraWQiOiI2dlBrSmw0NGNtODJ5NGFMQkl6YU9odU...kPGe8KX8JZBTQ"

Watch the video demo

Get access to the pre-recorded 10-minute demo, and see how Userlist can help you onboard new users, convert free trials, and manage customers and leads within one tool.