Mixpanel Destination

Mixpanel is a powerful, self-serve product analytics solution for your web and mobile apps. By analyzing the actions your users perform, you can unlock valuable customer insights to drive retention, engagement, and conversion.

Find the open source transformer code for this destination in the GitHub repository.

Getting started

RudderStack supports sending event data to Mixpanel via the following connection modes:

In a web device mode integration, that is, using JavaScript SDK as a source, the Mixpanel native SDK is loaded from https://cdn.mxpnl.com/ domain. Based on your website’s content security policy, you might need to allowlist this domain to load the Mixpanel SDK successfully.

Once you have confirmed that the source platform supports sending events to Mixpanel, follow these steps:

1. From your RudderStack dashboard, add a source. Then, from the list of destinations, select Mixpanel.
2. Assign a name to the destination and click Continue.

Connection settings

To successfully configure Mixpanel as a destination, you will need to configure the following settings:

• API Token: Enter your Mixpanel API Token.
• API Secret: Enter your Mixpanel API secret. For more information on obtaining the Mixpanel API Token and API Secret (also called Project Secret), see Mixpanel Help Center.

Mixpanel will deprecate the Project Secret authentication method soon. It is highly recommended to use Service Accounts for authenticating your Mixpanel project. For more information, see Mixpanel API reference.

• Service Account Username: Enter your Mixpanel service account username.
• Service Account Secret: Enter the secret associated with your service account.

For more information on setting up your Mixpanel service account and getting the username and secret, see Mixpanel Help Center.

• Project ID: Enter your Mixpanel project ID.

For more information on getting your Mixpanel project ID, see Mixpanel Help Center.

• Data Residency: Select the relevant option among US and EU. RudderStack will send your event data to the Mixpanel server in that region.
• Identity Merge: Select either Original ID Merge or Simplified ID Merge from the dropdown to track user journeys across devices. For more information on the differences between these APIs, see the Mixpanel documentation.

If you select the Simplified ID Merge option, make sure to turn on the Simplified ID Merge API for your project before sending the events.

• User Deletion: Select the deletion API from the following options which RudderStack uses to delete the user profile in Mixpanel:
  • Delete Profile: RudderStack deletes the user profile in Mixpanel but not the event data associated with it. For more information, see the Mixpanel documentation.
  • Delete Profile and Associated Events: RudderStack deletes the user profile along with the associated data in Mixpanel. Note that it can take up to 60 days for the deletion to come into effect. For more information, see the Mixpanel documentation.
    • GDPR API Token: If you select Delete Profile and Associated Events for user deletion, enter the GDPR OAuth token. For more information on generating this token, see the Mixpanel documentation.
• Strict Mode: If turned on, Mixpanel validates the requests and returns errors for each failed event. See Mixpanel Import Events API for more information.
• Ignore “Do Not Track”: If turned on, the native Mixpanel SDK ignores the “Do Not Track” setting of your web browser. This setting is applicable when sending events in web device mode.

The Mixpanel SDK cannot send events if Send a 'Do Not Track' request with your browsing traffic setting is turned on in Chrome browsers.

Device mode settings

The following settings are applicable if you are sending events to Mixpanel via web device mode:

• Use Mixpanel People: This option sends all your identify calls to Mixpanel People. For more information, see the Mixpanel People section below.
• Automatically set all Traits as Super Properties and People properties: When you turn on this setting, RudderStack sets all the identify traits as super properties and people properties if Use Mixpanel People setting is turned on. See Setting People Properties and Super Properties section for more information.
• Events to increment in People: See the Incrementing events in Mixpanel People section below for more information on this field.
• Properties to increment in People: See the Incrementing properties in Mixpanel People section below for more information on this field.
• Page Tracking Options: For device mode, RudderStack offers the following three settings for sending the page calls to Mixpanel. See the Page web device mode settings section for more information on these options.
  • Track All Pages to Mixpanel with a Consolidated Event Name
  • Track Categorized Pages to Mixpanel
  • Track Named Pages to Mixpanel
• Source Name: If specified, RudderStack sends this source name to Mixpanel for every event/page/screen call.
• Cross Subdomain Cookie: This option lets you persist the Mixpanel cookie between different pages of your application.
• Persistence Type: This option lets you choose the persistence storage method for your Mixpanel cookies. RudderStack provides the following options:
  • None: Mixpanel will not persist the cookie.
  • Cookie: Mixpanel persists the cookie in the browser’s cookie storage.
  • Local Storage: Mixpanel persists the cookie in local storage.
