The Mixpanel Ruby library is designed to be used for scripting, or in circumstances when a user isn't directly interacting with your application on the web or a mobile device.

Mixpanel also provides a powerful and easy to use client-side JavaScript library for web applications. This library offers platform-specific features and conveniences that can make Mixpanel implementations much simpler, and can scale naturally to an unlimited number of clients. The client-side Javascript library is the preferred way to add Mixpanel to user-facing web applications.

Installing the Library

You can get the library with

$ gem install mixpanel-ruby

Once the mixpanel-ruby gem is installed, you can use the Mixpanel library in your applications with:

require 'mixpanel-ruby'

Sending Events

Mixpanel events are sent using an instance of the Mixpanel::Tracker class.

You can instantiate an instance of Mixpanel::Tracker with a String containing your Mixpanel project token. You can find your project token in the settings dialog of the Mixpanel web application.

Once you have an instance of the tracker, you can track events with by providing a distinct id and a name for your event to the Mixpanel::Tracker#track.

require 'mixpanel-ruby'

tracker = Mixpanel::Tracker.new(PROJECT_TOKEN)

# Tracks an event, 'Sent Message',
# with distinct_id user_id
tracker.track(user_id, 'Sent Message')

# You can also include properties to describe
# the circumstances of the event
tracker.track(user_id, 'Plan Upgraded', {
    'Old Plan' => 'Business',
    'New Plan' => 'Premium'
})

Mixpanel determines default geolocation data ($city, $region, mp_country_code) using the IP address on the incoming request. As all server-side calls will likely originate from the same IP (that is, the IP of your server), this can have the unintended effect of setting the location of all of your users to the location of your datacenter. Read about best practices for geolocation with server-side implementations.

EU Data Residency

Route data to Mixpanel's EU servers by using a custom consumer

require 'mixpanel-ruby'

eu_consumer = Mixpanel::Consumer.new(
    'https://api-eu.mixpanel.com/track',
    'https://api-eu.mixpanel.com/engage',
    'https://api-eu.mixpanel.com/groups',
)
tracker = Mixpanel::Tracker.new(YOUR_PROJECT_TOKEN) do |type, message|
    eu_consumer.send!(type, message)
end

Managing User Identity

Mixpanel groups events sent with different distinct_ids, presenting them in reports as different user event streams. You can connect events with different distinct_ids using alias, identify, or merge, ultimately attributing them to one user.

📘

ID Merge

If a project has ID merge enabled, the $identify event can connect pre- and post-authentication events. If ID merge is not enabled, identify events will not link identities however alias can be used to connect pre and post registration events.

Alias

The alias method creates an alias which Mixpanel will use to remap one distinct_id to another. Multiple aliases can point to the same identifier.

Argument

Type

Description

alias

String
required

A unique identifier that you want to use as an identifier for this user.

distinct_id

String
optional

The current user identifier.

The following is a valid use of alias:

tracker.alias(new_internal_id, original_anonymous_id)
#Create a second alias
mp.alias(new_second_id, original_anonymous_id)

Aliases can also be chained. You cannot point to multiple identifiers.

❗️

ID Merge

If a project does not have ID Merge enabled, the best practice is to call alias once when a unique ID is first created for a user (e.g., when a user first registers for an account).

📘

NOTE

Aliases don't take effect until the alias request hits the Mixpanel server. Because of this, unlike most Mixpanel tracking and update methods, alias sends a synchronous HTTP request directly to Mixpanel whenever it is called, regardless of how you've configured your tracker.

Storing User Profiles

In addition to events, you can send user profile updates to Mixpanel. Mixpanel can maintain a profile of each of your users, storing information you know about them. An update is a message that changes the properties of a user profile.

You can use profiles to explore and segment users by who they are, rather than what they did. You can also use profiles to send messages, such as emails, SMS, or push notifications.

Mixpanel determines default geolocation data ($city, $region, mp_country_code) using the IP address on the incoming request. As all server-side calls will likely originate from the same IP (that is, the IP of your server), this can have the unintended effect of setting the location of all of your users to the location of your datacenter. Read about best practices for geolocation with server-side implementations.

Setting Profile Properties

Instances of Mixpanel::Tracker have a property called people that is an instance of Mixpanel::People. You can use people to send profile updates.

