JavaScript Full API Reference

mixpanel.init

This function initialize a new instance of the Mixpanel tracking object. All new instances are added to the main mixpanel object as sub properties (such as mixpanel.your_library_name) and also returned by this function. If you wanted to define a second instance on the page you would do it like so:

 mixpanel.init("new token", { your: "config" }, "library_name")

and use it like this:

 mixpanel.library_name.track(...)

Arguments

token
String
Your Mixpanel API token
config
Object
A dictionary of config options to override
name
String
The name for the new mixpanel instance that you want created

mixpanel.push

push() keeps the standard async-array-push behavior around after the lib is loaded. This is only useful for external integrations that do not wish to rely on our convenience methods (created in the snippet). Good example is Optimizely.

Usage:

mixpanel.push(['register', { a: 'b' }]);

Arguments

item
Array
A [function_name, args...] array to be executed

mixpanel.disable

Disable events on the Mixpanel object. If passed no arguments, this function disables tracking of any event. If passed an array of event names, those events will be disabled, but other events will continue to be tracked.

Note: this function doesn't stop regular mixpanel functions from firing such as register and name_tag.

Arguments

events
Array
An array of event names to disable

mixpanel.track

Track an event. This is the most important Mixpanel function and the one you will be using the most.

Usage:

// track an event named "Registered"
mixpanel.track("Registered", {"Gender": "Male", "Age": 21});

For tracking link clicks or form submissions, see mixpanel.track_links or mixpanel.track_forms.

Arguments

event_name
String
The name of the event. This can be anything the user does - "Button Click", "Sign Up", "Item Purchased", etc.
properties
Object
A set of properties to include with the event you're sending. These describe the user who did the event or details about the event itself.
callback
Function
If provided, the callback function will be called after tracking the event.

mixpanel.track_forms

Tracks form submissions. Selector must be a valid query.

Usage:

// track submission for form id "register"
mixpanel.track_forms("#register", "Created Account");

Notes:

This function will wait up to 300 ms for the mixpanel servers to respond, if they have not responded by that time it will head to the link without ensuring that your event has been tracked. To configure this timeout please see the mixpanel.set_config docs below.

If you pass a function in as the properties argument, the function will receive the DOMElement which triggered the event as an argument. You are expected to return an object from the function; any properties defined on this object will be sent to mixpanel as event properties.

Arguments

query
String
A valid DOM query
event_name
String
The name of the event to track
properties
Object or Function
This can be a set of properties, or a function that returns a set of properties after being passed a DOMElement

mixpanel.register

Register a set of super properties, which are included with all events. This will overwrite previous super property values.

Arguments

properties
Object
An associative array of properties to store about the user
days
Number
How many days since the user's last visit to store the super properties

mixpanel.register_once

Register a set of super properties only once. This will not overwrite previous super property values, unlike register().

Notes:

If default_value is specified, current super properties with that value will be overwritten.

Arguments

properties
Object
An associative array of properties to store about the user
default_value
*
Value to override if already set in super properties (ex: "False") Default: "None"
days
Number
How many days since the users last visit to store the super properties

mixpanel.unregister

Delete a super property stored with the current user.

Arguments

property
String
The name of the super property to remove

mixpanel.identify

Identify a user with a unique id. All subsequent actions caused by this user will be tied to this identity. This property is used to track unique visitors. If the method is never called, then unique visitors will be identified by a UUID generated the first time they visit the site.

Note:

You can call this function to overwrite a previously set unique id for the current user. Mixpanel cannot translate between ids at this time, so when you change a users id they will appear to be a new user.

Arguments

unique_id
String
A string that uniquely identifies a user

mixpanel.get_distinct_id

Returns the current distinct id of the user. This is either the id automatically generated by the library or the id that has been passed by a call to mixpanel.identify

mixpanel.alias

Create an alias, which Mixpanel will use to link two distinct_ids going forward (not retroactively). Multiple aliases can map to the same original ID, but not vice-versa. Aliases can also be chained - the following is a valid scenario:

 mixpanel.alias("new_id", "existing_id");
 ...
 mixpanel.alias("newer_id", "new_id");

If the original ID is not passed in, we will use the current distinct_id - probably the auto-generated GUID.

Arguments

alias
String
A unique identifier that you want to use for this user in the future.
original
String
The current identifier being used for this user.

mixpanel.set_config

Update the configuration of a mixpanel library instance.

