Mixpal

As the JavaScript library is Mixpanel's preferred method of usage, Mixpal aims to make it easier to work with from your Rails backend. Most notably it persists tracking data across redirects, perfect for handling events like user sign ups or form submissions.

First make sure you follow the instructions for installing Mixpanel's JS library:

https://mixpanel.com/help/reference/javascript

1. Add to Gemfile: gem "mixpal"
2. $ bundle

$ gem install mixpal

class ApplicationController < ActionController::Base
  include Mixpal::Integration
  mixpanel_identity :current_user, :email
end

mixpanel_identity tells Mixpal how to identify your users. This is used to alias and identify with Mixpanel. The first arg should be a method on this controller that returns an object to which we can send the second arg. In this example, we'll identify our user by current_user.email.

<%= mixpanel.render() %>

Mixpal exposes its helpers to your controllers, views, and view helpers.

mixpanel.track "Event Name", property_1: "A string", property_2: true

When a new user signs up, you want to create their profile on Mixpanel as well as alias all event data to their identifier. As per Mixpanel's docs, you should only do this once per user.

mixpanel.register_user user.attributes.slice("name", "email")

register_user will attempt to identify and convert the following properties to Mixpanel "special properties": name, email, and created_at.

When a user changes their profile...

mixpanel.update_user email: "mynewemail@example.com"

As with register_user, this method will also identify "special properties".

Mixpal allows you to define custom mixpal methods to use in your controllers/views

1. create a custom module and define your mixpal events

module YourCustomEventsModule
  def sign_up(user)
    register_user user.attributes.slice('name', 'email')
    track 'User signed up'
  end
end

2. create a mixpal.rb initializer and configure mixpal to use your module

Mixpal.configure do |config|
  config.helper_module = YourCustomEventsModule
end

3. use in controllers/views

class UserController < ActionController::Base
  def create
    # ... do cool stuff ...
    mixpal.sign_up(user)
    redirect_to root_path
  end
end

Mixpal stores any tracked events or user data in the session when it detects a redirect so it can output the appropriate Mixpanel JS integration code to the client on the following render. This enables us to do cool things like:

class UsersController < ActionController::Base
  def create
    # ... do cool stuff ...
    mixpanel.register_user name: @user.name, email: @user.email
    redirect_to root_path
  end

  def update
    # ... more cool stuff! ...

    mixpanel.update_user name: @user.name
    mixpanel.track "Profile Updated"

    redirect_to root_path
  end
end

When using Rails' default ActionDispatch::Session::CookieStore, a 4K cookie size limit is enforced. This cookie is shared by anything using the session. If you anticipate tracking many events or large data sets to Mixpal, consider a different session store.

1. Fork it
2. Create your feature branch (git checkout -b feature/my-new-feature)
3. Make your changes
4. Add accompanying tests
5. Commit your changes (git commit -am 'Add some feature')
6. Push to the branch (git push origin feature/my-new-feature)
7. Create new Pull Request

Bump lib/mixpal/version.rb then build + release with docker-compose. If you prefer local development, inspect the Dockerfile to get your local env built.

docker-compose build \
  --build-arg USER_ID=$(id -u) \
  --build-arg GROUP_ID=$(id -g)
docker-compose run gem rake release