Node.js

API Integration

The Mixpanel Node.js library provides Mixpanel tracking functionality in server-side applications built using Node.js.

Use the HTTP tracking API for server-side applications that do not use Node.js.

Additionally, Mixpanel offers client-side libraries for the following platforms:

The Mixpanel client-side libraries support a wide range of convenience features, and should be the starting point for using Mixpanel in client-side implementations.

The Mixpanel Node.js library will be most useful to you if you need to send data from a Node.js server, or for interacting with Mixpanel APIs in JavaScript outside of the browser (such as importing past events with a script).

Installing the Library

Install the Mixpanel Node.js library and create a Mixpanel instance in order to begin Mixpanel tracking.

Use npm to install Mixpanel in your project by calling npm install mixpanel. The Mixpanel module will be available in the Node project after installing the library.

Next, create a Mixpanel instance and initialize a Mixpanel client to communicate with Mixpanel servers. To do this, grab the Mixpanel factory and create an instance of the Mixpanel client by calling mixpanel.init(YOUR_PROJECT_TOKEN).

The project token is unique to your Mixpanel project. Instructions for finding your project token can be found here.

// grab the Mixpanel factory
var Mixpanel = require('mixpanel');

// create an instance of the mixpanel client
var mixpanel = Mixpanel.init('<YOUR_TOKEN>');

EU Data Residency

Route data to Mixpanel's EU servers by setting the host config property.

mixpanel.init(
  "YOUR_TOKEN",
  {
    host: "api-eu.mixpanel.com",
  },
);

Sending Events

You can track events with mixpanel.track() after initializing a Mixpanel instance.

The mixpanel.track() method takes two arguments, an event name and a properties object which must include the distinct_id.

You have the option to add additional event properties to the call to add detail to that event. Read more about events and properties here.

var Mixpanel = require('mixpanel');
var mixpanel = Mixpanel.init('<YOUR_TOKEN>');

// track an event with optional properties
mixpanel.track('event name', {
    distinct_id: 'unique client id',
    property_1: 'value 1',
    property_2: 'value 2',
    property_3: 'value 3'
});

Mixpanel determines default geolocation data ($city, $region, mp_country_code) using the IP address on the incoming request. This can have the unintended effect of setting the location of all of your users to the location of your datacenter in server-side implementations.

It is therefore important to pass IP as a property in server-side implementations. Read about best practices for geolocation with server-side implementations.

var Mixpanel = require('mixpanel');
var mixpanel = Mixpanel.init('<YOUR_TOKEN>');

// track an event with optional properties
mixpanel.track('event name', {
    distinct_id: 'unique client id',
    ip: '127.0.0.1'
});

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.

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:

