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

Set / increment user attributes directly from your backend

Set / increment user attributes through JavaScript using a Rack Middleware

Install

gem install mixpanel

Rack Middleware

Only needed if you want to track events via Javascript. This setup will allow your backend to have the client browser process the actual
requests over JavaScript rather than sending the request yourself.

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:

By default the Mixpanel JavaScript API library scripts are inserted into the
HTML. If you'd prefer to insert them yourself, set the
insert_mixpanel_scripts flag to false.

insert_js_last : boolean

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, set the insert_js_last flag to true 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, this will have no effect
when inserting JS into an AJAX response.

persist : boolean

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, which can be 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
transmitted 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 the flag twice: here when instantiating Middleware and again when you initialize the Mixpanel class.

Usage

Initialize Mixpanel

@mixpanel=Mixpanel::Tracker.newYOUR_MIXPANEL_API_TOKEN, options

Where options is a hash that accepts the following keys:

async : boolean

Default: false

Built in async feature. Events are sent to a subprocess via a pipe and the sub process asynchronously send events to Mixpanel.
This value can be overwritten on subsequent method calls. I.e., this setting represents the default for your Mixpanel object,
but each call can overwrite this default setting.

This process uses a single thread to upload events, and may start dropping events if your application generates
them at a very high rate. While this is a simple way to have asynchronous interaction with Mixpanel, more robust solutions are
available. Specifically, see the Resque example below.

persist : boolean

Default: false

This is used in connection with the Rack Middleware section above. If you are not going to use Middleware
to send requests to Mixpanel through JavaScript, you don't need to worry about this option.

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, which can be 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
transmitted 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 the flag twice: when instantiating Middleware and here when you initialize
the Mixpanel class.

api_key : string

Default: nil

When using the import functionality, you must set an API key to go along with your token. If not set when the
class is instantiated, you will be required to send the api key in the options hash of the import method.

env : hash

Default: {}

This is used by the gem to append information from your request environment to your Mixpanel request. If you are calling this
directly from a controller, simply passing in request.env will be sufficient. However, as explained in the Resque example,
your environment might choke if it tries to convert that hash to JSON (not to mention how large that hash can be). You can just pass
in a subset of the full environment:

Basically, this information is being used to: set the default IP address associated with the request, and grab any session variables
needed to run the Middleware stuff.

Additional information contained in your environment (e.g., http_referer) can simply be sent in as attributes where appropriate
for your use case.

Track Events Directly

@mixpanel.track event_name, properties, options

event_name is a string denoting how you want this event to appear in your Mixpanel dashboard.

properties is a hash of properties to be associated with the event. The keys in the properties can either be strings
or symbols. If you send in a key that matches a special property,
it will automatically be converted to the correct form (e.g., { :os => 'Mac' } will be converted to { :$os => 'Mac' }).

options is a hash that accepts the following keys:

async : boolean

Default: the async value from when the class was instantiated

api_key: string

Default: the api_key value from when the class was instantiated

url: string

Default: http://api.mixpanel.com/track/

This can be used to proxy Mixpanel API requests.

test: boolean

Default: false

Send data to a high priority rate limited queue to make testing easier

Set Person Attributes Directly

@mixpanel.set distinct_id_or_request_properties, properties, options

distinct_id_or_request_properties is whatever is used to identify the user to Mixpanel or a hash of
properties of the engage event that exist
outside of the $set. Special properties will be automatically converted to the correct form (e.g., { :ip => '127.0.0.1' } will be
converted to { :$ip => '127.0.0.1' }

properties is a hash of properties to be set. The keys in the properties can either be strings
or symbols. If you send in a key that matches a special property,
it will automatically be converted to the correct form (e.g., { :first_name => 'Chris' } will be converted to { :$first_name => 'Chris' }).

Increment Person Attributes Directly

@mixpanel.increment distinct_id, properties, options

All of these options have the same meaning and same defaults as the set method. Note that according to Mixpanel's
docs, you cannot combine set and increment requests, and that is why they are split here.

Example:

@mixpanel.increment 'john-doe', { :tokens => 5, :coins => -4 }

Track Charges for Revenue Directly

@mixpanel.track_charge distinct_id, amount, time, options

This allows you to use the Revenue tab in your mixpanel dashboard.

Example:

@mixpanel.track_charge 'john-doe', 20.00

If you need to remove accidental charges for a person, you can use:

@mixpanel.reset_charges distinct_id

Append Events To Be Tracked With Javascript

Note that you must call mixpanel.identify() in conjunction with People requests like set(). If you make set() requests before
you identify the user, the change will not be immediately sent to Mixpanel. Mixpanel will wait for you to call identify() and then send the accumulated changes.

Prevent middleware from inserting code

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.

How to track events using Resque and Rails

While there is built-in async functionality, other options are more robust (e.g., using a dedicated queue manager). Below is an example of how this
might be done with Resque, but the same concepts would apply no matter what queue manager you use.