User trackers
user_trackers is a ruby gem for tracking user's activity on a ruby on rails app using Mixpanel, Intercom, Slack and app's database.
If desired, the gem may track guest users and associate their activity to authenticated users when used with cookies. The gem can be executed using sidekiq or resque.
Installation
Add the following line to your Gemfile:
gem 'user_trackers'
Then run bundle install
Next, run the generator:
rails generate user_trackers:install
The generator will create:
- Configuration files in config/initializers/user_trackers/
- Configuration file config/user_trackers.yml
-
UserEvent
model and associated migration file
After running the generator you need to run the migration associated to UserEvent
rails db:migrate
Editing configuration files
YML file
API Tokens related to Mixpanel, Intercom and Slack may be set considering development, test and production rails environments.
user_trackers.yml provides the following options:
development:
ignore_events: ['ignored_event_name']
# queue_adapter: sidekiq
mixpanel:
token: <%= ENV["DEV_MIXPANEL_TOKEN"] %>
ignore_events: []
intercom:
token: <%= ENV['DEV_INTERCOM_TOKEN'] %>
ignore_events: []
slack:
token: <%= ENV['DEV_SLACK_TOKEN'] %>
activity_channel: <%= ENV['DEV_SLACK_ACTIVITY_CHANNEL'] %>
ignore_events: []
db:
ignore_events: []
production:
ignore_events: ['ignored_event_name']
queue_adapter: resque
mixpanel:
token: <%= ENV["MIXPANEL_TOKEN"] %>
intercom:
token: <%= ENV['INTERCOM_TOKEN'] %>
ignore_events: ['test_event']
slack:
token: <%= ENV['SLACK_TOKEN'] %>
activity_channel: <%= ENV['SLACK_ACTIVITY_CHANNEL'] %>
ignore_events: []
db:
ignore_events: []
test:
ignore_events: ['ignored_event_name']
mixpanel:
token: <%= ENV["TEST_MIXPANEL_TOKEN"] %>
ignore_events: []
intercom:
token: <%= ENV['TEST_INTERCOM_TOKEN'] %>
ignore_events: []
slack:
token: <%= ENV['TEST_SLACK_TOKEN'] %>
activity_channel: <%= ENV['TEST_SLACK_ACTIVITY_CHANNEL'] %>
ignore_events: []
db:
ignore_events: []
You may ignore events per environment or per tracker. For running trackers on a background job, specify a queue_adapter
option with a value of resque
or sidekiq
Configuration files for trackers
config/initializers/user_trackers/ will contain configuration files with blocks for customizing user
and event
attributes according to your app's datamodel. Configuration blocks will have this form:
UserTrackers.configure_mixpanel do |config|
def config.user_attributes(user_id, event_name, event_attributes = {}, anonymous_id)
user = User.find(user_id)
{
'$first_name': user.first_name,
'$last_name': user.last_name,
'$email': user.email,
'$test': 'test_value2'
}
end
def config.event_attributes(user_id, event_name, event_attributes = {}, anonymous_id)
event_attributes
end
end
Usage
You may call UserTrackers.track
in your rails app or use clients related to each of the gem's trackers.
Track method
The track method must be called with a hash as a parameter and may be called with an optional parameter that should be related to rails' session
Example:
UserTrackers.track({
user_id:9,
event_name:'publish_post',
event_attributes:{ title:'Post title', description:'new post'}
},
session
)
You may call the track method with or without a user_id
parameter. An anonymous_id
will be generated in case no user_id
is specified.
If session
is specified then the gem will use cookies to track guest users.
Tracker clients
You may also use the gem calling methods related to Mixpanel, Intercom and Slack gems.
Mixpanel Example:
UserTrackers::MixpanelTracker.client.track('User1', 'A Mixpanel Event')
Intercom Example:
UserTrackers::IntercomTracker.client.users.find(email: "bob@example.com")
Slack Example:
UserTrackers::SlackTracker.client.chat_postMessage(channel: '#general', text: 'Hello World', as_user: true)