// create or update a profile with First Name, Last Name,
// E-Mail Address, Phone Number, and Favorite Color
// without updating geolocation data or $last_seen
tracker.people.set('12345', {
    '$first_name'       => 'John',
    '$last_name'        => 'Doe',
    '$email'            => '[email protected]',
    '$phone'            => '5555555555',
    'Favorite Color'    => 'red'
}, ip = 0, {'$ignore_time' => 'true'});

This call to Mixpanel::People#set will change the value of properties on user 12345's profile. If there isn't a profile with distinct_id 12345 in Mixpanel already, a new profile will be created. If user 12345 already has has any of these properties set on their profile, the old values will be overwritten with the new ones.

📘

NOTE

Pick your property names wisely. Once you've sent them to Mixpanel, there is no way to change them. Feel free to use capitalization and spaces in between words.
There are a few limitations:

  • Your property names should not begin with $ or mp_. These properties are reserved for special properties sent by Mixpanel.
  • Your property names cannot begin or end with a space as they will automatically be trimmed.
  • Your property names and values cannot be longer than 255 characters. In practice they should be much shorter than that. Property names get cut off by our user interface at about 20 characters.

Click here to see a list of Mixpanel's reserved user profile properties.

Incrementing Numeric Properties

You can change the current value of numeric properties using people.increment. This is useful when you want to keep a running tally of things, such as games played, emails sent, or points earned.

tracker.people.increment('12345', {
   'Logins used' => 1,
   # use a negative number to subtract
   'Logins remaining' => -1,
})

Appending to List Properties

Use people.append to add an item to an existing list-valued property. The values you send with the append will be added to the end of the list for each named property. If the property doesn't exist, it will be created with a one element list as its value.

tracker.people.append('12345', {
    'Favorite Fruits' => 'Apples'
})

Other Types of Profile Updates

There are a few other types of profile updates. They're exposed as members of Mixpanel::People.

Group Analytics

Mixpanel Group Analytics allows behavioral data analysis by selected groups, as opposed to individual users.

Grouping by identifiers other than the distinct_id allows analysis at a company or group level when using Mixpanel analytics. Read this article to learn more about Group Analytics.

A group is identified by the group_key and group_id.

  • group_key is the property that connects event data for Group Analytics.
  • group_id is the identifier for a specific group.

If the property “Company” is chosen for Group Analytics, “Company” is the group_key, and “Mixpanel”, “Company A”, and “13254” are all potential group_id values.

A user can belong to multiple groups. All updates to a group operate on the group_key and group_id.

📘

Add Group Keys

To start tracking groups data, add group keys in project settings. If you don't see group keys in your Project Settings, reach out to the Mixpanel Sales Team to purchase Group Analytics.

Creating a Group Key

See the Implementation section in this article for instructions on how to create a group key in your Project Settings.

Sending Group Identifiers With Events

To send group identifiers with events, send the group_key as a property key and the group_id as the property value. The data type of the group_key property is a list, therefore you can add multiple values for a single user. It is also possible to pass only one value.

Tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
tracker.track("user_id1", “App Open”, {
  ‘GROUP KEY’ => 1234,
})
 
# event will be attributed to multiple groups with IDs 1000, 1234
tracker.track(“user_id1”, “App Open”, {
  ‘GROUP KEY’ => [1000, 1234],
})

Mixpanel can group events by the group_id, similar to how events are grouped with the distinct_id. A group_id, however, is a group level identifier and not a user level identifier like the distinct_id.

Note that sending in a group_key and group_id as event properties does not add users to the group profile or assign group membership to the user's profile. Only events with your chosen group_key property set will be available for behavioral analysis at the group level. See the sections following the code example to learn how to add users to a group profile or add a group to the user's profile.

Adding Group Identifiers to Individual Users

To connect group information to a user profile, include the group_key and group_id by sending the property as part of the people_set call.

# Create or update a user profile with distinct_id "user_id1", a $name property,
# and group_key = 'Company', group_id = 'Mixpanel'
tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
tracker.people.set("user_id1", {
  '$name' => 'Steph Curry',
  ‘Company’ => 'Mixpanel',
})

Creating Group Profiles