• Persistence Name: Specify a name for the Mixpanel cookie. RudderStack adds it as a suffix for the Mixpanel cookie name.
• Secure Cookie: Enabling this option will mark the Mixpanel cookie as secure, i.e., it will only transmit over HTTPS.
• Group Key Settings: RudderStack sends the group calls to Mixpanel only if one or more group keys are specified here. These group keys act as the group identifiers in Mixpanel. For more information, see the Group Key section below.
• Client-side Events Filtering: See the Client-side Event Filtering guide for more information on this feature.

The following event mapping setting is applicable only if you are sending events to Mixpanel via cloud mode:

• Use New Mapping: This option is disabled by default and sends the first name and last name as:

  $firstName : "John"
$lastName : "Keener"

  If this option is turned on, RudderStack maps these fields to Mixpanel in the following way :

  $first_name : "John"
$last_name : "Keener"

RudderStack lets you pass empty and null values for the properties sent to Mixpanel.

Identify

You can use the identify call to create or update a user in Mixpanel.

Mixpanel needs an identifier to uniquely identify a user. If you pass userId and anonymousId along with the Mixpanel API Secret (in the dashboard settings), then RudderStack first makes an identify call to Mixpanel using the userId and the traits. RudderStack then passes the userId and anonymousId via Mixpanel’s Merge Identities feature, so that the two identifiers are glued to a single user profile.

Note that:

• When sending events via cloud mode, you can only create a new user in Mixpanel using identify events if you have selected the Simplified ID Merge dashboard setting. To perform identity merging, you need to use the track or page/screen calls.
• When sending events to Mixpanel with Simplified ID Merge via cloud and device mode, you need to pass deviceId generated by the Mixpanel SDK as anonymousId in the RudderStack server-side calls to merge two profiles together successfully. For more information, see Mixpanel User Profiles documentation.

A sample identify call is as shown:

rudderanalytics.identify("12345", {
  firstname: "Alex",
  city: "New Orleans",
  country: "USA",
  phone: "8005550100",
  email: "alex@example.com"
})

When sending events via cloud mode, you can prevent the $last_seen attribute getting updated with incorrect times by setting active to false in the context object, as shown in the following snippet:

rudderanalytics.identify("12345", {
  firstname: "Alex",
  city: "New Orleans",
  country: "USA"
}, {
  context: {
    active: false
  }
})

Setting active to false sets Mixpanel’s $ignore_time attribute to true. This way, you can bypass the “Last Seen” date property.

Setting traits as People Properties and Super Properties

This feature is available in web device mode only.

If Use Mixpanel People option is toggled on in the dashboard, you can set the identify traits as both Super Properties and People Properties. To do so, turn on the Automatically set all Traits as Super Properties and People Properties option in the dashboard settings.

You can also choose to filter your reports by both People Properties and Super Properties. This gives you better control over what traits you can set as a Super Property or People Property. To do this:

1. Disable the Automatically set all Traits as Super Properties and People Properties option in the dashboard.
2. Add the traits that you want to send to Mixpanel as Super Properties or People Properties in the Properties to send as Super Properties and Traits to set as People Properties fields respectively:

RudderStack will send all Mixpanel special traits as People Properties. Hence, you can only add the properties that are not in this list.

Properties to set only once

RudderStack lets you set the identify traits as Mixpanel properties whose values you do not want to change at the user profile level, that is, Mixpanel will not overwrite the existing property values. See Mixpanel documentation for more information on this feature.

To use this feature:

1. Enable the Automatically set all Traits as Super Properties and People Properties option in the dashboard. This is required when sending events in web device mode.
2. Add the traits in the Properties to set only once setting.

RudderStack expects the traits specified in the above field to be present in the following object within the identify event:

• Web device mode: context.traits
• Cloud mode: message.traits or message.context.traits (message.traits has higher precedence)

For example, if your identify event sent in cloud mode contains the following and you specify address.city in the Properties to set only once field:

"traits": {
  "address": {
    "city": "London"
  }
}

...

"context": {
  "traits": {
    "address": {
      "city": "Berlin"
    }
  }
}

