• Home
• Integrations
• Ruby on Rails

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

Installation

Add this line to your application's Gemfile:

1
gem 'userlist-rails'

And then execute:

1
$ bundle

Or install it yourself as:

1
$ 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 account.

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

Configuration via environment variables:

1
2
USERLIST_PUSH_KEY=VvB7pjDrv0V2hoaOCeZ5rIiUEPbEhSUN
USERLIST_PUSH_ID=6vPkJl44cm82y4aLBIzaOhuEHJd0Bm7b

Configuration via an initializer:

1
2
3
4
5
# config/initializer/userlist.rb
Userlist.configure do |config|
  config.push_key = 'VvB7pjDrv0V2hoaOCeZ5rIiUEPbEhSUN'
  config.push_id = '6vPkJl44cm82y4aLBIzaOhuEHJd0Bm7b'
end

In addition to the configuration options of the userlist gem, the following options are available.

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 (not to be confused with nil).

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

1
2
3
4
5
6
7
8
9
10
11
12
13
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.users.push method.

1
Userlist::Push.users.push(user)

It's also possible to customize the payload sent to Userlist by passing a hash instead of the user object.

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

Ignoring users

For cases where you don't want to send specific user to Userlist you can add a userlist_push? method. Whenever this method doesn't return a falsey value, this user will not be sent to Userlist. This also applies to any events or relationships this user is involved in.

1
2
3
4
5
class User < ApplicationRecord
  def userlist_push?
    !deleted? && !guest?
  end
end

Deleting users

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

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

Tracking Companies

Sending company data automatically

By default, this gem will automatically detect your company model (like Account, Company, Team, Organization) and create, update, and delete the corresponding company inside of Userlist. To customize the identifier, name, or properties transmitted for a company, you can overwrite the according methods in your company model.

1
2
3
4
5
6
7
8
9
10
11
12
13
class Account < ApplicationRecord
  def userlist_properties
    { projects: projects.count }
  end

  def userlist_identifier
    "account-#{id}"
  end

  def userlist_name
    name
  end
end

Sending company data manually

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

1
Userlist::Push.companies.push(company)

It's also possible to customize the payload sent to Userlist by passing a hash instead of the company object.

1
Userlist::Push.companies.push(identifier: company.id, name: company.name, properties: { projects: company.projects.count })

Ignoring companies

For cases where you don't want to send specific company to Userlist you can add a userlist_push? method. Whenever this method doesn't return a falsey value, this company will not be sent to Userlist. This also applies to any events or relationships this company is involved in.

1
2
3
4
5
class Account < ApplicationRecord
  def userlist_push?
    !deleted? && active_subscription?
  end
end

Deleting companies

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

1
Userlist::Push.companies.delete(company)

Tracking relationships

Userlist supports n:m relationships between users and companies. This gem will try to figure out the model your application uses to describe these relationships by looking at the associations defined in your user and company models. When sending a user to Userlist, this gem will try to automatically include the user's relationships as well. This includes information about the relationships and companies this user is associated with, but not information about other users associated with any of the companies. This works the other way around as well. When sending a company, it'll try to automatically include the company's relationships, but not any information about the associated users' other companies.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
user = User.create(email: 'foo@example.com')
user.companies.create(name: 'Example, Inc.')

Userlist::Push.users.push(user)

# Payload sent to Userlist
{
  identifier: 'user-1',
  email: 'foo@example.com',
  relationships: [
    {
      user: 'user-identifier',
      company: {
        identifier: 'company-identifier',
        name: 'Example, Inc.',
      }
    }
  ]
}

Similar to users and events, these relationships may define a userlist_properties method to provide addition properties that describe the relationship.

1
2
3
4
5
6
7
8
class Membership < ApplicationRecord
  belongs_to :user
  belongs_to :account

  def userlist_properties
    { role: role }
  end
end

Customizing relationship lookup

It's possible to customize the way this gem looks up relationships for users and companies by specifying a userlist_relationships method on the user and/or company model.

1
2
3
4
5
class User < ApplicationRecord
  def userlist_relationships
    memberships.where(role: 'owner')
  end
end

If you don't have a dedicated model describing the relationship, you can return a hash including both the user and the company model.

1
2
3
4
5
6
7
8
9
10
class User < ApplicationRecord
  def userlist_relationships
    [
      {
        user: self,
        company: account
      }
    ]
  end
end

Ignoring relationships

This gem automatically ignores a relationship if either the user or the company is ignored. However, in some cases it might be desirable to ignore relationships even when they connect to valid objects. A typical example for this are pending invitations. To support this use case, you can provide a userlist_push? method. Whenever this method doesn't return a falsey value, this relationship will not be sent to Userlist.

1
2
3
4
5
6
7
8
class Membership < ApplicationRecord
  belongs_to :user
  belongs_to :account

  def userlist_push?
    pending?
  end
end

Deleting relationships

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

1
Userlist::Push.relationships.delete(membership)

Tracking Events

To track custom events use the Userlist::Push.events.push method. Events can be related to a user, a company, or both.

1
Userlist::Push.events.push(name: 'project_created', user: current_user, company: current_account, properties: { project_name: project.name })

Enabling in-app messages

In order to use in-app messages, please set both the push_key and push_id configuration variables. Afterwards, include the userlist_script_tag helper into your application's layout for signed in users.

1
<%= userlist_script_tag %>

By default, the helper will try to use the current_user helper to read the currently signed in user. You can change the default bebahvior by passing a different user. The passed object must respond to the userlist_identifier method.

1
<%= userlist_script_tag(user) %>

Batch importing

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

1
rake userlist:import