It is possible to create a Group profile that is similar to a user profile. You must call a property-setting method like Mixpanel::Groups#set (described below) to create a group profile. It is important to include the group_key, group_id, and at least one property so that the profile is not empty.

Setting Group Properties

You can add details to Group Profiles by adding properties to them.

You can set the property $name to populate the name field at the top of the group profile.

These operations are similar to the corresponding operations for user profile property updates.

set

Mixpanel::Groups#set updates or adds properties to a group profile. The profile is created if it does not exist.

# Sets properties on a group profile. Takes a Hash with string
# keys, and values that are strings, numbers, booleans, or DateTimes
tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
# Sets properties on group profile with group_key "Company", group_id "Acme"
tracker.groups.set('Company', 'Acme', {
  '$name' => 'Acme, Inc.',
  'plan' => 'Premium',
  'Sign-Up Date' => DateTime.now
})

set once

Mixpanel::Groups#set_once adds properties to a group profile only if the property is not already set. The profile is created if it does not exist.

# set_once works just like #set, but will only change the
# value of properties if they are not already present
# in the group. That means you can call set_once many times
# without changing an original value.
 
tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
tracker.groups.set_once('Company', 'Acme', {
  'First Login Date': DateTime.now
});

unset

Mixpanel::Groups#unset unsets properties on the group profile.

# Removes properties and their values from a group profile.
tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
# removes a single property and its value from a group profile.
tracker.groups.unset('Company', 'Acme', 'Overdue Since')

# removes multiple properties and their values from a group profile.
tracker.groups.unset('Company', 'Acme', ['Overdue Since', 'Paid Date'])

union

Mixpanel::Groups#union adds the specified values to a list property and ensures that those values only appear once. The profile is created if it does not exist.

# Set union on list valued properties.
# Associates a list containing all elements of a given list,
# and all elements currently in a list associated with the given
# property. After a union, every element in the list associated
# with a property will be unique.
tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
tracker.groups.union('Company', 'Acme', {
  'Levels Completed' => ['Suffragette City']
})

remove

Mixpanel::Groups#remove removes a specific value in a list property.

# Removes a specific value in a list property
tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
# removes "socks" from the "Items purchased" list property
# for the specified group
tracker.groups.remove('Company', 'Acme', { 'Items purchased' => 'socks' })

delete

Mixpanel::Groups#delete permanently deletes a group profile.

tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
tracker.groups.delete('Company', 'Acme')

Lookup tables

You can use lookup tables to enrich existing event and profile properties. While you've had the ability to upload CSV to update the lookup tables, we now support programmatic access to do the same. Updating lookup tables follows the same process as updating group profile properties.

It is possible to create a lookup profile that is similar to a user profile. You must call a property-setting method like Mixpanel::Groups#set to create a lookup profile (row). It is important to include the group_key, group_id, and at least one property so that the profile is not empty.

To learn more about the concepts behind lookup tables, and to see how each of the IDs map to the lookup table entities, please read this.

How to find the group_key?

Updating a lookup table

set

Mixpanel::Groups#set updates or adds properties to a lookup profile (row). The profile is created if it does not exist.

# Create a lookup table profile (row) with group_key (found in lookup table details page)
# and group_id (join key value in 1st column of table).
tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
tracker.groups.set('d1b6d2e0-1330-4ad6-b520-d948ede3b1a7', 'Gangnam style', {
  'Genre' => 'Pop',
})

set once

Mixpanel::Groups#set_once adds properties to a lookup profile only if the property is not already set. The profile is created if it does not exist.

# set_once works just like #set, but will only change the
# value of properties if they are not already present
# in the lookup profile. That means you can call set_once many times
# without changing an original value.
 
tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
tracker.groups.set_once('d1b6d2e0-1330-4ad6-b520-d948ede3b1a7', 'Gangnam style', {
  'First Played': DateTime.now
});

unset

Mixpanel::Groups#unset unsets properties on the lookup profile.

# Removes properties and their values from a lookup profile.
tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
# removes a single property and its value from a lookup profile
tracker.groups.unset(
  'd1b6d2e0-1330-4ad6-b520-d948ede3b1a7',
  'Gangnam style',
  'Genre'
)