Then, RudderStack maps city as London as the traits object gets precedence over context.traits.

Reserved Mixpanel properties

Mixpanel has some reserved properties:

• $first_name
• $last_name
• $name
• $username
• $created
• $email
• $phone
• $avatar
• $city
• $country_code
• $region
• $unsubscribed

You should not create custom properties that begin with a $ sign.

Mixpanel People

Currently, RudderStack supports this feature only for web device mode.

RudderStack does not send data to Mixpanel People by default, as it usually requires you to upgrade your Mixpanel account. If you want to use this feature, you can turn on the Use Mixpanel People option in the RudderStack dashboard.

You can identify the user traits without the userId if you wish to add the people properties in Mixpanel before knowing the userId. To do so, see the following snippet:

rudderanalytics.identify({
  email: 'alex@example.com',
  name: 'Alex Keener'
})

Deleting a user

You can delete a user in Mixpanel using the Suppression with Delete regulation of RudderStack’s User Suppression API.

To delete a user, you must specify their userId in the event. Additionally, you can specify a custom identifier (optional) in the event.

A sample regulation request body for deleting a user in Mixpanel is shown below:

{
  "regulationType": "suppress_with_delete",
  "destinationIds": [
    "2FIKkByqn37FhzczP23eZmURciA"
  ],
  "users": [{
    "userId": "1hKOmRA4GRlm",
    "<customKey>": "<customValue>"
  }]
}

RudderStack internally uses the deletion API specified in the User Deletion dashboard setting. For more information on these deletion APIs, see Connection settings.

To see the deletion requests created by RudderStack using the Delete Profile and Associated Events option, log in to your Mixpanel dashboard and navigate to Organization Settings > Data & Privacy.

Deletion requests created using the Delete Profile API are not shown in this dashboard.

Track

To track user events, use the track method with the event name and the associated properties.

When you select Simplified ID Merge in the Identity Merge dashboard setting, RudderStack sets the event’s userId and anonymousId using Mixpanel’s Simplified ID Merge API so that the two identifiers are glued to a single user profile.

A sample track call is as shown:

rudderanalytics.track("track event", {
    test_prop1: 50,
    test_prop2: "prop_value"
});

Tracking revenue

Mixpanel lets you track revenue events. If you send revenue as a property in your track event, RudderStack tracks it as a revenue event.

Revenue tracking is done with a distinct_id (userId that you provide in your identify call; if userId is not present then it will be associated with an anonymousId.)

A sample revenue track call is as shown:

rudderanalytics.track("Purchase", {
  revenue: 100,
  currency: "USD"
});

Tracking charge

If Use Mixpanel People setting is toggled on in your RudderStack dashboard and you include revenue as an event property, RudderStack will track a charge for the current user.

Page

RudderStack passes all page properties that you provide via the page call to Mixpanel, along with the other default properties. It sets the event name as Page for a page call and Screen for a screen call.

When you select Simplified ID Merge in the Identity Merge dashboard setting, RudderStack sets the event’s userId and anonymousId using Mixpanel’s Simplified ID Merge API so that the two identifiers are glued to a single user profile.

A sample page call is shown below:

rudderanalytics.page();

Page web device mode settings

RudderStack will send 1 event to Mixpanel per page call.

For device mode, RudderStack offers the following three options for page calls:

• Track All Pages with a Consolidated Event Name: This setting is on by default. RudderStack sends all page and screen calls with the name Loaded a Page with the corresponding properties of the call. This lets you leverage Mixpanel’s reporting capabilities for page/screen analytics in the best possible way.
• Track Categorized Pages to Mixpanel: RudderStack tracks the categorized pages to Mixpanel. If you turn on this setting in the dashboard, RudderStack sends a Viewed [<category>] Page event to Mixpanel. If the page name is also present in the event, then RudderStack sends a Viewed [<category> <page_name>] Page event.
• Track Named Pages to Mixpanel: RudderStack also tracks the named pages to Mixpanel. If you turn on this setting in the dashboard, RudderStack will send a Viewed [page_name] Page event. Note that this option has the least precedence and comes to effect only if the above two options are disabled in the RudderStack dashboard.

RudderStack gives the highest precedence to the Track All Pages with a Consolidated Event Name option even if Track Categorized Pages to Mixpanel and Track Named Pages to Mixpanel are turned on in the dashboard.

