mixpanel: A Ruby repository from ketzusaka

[What is Mixpanel] (#what-is-mixpanel)
[What does this Gem do?] (#what-does-this-gem-do)
[Install] (#install)
- [Rack Middleware] (#rack-middleware)
[Usage] (#usage)
- [Initialize Mixpanel class] (#initialize-mixpanel-class)
[Examples] (#examples)
[How to use it from Rails controllers] (#how-to-use-it-from-rails-controllers)
[How to track events using Resque and Rails] (#how-to-track-events-using-resque-and-rails)
[Supported Platforms] (#supported-platforms)
[Deprecation Notes] (#deprecation-notes)
[Collaborators and Maintainers] (#collaborators-and-maintainers)

What is Mixpanel

Mixpanel is a real-time analytics service that helps companies understand how users interact with web applications. http://mixpanel.com

What does this Gem do?

Track events with properties directly from your backend.
Track events with properties through javascript using a rack middleware.

Install

  gem install mixpanel

Rack Middleware

Only need if you want to track events from Javascript.

If you are using Rails you can add this to your specific environment configuration file (located in config/environments/) or create a new initializer for it:

  config.middleware.use "Mixpanel::Tracker::Middleware", "YOUR_MIXPANEL_API_TOKEN", options

Where options is a Hash that accepts the following keys:

insert_js_last : true | false

Default: false. By default the scripts are inserted into the head of the html response. If you'd prefer the scripts to run after all rendering has completed you can set the insert_js_last flag and they'll be added at the end of the body tag. This will work whether or not you opt for the aynchronous version of the API. However, when inserting js into an ajax response it will have no effect.
persist : true | false

Default: false. If you would like, the Mixpanel gem may be configured to store its queue in a Rack session. This allows events to be stored through redirects, helpful if you sign in and redirect but want to associate an event with that action. The mixpanel gem will also remove duplicate events from your queue for information that should only be trasmitted to the API once, such as mixpanel.identify, mixpanel.name_tag, mixpanel.people.set, and mixpanel.register. This allows you to use a before filter to set these variables, redirect, and still have them only transmitted once. To enable persistence, you must set it in both places, Middleware and when you initialize Mixpanel class.
config : a Hash

Default: {}. You can also pass Mixpanel configuration details as seen here (https://mixpanel.com/docs/integration-libraries/javascript-full-api#set_config)

Usage

Initialize Mixpanel class

  @mixpanel = Mixpanel::Tracker.new("YOUR_MIXPANEL_API_TOKEN", request.env, options)

Where options is a Hash that accepts the following keys:

async : true | false

Default: false. Built in async feature. Events are sent to a subprocess via a pipe and the sub process which asynchronously send events to Mixpanel. This process uses a single thread to upload events, and may start dropping events if your application generates them at a very high rate. If you like for a more robust async behavior take a look at Resque example.
url : String

Default: http://api.mixpanel.com/track/?data=. If you are proxying Mixpanel API requests then you can set a custom url and additionally stop the token from being sent by marking it as false if you're going to let the proxy add it. Example: { url: "http://localhost:8000/mixpanelproxy?data=" }.
persist : true | false

Default: false. If you would like, the Mixpanel gem may be configured to store its queue in a Rack session. This allows events to be stored through redirects, helpful if you sign in and redirect but want to associate an event with that action. The mixpanel gem will also remove duplicate events from your queue for information that should only be trasmitted to the API once, such as mixpanel.identify, mixpanel.name_tag, mixpanel.people.set, and mixpanel.register. This allows you to use a before filter to set these variables, redirect, and still have them only transmitted once. To enable persistence, you must set it in both places, Middleware and when you initialize Mixpanel class.

Track events directly.

  @mixpanel.track_event("Sign in", {:some => "property"})

Append events to be tracked with Javascript.

Note: You should setup the Rack Middleware.

  @mixpanel.append_event("Sign in", {:some => "property"})

Execute Javascript API call

Note: You should setup the Rack Middleware.

  @mixpanel.append_api("register", {:some => "property"})
  @mixpanel.append_api("identify", "Unique Identifier")

Prevent middleware from inserting code

Note: Only applies when Rack Middleware is setup.

Occasionally you may need to send a request for HTML that you don't want the middleware to alter. In your AJAX request include the header "SKIP_MIXPANEL_MIDDLEWARE" to prevent the mixpanel code from being inserted.

$.ajax("/path/to/api/endpoint", {
	headers: {"SKIP_MIXPANEL_MIDDLEWARE": true},
	success: function(data) {
		// Process data here
	}
});

Examples

How to use it from Rails controllers?

In your ApplicationController class add a method to instantiate mixpanel.

  before_filter :initialize_mixpanel

  def initialize_mixpanel
    @mixpanel = Mixpanel::Tracker.new("YOUR_MIXPANEL_API_TOKEN", request.env, options)
  end

How to track events using Resque and Rails

If you don't want to use the built in Mixpanel Gem async feature bellow there is an example about how to make async calls using Resque.

Resque is a Redis-backed Ruby library for creating background jobs

    class MixpanelTrackEventJob
      @queue = :slow

      def mixpanel(request_env)
        Mixpanel::Tracker.new(MIXPANEL_TOKEN, request_env)
      end

      def perform(name, params, request_env)
        mixpanel(request_env).track_event(name, params)
      end
    end

    class UsersController < ApplicationController
      def create
        @user = User.new(params[:user])

        if @user.save
          MixpanelTrackEventJob.enqueue("Sign up", {:invited => params[:invited]}, request.env)
          redirect_to user_root_path
        else
          render :new
        end
     end
   end

Supported Ruby Platforms

1.8.7
1.9.2
1.9.3
JRuby 1.8 Mode

Deprecation Notes

This way to initialize Mixpanel gem is not longer allowed.

  Mixpanel.new

Use this instead:

  Mixpanel::Tracker.new

ketzusaka/mixpanel

Table of Contents