# removes multiple properties and their values from a lookup profile
tracker.groups.unset(
  'd1b6d2e0-1330-4ad6-b520-d948ede3b1a7',
  'Gangnam style',
  ['Genre', 'First Played']
)

union

Mixpanel::Groups#union adds the specified values to a list property and ensures that those values only appear once. The profile is created if it does not exist.

# Set union on list valued properties.
# Associates a list containing all elements of a given list,
# and all elements currently in a list associated with the given
# property. After a union, every element in the list associated
# with a property will be unique.
tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
tracker.groups.union('d1b6d2e0-1330-4ad6-b520-d948ede3b1a7', 'Gangnam style', {
  'hashtags' => ['spectacular', 'crazy']
})

remove

Mixpanel::Groups#remove removes a specific value in a list property.

# Removes a specific value in a list property
tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
tracker.groups.remove('d1b6d2e0-1330-4ad6-b520-d948ede3b1a7', 'Gangnam style', {
  'hashtags' => 'amazing'
})

delete

Mixpanel::Groups#delete permanently deletes a lookup profile (row).

tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
tracker.groups.delete('d1b6d2e0-1330-4ad6-b520-d948ede3b1a7', 'Gangnam style')

Tracking Revenue

Mixpanel makes it easy to analyze the revenue you make from individual customers. By associating charges with user profiles, you can compare revenue across different customer segments and calculate things like lifetime value.

You can track a single transaction with the track_charge method of Mixpanel::Tracker#people. Sending a message created with track_charge will add transactions to the individual user profile, which will also be reflected in the Mixpanel Revenue report.

# Records a charge of $9.99 from user '12345'
tracker.people.track_charge('12345', 9.99)

# records a charge of $30.50 on the 2nd of January
mixpanel.people.track_charge("12345", 30.50, {
    '$time' => DateTime.parse("Jan 2 2013"),
})

Scaling your Server-Side Tracking

By default, Mixpanel::Tracker sends a request to Mixpanel immediately for every tracking message or profile update. This is convenient for getting started quickly, but almost all server-side use of the Mixpanel library will eventually want to do the IO associated with tracking in a separate thread or process from the events being tracked.

The Mixpanel library provides two mechanisms for separating your tracking from your IO; The Mixpanel::Tracker block constructor and the Mixpanel::Consumer class.

Using Blocks with Mixpanel::Tracker.new

In addition to your token, Mixpanel::Tracker::new takes an optional block. A block is given, when you call Mixpanel::Tracker#track or any of the profile update methods on Mixpanel::Tracker#people, the tracker will call your block instead of sending data directly to Mixpanel.

You can use the code in your block to send the data to a separate process, add it to a queue, or write it to a log.

tracker_log = open("MIXPANEL_LOG.txt", "w+")

# Tracker blocks take two arguments-
# a type (either :event or :profile_update)
# and a message (a JSON string containing
# your Mixpanel message, suitable for
# sending to Mixpanel)

tracker = Mixpanel::Tracker.new(YOUR_TOKEN) do |type, message|
    tracker_log.write([ type, message ].to_json + "\n")
end

Using Mixpanel::Consumer

The Mixpanel library also offers classes to send the messages you record. You can use Mixpanel::Consumer to send messages to Mixpanel.

mixpanel = Mixpanel::Consumer.new
open("MIXPANEL_LOG.txt", "r+") do |log|
    log.each_line do |line|
        type, message = JSON.load(line)
        # Each call communicates with Mixpanel
        mixpanel.send!(type, message)
    end
end

The combination of a block passed to Mixpanel::Tracker::new and a Mixpanel::Consumer makes it simple to use the Mixpanel library with a queueing system. For example:

# In your time-sensitive process
tracker = Mixpanel::Tracker.new(YOUR_TOKEN) do |type, message|
    @queue.set('mixpanel_queue', [ type, message ].to_json)
end

# Track just like you would in any other situation
tracker.track(user_id, 'Sent Message')
tracker.people.increment(user_id, {
    'Messages Sent' => 1
})

# In a worker process on another machine
mixpanel = Mixpanel::Consumer.new
loop do
    job = @queue.get('mixpanel_queue')
    mixpanel.send!(*JSON.load(job))
end

Updated 3 months ago


Ruby


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.