RudderStack expects atleast one of the three options listed above to be toggled on for sending the page events to Mixpanel using device mode.

Screen

The screen method lets you record whenever a user sees their mobile screen along with any optional properties about the viewed screen.

A sample screen call is shown below:

[[RSClient sharedInstance] screen:@"Sample Screen Name" properties:@{@"prop_key" : @"prop_value"}];

Alias

The alias call lets you associate multiple identities of a known user.

The alias call is deprecated with the Simplified ID Merge dashboard setting.

A sample alias call is as shown:

analytics.alias('userId', `previousId`);

Group

The group call lets you link an identified user with a group such as a company, organization, or an account, and record any traits associated with that group, for example, company name, number of employees, etc. For more information on how the group call works in Mixpanel, see Mixpanel’s Group Analytics documentation.

RudderStack lets you record the custom traits associated with a user group and send this information to Mixpanel.

A sample group call is shown below:

rudderanalytics.group(
  "sample_group_id", {
    name: "Tech group",
    industry: "Technology",
    employees: 100,
  }
);

Group Key

You can create group keys in the Mixpanel project settings, which act as the group identifiers in Mixpanel. To successfully send a group call to Mixpanel, you must specify at least one group key in the Group Key RudderStack dashboard setting:

Note the following points:

• If you map the groupId as a group key, RudderStack looks up its value in the following priority order:
  1. In message.groupId
  2. In message.traits.groupId
• If you map any other field as a group key, RudderStack looks up its value in message.traits.groupKey.
• You can specify multiple values for a group key and send them in an array in the group event payload.

Sending historic events

Mixpanel supports importing historical event data. However, note that the event timestamp should be within the last 5 years. Mixpanel rejects any data older than this duration. To send historic events, provide the timestamp in the timestamp field of the message. RudderStack will then send the event with the same timestamp to Mixpanel.

Mapping RudderStack properties to Mixpanel properties

RudderStack maps the following properties to the Mixpanel properties before sending them over Mixpanel’s HTTP API.

RudderStack maps these fields only in the identify requests.

Mixpanel special traits

The following table lists all properties that RudderStack sends to Mixpanel as special traits:

Incrementing events in Mixpanel People

To increment event counts in Mixpanel People, you can add the events in the Events to increment in People field.

This feature is available in web device mode only.

For each event name added, RudderStack automatically calls Mixpanel and sets a user trait as Last + <event_name>. For example, if you add Logged In to the list of increment events, RudderStack will increment a user trait called Logged In and set a trait called Last Logged In with the current date and time.

Increment works for known users only. If you make a track call, you must identify your user first.

Incrementing properties in Mixpanel People

To increment properties in Mixpanel People, you can add them in the Properties to Increment in People field. RudderStack will call Mixpanel’s increment when you attach a number to the specified property. For example, 'items purchased': 5.

Send UTM parameters to Mixpanel

This section is applicable for track, page, and screen events.

RudderStack maps the following keys (derived from the event’s context.campaign object) to the Mixpanel standard UTM parameters:

Any contextual fields apart from the ones mentioned above are sent as utm_{key} to Mixpanel. An example is shown below:

{
  "context": {
    "campaign": {
      "name": "test_name",
      "source": "test_source",
      "medium": "test_mediun",
      "content": "test_content",
      "term": "test_term",
      "keyword": "test_keyword"
    }
  }
}

utm_campaign
utm_source
utm_medium
utm_content
utm_term
utm_keyword

In the above example, RudderStack sends utm_keyword as a custom UTM parameter to Mixpanel.

FAQ

Can I pass null and empty values for the properties?

Yes, RudderStack supports passing empty or null values for the properties sent to Mixpanel.

Why am I getting the ‘Request Header Fields Too Large’ error?

Mixpanel imposes certain limitations on its API requests such as:

• Any GET request URL above 19K characters (around 19 KB+) is blocked.
• The header size more than 15KB is not allowed.
• The body of the request more than 20MB is not allowed.
• Each event can have up to 255 event properties.

If your requests are larger than the above-mentioned limits, you will get a ‘Request Header Fields Too Large’ error.

See Mixpanel’s Community FAQ for more information.

Questions? Contact us by email or on Slack