mixpanel.alias('new_id', 'existing_id');
//You can add multiple id aliases to the existing id
mixpanel.alias('newer_id', 'existing_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, you'll need to take special care if you're using mixpanel.alias() with a custom consumer, so you can be sure that your alias message arrives before any events or updates associated with the new alias.

Storing User Profiles

You can send user profile updates to Mixpanel in addition to sending events.

Mixpanel can maintain a profile of each of your users, storing information you know about them.

A profile update changes the properties of a user profile, essentially changing the details tied to that profile or creating it if it does not exist.

You can use profiles and user profile properties to explore and segment users by who they are, in addition to what they did with event tracking. You can also use profiles to send messages, such as emails, SMS, or push notifications.

Setting Profile Properties

You can update or create a user profile with mixpanel.people.set(). The first argument is distinct_id, and the second argument is a JSON list of the properties to add to or update the profile with.

The following example sets a "Plan" property with a value "Premium", a first name, a last name, and a created date on the user's profile that has a distinct id of 13793.

Mixpanel automatically creates a new profile if there isn't already a profile with a distinct_id of 13793 in the project already.

If the user with a distinct_id of 13793 already has a property named "Plan" in their profile, the new value "Premium" overwrites the old value of "Free".

// grab the Mixpanel factory
var Mixpanel = require('mixpanel');
var mixpanel = Mixpanel.init('<YOUR_TOKEN>');

// create or update a user in Mixpanel
mixpanel.people.set('13793', {
    $first_name: 'Billy',
    $last_name: 'Bob',
    $created: (new Date('jan 1 2013')).toISOString(),
    plan: 'premium',
});

📘

NOTE

Pick your property names wisely. 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 use mixpanel.people.increment() to increment the current value of numeric properties. This is useful when tracking a running count of properties, such as games played, emails sent, or points earned.

// increment a numeric property
mixpanel.people.increment('13793', 'games_played');
// increment a numeric property by a different amount
mixpanel.people.increment('13793', 'points', 15);
// increment multiple properties
mixpanel.people.increment('13793', {'points': 10, 'games_played': 1});

Appending to List Properties

Use mixpanel.people.append() to add an item to an existing list-valued property.

mixpanel.people.append() adds the values passed to it at the end of the list for each named property. Mixpanel creates a list containing one element as its value if the property does not already exist.

// append value to a list
mixpanel.people.append('13793', 'awards', 'Great Player');
// append multiple values to a list
mixpanel.people.append('13793', {'awards': 'Great Player', 'levels_finished': 'Level 4'});

Other Types of Profile Updates

There are a few other types of profile updates. You can get more information about them from the "Quick Start" section of the repository Readme and examples in the library code.

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

Administer group keys through your Project Settings. Group keys are event properties. All events need to have a defined group key on them in order to be attributed to a group. Group keys are project specific, and the group key should be set up before group data is sent. Note that Mixpanel does not backfill historical data before the group key was implemented.

To administer group keys, navigate to your Project Settings. Click +Add Group Key under the GROUP KEYS section.

Enter an event property to attribute the group key to. You can also enter a display name for the group key. Click Save.

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.

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.

// Tracks an event named 'Plan Purchase',
// with group_id = 'Company' and group_key = 'Mixpanel'
mixpanel.track('Plan Purchase', {
    distinct_id: 'unique client id',
    'Plan Type': 'Premium',
    Company: 'Mixpanel',
});

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 group_id = Company,
// group_key = Mixpanel along with name properties.
mixpanel.people.set('13793', {
    $first_name: 'Billy',
    $last_name: 'Bob',
    Company: 'Mixpanel',
});

Creating Group Profiles

You can create a Group profile that is similar to a user profile. You must call groups.set(), groups.set_once() or groups.union() 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.

// Create or update a group profile with group_key = Company,
// group_id = Mixpanel
mixpanel.groups.set('Company', 'Mixpanel', {
  $name: 'Mixpanel',
  Type: 'Analytics',
})

Setting Group Properties

You can add details to Group Profiles by adding properties to them. These operations are similar to the corresponding operations for user profile property updates.

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

set

groups.set() updates or adds properties to a group profile. The profile is created if it does not exist.

// Create or update a group profile with group_key = Company,
// group_id = Mixpanel
mixpanel.groups.set('Company', 'Mixpanel', {
  $name: 'Mixpanel',
  Type: 'Analytics',
  tags: ['high ROI', ':)'],
})

set_once

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.

// Create or update a group profile with group_key = Company,
// group_id = Mixpanel, only setting the properties that are not
// already set.
mixpanel.groups.set_once('Company', 'Mixpanel', {
  Type: 'Analytics',
  HQ: 'San Francisco',
})

unset

groups.unset() unsets a property or properties on the group profile.

// Permanently removes the group profile property "Type"
mixpanel.groups.unset('Company', 'Mixpanel', 'Type')

// Permanently removes the "Type" and "tags" properties
mixpanel.groups.unset('Company', 'Mixpanel', ['Type', 'tags'])

union

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.

// Add the "Features" list property or merge "Insights"
// and "Funnels" into the existing property.
mixpanel.groups.union('Company', 'Mixpanel', {
  Features: ['Insights', 'Funnels'],
})

remove

groups.remove() removes a specific value in a list property.

// Remove "Hardware Repair" from the "Additional Services" list property
mixpanel.groups.remove('Company', 'Mixpanel', {
  'Additional Services': 'Hardware Repair'
})

delete_group

groups.delete_group() permanently deletes a group profile.

// Delete the Mixpanel group profile
mixpanel.groups.delete_group('Company', 'Mixpanel')

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.

You can create a lookup profile that is similar to a user profile. You must call groups.set(), groups.set_once() or groups.union() 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.

Locating a table's group_key

Updating a lookup table

set

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

// Create or update a lookup profile (row) with group_key found in lookup table details page and
// group_id "Gagnam style" (the join key, which is the value for the 1st column)
mixpanel.groups.set('d1b6d2e0-1330-4ad6-b520-d948ede3b1a7', 'Gagnam style', {
  Genre: 'Pop',
})

set_once

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.

// Create or update a lookup profile (row) with group_key found in lookup table details page and
// group_id "Gagnam style" (the join key, which is the value for the 1st column)
mixpanel.groups.set_once('d1b6d2e0-1330-4ad6-b520-d948ede3b1a7', 'Gagnam style', {
  Genre: 'Pop',
})

unset

groups.unset() unsets a property or properties on the lookup profile.

// Permanently removes the profile's "Genre" property
mixpanel.groups.unset('d1b6d2e0-1330-4ad6-b520-d948ede3b1a7', 'Gagnam style', 'Genre')

// Permanently removes the "Genre" and "tags" properties
mixpanel.groups.unset('d1b6d2e0-1330-4ad6-b520-d948ede3b1a7', 'Gagnam style', ['Genre', 'tags'])

union

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.

// Add the "hashtags" list property or merge "spectacular" and "crazy"
// into the existing property.
mixpanel.groups.union('d1b6d2e0-1330-4ad6-b520-d948ede3b1a7', 'Gagnam style', {
  hashtags: ['spectacular', 'crazy'],
})

remove

groups.remove() removes a specific value in a list property.

// Remove "crazy" from the "hashtags" list property
mixpanel.groups.remove('d1b6d2e0-1330-4ad6-b520-d948ede3b1a7', 'Gagnam style', {
  hashtags: 'crazy'
})

delete_group

groups.delete_group() permanently deletes a lookup profile (row).

// Delete the lookup profile (row) with group_key found in lookup table details page and
// group_id "Gagnam style" (the join key, which is the value in the 1st column)
mixpanel.groups.delete_group('d1b6d2e0-1330-4ad6-b520-d948ede3b1a7', 'Gagnam style')

Tracking Revenue

It is possible to track and analyze revenue generated from individual customers.

You can track a single transaction with mixpanel.track_charge(). This call adds transactions to the individual user profile. These values are visible in the Mixpanel Revenue report.

// record a transaction for revenue analytics
mixpanel.people.track_charge('13793', 39.99)

Additional Resources

Visit the Mixpanel-Node repository on GitHub for additional information, such as:

Updated 8 days ago


Node.js


API Integration

Suggested Edits are limited on API Reference Pages

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