The default config is:

{
  // super properties span subdomains
  cross_subdomain_cookie:     true

  // super properties cookie name
  cookie_name:                ""

  // super properties cookie expiration (in days)
  cookie_expiration:          365

  // should we track a page view on page load
  track_pageview:             true

  // the amount of time track_links will
  // wait for Mixpanel's servers to respond
  track_links_timeout:        300

  // if this is true, the mixpanel cookie will be deleted,
  // and no user persistence will take place
  disable_cookie:             false

  // if this is true, the mixpanel cookie will be marked as
  // secure, meaning it will only be transmitted over https
  secure_cookie:              false

  // if you set upgrade to be true, the library will check for a
  // cookie from our old js library and import super
  // properties from it, then the old cookie is deleted
  // The upgrade config option only works in the initialization, so
  // make sure you set it when you create the library.
  upgrade:                    false
}

Arguments

config
Object
A dictionary of new configuration values to update

mixpanel.get_config

returns the current config object for the library.

mixpanel.get_property

Returns the value of the super property named property_name. If no such property is set, get_property will return the undefined value.

Arguments

property_name
String
The name of the super property you want to retrieve

mixpanel.people.set

Set properties on a user record.

Usage:

mixpanel.people.set('gender', 'm');

// or set multiple properties at once
mixpanel.people.set({
    'Company': 'Acme',
    'Plan': 'Premium',
    'Upgrade date': new Date()
});
// properties can be strings, integers, dates, or lists

Arguments

prop
Object or String
If a string, this is the name of the property. If an object, this is an associative array of names and values.
to
*
A value to set on the given property name
callback
Function
If provided, the callback will be called after the tracking event

mixpanel.people.set_once

Set properties on a user record, only if they do not yet exist.

Usage:

mixpanel.people.set_once('First Login Date', new Date());

// or set multiple properties at once
mixpanel.people.set_once({
    'First Login Date': new Date(),
    'Starting Plan': 'Premium'
});

// properties can be strings, integers or dates

Arguments

prop
Object or String
If a string, this is the name of the property. If an object, this is an associative array of names and values.
to
*
A value to set on the given property name
callback
Function
If provided, the callback will be called after the tracking event

mixpanel.people.increment

Increment/decrement numeric people analytics properties.

Usage:

mixpanel.people.increment('page_views', 1);

// or, for convenience, if you're just incrementing a counter by 1, you can
// simply do
mixpanel.people.increment('page_views');

// to decrement a counter, pass a negative number
mixpanel.people.increment('credits_left': -1);

// like mixpanel.people.set(), you can increment multiple properties at once:
mixpanel.people.increment({
    counter1: 1,
    counter2: 1
});

Arguments

prop
Object or String
If a string, this is the name of the property. If an object, this is an associative array of names and numeric values.
by
Number
An amount to increment the given property
callback
Function
If provided, the callback will be called after the tracking event

mixpanel.people.append

Append a value to a list-valued people analytics property.

Usage:

// append a value to a list, creating it if needed
mixpanel.people.append('pages_visited', 'homepage');

// like mixpanel.people.set(), you can append multiple properties at once:
mixpanel.people.append({
    list1: 'bob',
    list2: 123
});

Arguments

prop
Object or String
If a string, this is the name of the property. If an object, this is an associative array of names and numeric values.
value
*
An amount to increment the given property
callback
Function
If provided, the callback will be called after the tracking event

mixpanel.people.track_charge

Record that you have charged the current user a certain amount of money. Charges recorded with track_charge will appear in the Mixpanel revenue report.

Usage:

// charge a user $50
mixpanel.people.track_charge(50);

// charge a user $30.50 on the 2nd of january
mixpanel.people.track_charge(30.50, { '$time': new Date('jan 1 2012') });

Arguments

amount
Number
The amount of money charged to the current user
properties
Object
An associative array of properties associated with the charge
callback
Function
If provided, the callback will be called when the server responds

mixpanel.people.clear_charges

Permanently clear all revenue report transactions from the current user's people analytics profile.

Usage:

mixpanel.people.clear_charges();

Arguments

callback
Function
If provided, the callback will be called after the tracking event

mixpanel.people.delete_user

Permanently deletes the current people analytics profile from Mixpanel (using the current distinct_id).

Usage:

// remove the all data you have stored about the current user
mixpanel.people.delete_user();

Document Sections