Segment makes it easy to send your data to Mixpanel (and lots of other destinations). Once you've tracked your data through our open source libraries we'll translate and route your data to Mixpanel in the format they understand. Learn more about how to use Mixpanel with Segment.

Our Mixpanel destination code is open sourced on Github. Feel free to check it out:

Getting Started

When you toggle on Mixpanel in Segment, this is what happens:

• Our CDN is updated within 5-10 minutes. Then our snippet will start asynchronously loading mixpanel.js onto your page. This means you should remove Mixpanel’s snippet.
• Since Mixpanel only records custom events and custom user data, no events or users will appear in Mixpanel until you start using the API outlined below.
• Any iOS and Android apps running our mobile sources will start sending data to Mixpanel. New settings will take up to an hour to propagate to all of your existing users. Or if you just added the iOS or Android library to your app code, it’ll be instantaneous!

Page

Page calls are transformed to Mixpanel Track events by the default ON: “Track All Pages to Mixpanel with a Consolidated Event Name” Mixpanel destination settings. This will send all page

If you want to track the page or screen calls to Mixpanel with the name or category in the event name, we offer three more options for sending page/screen calls.

Note: Beginning with Consolidate Page calls, the following options are each mutually exclusive. See the code for details

• 0) [default] Track All Pages to Mixpanel with a Consolidated Event Name
• 1) Track all Pages to Mixpanel
• 2) Track Categorized Pages to Mixpanel [default]
• 3) Track Named Pages to Mixpanel [default]

If you select Track all Pages to Mixpanel, all page calls regardless of how you have customized it will send a Loaded A Page. Even if you have the other options enabled, we will only send this call to prevent double counting your pageviews.

If you select Track Categorized Pages to Mixpanel, we will send a Viewed [category] Page event.

If you select Track Named Pages to Mixpanel, we will send a Viewed [name] Page event.

Note: If both option 2 and 3 are enabled, we will give precedence to category. If you pass both category and name, (e.g. analytics.page('category', 'name');), we will send a Viewed category name Page to Mixpanel.

In summary, Segment will only send 1 event to Mixpanel per page call.

Identify

The first thing you’ll want to do is to identify your users so Mixpanel knows who they are. You’ll use the identify method to accomplish this.

identify takes the unique userId of a user and any traits you know about them.

Client Side

When you call identify from the client in either a browser via Analytics.js or one of our mobile SDKs a bunch of things happen:

We start by recognizing and translating our special traits so that they fit the expectations of Mixpanel’s API. The table below shows the mappings. You’ll pass the key on the left into Segment and we will transform it to the key on the right before sending to Mixpanel.

Register Super Properties

By default, each trait (i.e. properties in an identify call) is registered as a super property. This does not require passing a userId in the identify call. You can pass a traits object by itself and it will still register the traits as super properties.

We also allow you to disable the default behavior and register super properties explicitly by unchecking Set All Traits as Super Properties or People Properties By Default and explicitly specifying in the traits or properties you want us to register as super properties in Segment’s Mixpanel destination panel. Check out the documentation here

Set People Properties

If you’ve enabled Mixpanel People in your Segment settings, we also call Mixpanel’s people.set with the same traits object. There’s no need for an additional API call to populate Mixpanel People.

We also allow you to disable the default behavior and set people properties explicitly by unchecking Set All Traits as Super Properties or People Properties By Default and explicitly specifying in the traits or properties you want us to set as people properties in the Mixpanel destination panel in Segment. We’ll automatically include any trait on an identify that matches one of Mixpanel’s special properties, which you can see in the table above. Check out the documentation here

If you call identify without a userId, it may not set the People Properties inside Mixpanel, but it will cache those traits for later use with Segment’s analytics.js. It is best practice to always call identify with a userId.

Arrays

For array type traits passed to identify calls, we will use Mixpanel’s people.union to union (append ignoring duplicates) them to their existing values. If the trait doesn’t exist a new array will be created for you. To clear the contents of the an array trait you can pass an empty array [].

Server Side

When you call identify from any of our server-side libraries, we create or update the user in Mixpanel People with the traits you provide. Calling identify doesn’t create any users in the standard Mixpanel reporting interface since that only supports track events.

You won’t see server-side traits appear as super-properties on any events you track. This is because Mixpanel has no REST API for setting super properties for a distinct_id, so identify calls only affect Mixpanel People.

For Mixpanel People, it’s important to identify a user before you call track. A track without an identify won’t create a user in Mixpanel People.

Track

Because Mixpanel is an event tracking analytics tool, you’ll want to track your user’s actions. The more useful events you track, the better Mixpanel becomes.

You should use the track method to accomplish this. The Segment track method maps events and event properties directly to Mixpanel events and event properties.

Track Charge

If Mixpanel People is enabled in your Segment settings and you include an event property called revenue, we’ll track a charge to the current user.

Reserved Properties

There are two strings to avoid when naming event properties that will be sent to Mixpanel: length and bucket. length is interpreted as the JavaScript .length method, which causes the mixpanel.track call to fail silently. bucket is a reserved property that was used in the early days of Mixpanel. If you include a property called bucket in your events, it will not show up in the UI. However, it will not cause the mixpanel.track call to fail.

Alias

Calling alias is required for Mixpanel in all libraries in order to connect anonymous visitors to identified users.

As soon as you have a userId for a visitor that was previously anonymous you’ll need to alias their old anonymous id to the new userId. In Mixpanel only one anonymous user history can be merged to one identified user. For that reason you should only call alias once, right after a user registered, but before the first identify.

You’ll also want to track the action that caused the user to be identified or created. Read our guide on how to identify new users to learn why.

Read more about how Mixpanel recommends using alias in their docs.

Note: Due to technical limitations with aliasing server-side, aliasing on the client is recommended whenever possible.

Aliasing From the Browser

In client-side javascript you only need to pass the new identified userId. We will automatically alias the old anonymous id to your new userId.

Here’s a javascript example where the new userId is 12345:

alias('12345');
identify('12345');
track('Signed Up');

Aliasing Server-Side

If an identify or track call arrives to Mixpanel with a new distinct_id too quickly after an alias call, there is a race condition between the event and the alias call. As long as your identify and track calls arrive ~1 second after the alias, this shouldn’t be an issue; when the alias queue is backed up, Mixpanel queues events as well, mitigating the race condition.

However, in cases when events are processed too quickly, before their corresponding alias, your calls can result in split/duplicate profiles.

Mixpanel’s client-side javasript library fixes this issue by continuing to send track calls to the original mixpanel distinct_id while the records update. To leverage that protection and avoid creating split profiles and broken funnels, we recommend doing all aliasing for Mixpanel on the client side through Analytics.js

However, in certain circumstances, despite the risk of duplicate profiles, you may still wish to send the calls server-side. In those cases, there are two options for calling alias from your servers:

In Conjunction with Client-Side Tracking

If you’re tracking anonymous users on the client side either from a browser or one of our mobile SDK you’ll need to pass the Mixpanel distinct_id from the browser to your servers in order to alias it to the new userId.

First, use analytics.ready to grab the Mixpanel distinct_id:

analytics.ready(function(){
    var anonId = mixpanel.get_distinct_id();
});

Next, pass the anonId to your server and alias, identify, and track your new user.

Here’s a Node example where the new userId is 12345:

analytics.alias({ previousId: anonId, userId: '12345' });
analytics.flush(); // flush the alias

analytics.identify({userId: '12345'});
analytics.track({
  userId: '12345',
  event: 'Connected Facebook'
});

As you can see we recommend flushing the alias to give Mixpanel a bit of extra time to process it on their side before you identify and track.

Tracking Exclusively Server Side

If you’re tracking anonymous users in one of our server-side libraries that makes things a lot easier. All you have to do is alias the anonymous id to the new userId.

Here’s a Python example of the alias, identify, track sequence where the anonymous id was 92fh49fqh9849hf and the new userId is 12345:

analytics.alias('92fh49fqh9849hf', '12345')
analytics.flush() # flush the alias

analytics.identify('12345')
analytics.track('12345', 'Registered')

As you can see we recommend flushing the alias to give Mixpanel a bit of extra time to process it on their side before you identify and track.

Collecting contextual properties

If you are sending events server side, depending on your library (JS, mobile, or server), we will map as many Mixpanel supported contextual properties as we can.

You can check out which context properties are being automatically collected by any Segment library. If you are using a library that does not support a certain contextual property, you can still send them manually with your events, as long as it is sent in accordance with our spec.

For example, if you want to send utm parameters with your server side library, you can attach a context.campaign object like this:

// node library

analytics.track({
  userId: '019mr8mf4r',
  event: 'Purchased an Item',
  properties: {
    revenue: 39.95,
    shippingMethod: '2-day'
  },
  context: {
    campaign: {
      name: "TPS Innovation Newsletter",
      source: "Newsletter",
      medium: "email",
      term: "tps reports",
      content: "image link"
    }
  }
});

We do not map $library_version since that is reserved for Mixpanel’s library version, not Segment’s. We do not map to $brand.

Features

Autotrack

Mixpanel’s Autotrack feature is supported via Segment as long as you are using one of our client-side libraries (analytics.js, iOS, Android). Additionally, if you’re using analytics for Android or iOS, make sure your Mixpanel destination is bundled - otherwise Autotrack will not work. Once Mixpanel is installed via segment, all you have to do is enable the Autotrack feature for your Mixpanel account and it will start working.

People

By default we don’t send data to Mixpanel People since it usually requires upgrading your Mixpanel account. If you want to enable Mixpanel People simply check the box for: Use Mixpanel People from your source destinations page in the Mixpanel sheet.

If you want to add people properties in Mixpanel before you know the user’s unique databse userId you can identify traits without the userId. Note: this only works in Analytics.js and our mobile SDKs.

Your identify call would look like this in Analytics.js if you only want to set people properties without a userId:

analytics.identify({
  email: '[email protected]',
  name: 'Ian Taylor'
})

UTM Campaign Parameters

Since Segment’s client-side javascript library (analytics.js) loads mixpanel.js in the background, you’ll get the exact same functionality of Mixpanel around UTM Campaign Paramters as you would when using Mixpanel directly.

In order to pass UTM parameters server-side, you can either pass properties or traits of utm_source, utm_medium, utm_campaign, utm_content, and utm_term in your track and identify calls, or pass them in your context object, for example:

// node library

analytics.track({
  userId: '019mr8mf4r',
  event: 'Purchased an Item',
  properties: {
    revenue: 39.95,
    shippingMethod: '2-day'
  },
  context: {
    campaign: {
      name: "TPS Innovation Newsletter",
      source: "Newsletter",
      medium: "email",
      term: "tps reports",
      content: "image link"
    }
  }
});

Explicitly Set People Properties and Super Properties

We used to set all of your traits and properties as both Super Properties and People Properties (If you had Mixpanel People enabled) but now Mixpanel allows you to segment your reports by both People Properties and Super Properties. In order to give you better precision and control over what property or trait gets set as a Super Property or People Property, you can uncheck Set All Traits as Super Properties or People Properties By Default and pass in the properties or traits that you want to send to Mixpanel as People or Super Properties as shown below. We’ll still pass through all of Mixpanel’s special traits as People Properties so you only need to add the ones that aren’t on this list. Please note that we’ll only set People Properties off of .identify() calls.

Incrementing events

If you need to increment event counts for Mixpanel people, there’s no need to add any extra code. All you have to do is tell us which events need to be incremented and we’ll take care of the rest:

You can find this in the Advanced Options of your Mixpanel settings on your Segment Destinations page.

For each event name listed we will automatically call Mixpanel increment and also set a user trait of Last +.

For example, if you add Logged In to the list of increment events, we will increment a user trait called Logged In and set a trait called Last Logged In with the current date and time.

If you’d like to add an increment for viewing a specific page or screen, ensure you have the setting “Track Named Pages” selected and use the dynamically generated event name under “Events to Increment in People.” For example, .page('Signup') would translate to “Viewed Signup Page“ and .screen('Listing') would translate to “Viewed Listing Screen“.

Remember, we will only send 1 event per page call.

Note: Increment only works for “known users”, so if your track call is being made server-side, you need to pass in a userId. If your track call is being made client-side, you need to identify your user first.

Incrementing properties

To increment at the property level, simply tell us which properties you’d like us to increment via the Properties to increment setting and we will call Mixpanel’s increment for you when you attach a number to the property (e.g. 'items purchased': 5)

Bypass “Last Seen” in Server-side Calls

You can bypass the automatic re-setting of the “Last Seen” date property by passing active with a value of false in the context object, as follows:

analytics.identify(user_id='12345', traits={
    'name': 'Frank'}, context={
    'active': false
    })

Reset Mixpanel Cookies

When a user logs out, we recommend that you cal analytics.reset(); to wipe Segment cookie. Currently this function is not mapped to Mixpanel’s reset method. If you are having issues with distinct_id such as not being matched with the right user, you should add this to your logout flow:

analytics.ready(function(){
  window.mixpanel.cookie.clear();
});

IP

If an ip property is passed to Mixpanel, the value will be interpreted as the IP address of the request and therefore automatically parsed into Mixpanel geolocation properties (City, Country, Region). After that IP address has been parsed, they will throw out the IP address and only hold onto those resulting geolocation properties. As such, if you want to display an IP address as a property within the Mixpanel UI or within raw data, you will simply want to slightly modify the naming convention for that property.

Instead of ip, you can use a property name of user IP or IP Address ( whatever is most clear for your implementation). This way, Mixpanel won’t automatically interpret the IP address as an IP address, and instead store that value as a property on the event. You can read more here.

Ignore IP from Server to Disable Geo-location in Mixpanel People

If you’d like to avoid having any ip address sent to Mixpanel and by doing so, turn off geo-location for server-side users, please pass the context.ip as 0.

Here’s a python example:

analytics.track(user_id=user.id,
  event='Ignore My IP', context={
  'ip': 0
})

Please provide context.ip to all your identify, track, and alias calls to make sure Mixpanel doesn’t geo-locate your users.

Push Notifications

Push notifications are only available for projects bundling the Segment-Mixpanel SDK.

Note: You must set up your push notification handlers by calling into native Mixpanel methods. You can read more about how to approach this in our iOS and Android documentation.

In-App Notifications

In-app notifications are only available for projects either bundling the Segment-Mixpanel SDK or using the client-side Web integration.

Note: You must set up your in-app notification handlers by calling into native Mixpanel methods. You can read more about how to approach this in our iOS and Android documentation.

A/B Testing

Note: You must set up your push notification handlers by calling into native Mixpanel methods. You can read more about how to approach this in our iOS and Android documentation.

Device Connection Mode (Bundled Mobile SDK)

For in-app notifications and surveys, you can follow the Mixpanel documentation here. You can leverage the native functionality to control when to show an in-app message by following the instructions here and calling the native Mixpanel methods.

Cloud Connection Mode (Unbundled/ Serverside)

If you are using Mixpanel server side and you have access to your users’ device tokens, you can import into Mixpanel by sending the token via context.device.token as described in our specs with an identify call. We will send the token as Mixpanel’s special trait $ios_devices. This only works on iOS. In order to use push on Android, you must bundle the Mixpanel SDK.

For example, using our node library:

analytics.identify({
  userId: '019mr8mf4r',
  traits: {
    name: 'Michael Bolton',
    email: '[email protected]',
    plan: 'Enterprise',
    friends: 42
  },
  context: {
    device: {
      token: 'ff15bc0c20c4aa6cd50854ff165fd265c838e5405bfeb9571066395b8c9da449'
    }
  }
});

Tracking Mixpanel Push Notification Open Rate

To enable push tracking, click the checkbox within Mixpanel as explained in Mixpanel’s documentation. This feature allows push notification opens to be tracked as properties of an app open event, however this will miss pushes which are received when the app is already open.

To add push open tracking, Mixpanel requires that on initialization Mixpanel is launched with options. Segment makes this available through the factory (instancetype)createWithLaunchOptions:(NSString *)token launchOptions:(NSDictionary *)launchOptions;

Note: Push open tracking in Android is not currently supported by the Mixpanel Android library.

Troubleshooting

When Will I See Data from my Mobile App?

If you already have an app deployed with the Segment library, and you just turned on Mixpanel mobile, it will take up to an hour for all your mobile users to refresh their Segment settings cache, and learn about the new service that you want to send to.

After the settings cache refreshes, our library will automatically start sending data to Mixpanel.

Also worth noting, Mixpanel’s SDK only submits requests to the Mixpanel servers when the app is backgrounded. That means you may see events in your Segment debugger while testing, but those requests won’t actually be forwarded to Mixpanel until the app gets sent to the background.

If you are testing in Xcode remember you must first background the app, then the events will show up in Mixpanel. If you terminate the session without backgrounding those events will be lost.

I’m seeing events come into Mixpanel but not people.

1. You’ll need to make sure you’re using identify. A Mixpanel track does not create users in Mixpanel People.
2. Make sure to turn on the “People” setting so that all of your identify calls will be sent to Mixpanel’s People feature.
3. Make sure you have disable the default filter in the Mixpanel People Explore tab.

Personas

You can send computed traits and audiences generated through Segment Personas to this destination as a user property. To learn more about Personas, reach out for a demo.

For user-property destinations, an identify call will be sent to the destination for each user being added and removed. The property name will be the snake_cased version of the audience name you provide with a true/false value. For example, when a user first completes an order in the last 30 days, we will send an identify call with the property order_completed_last_30days: true, and when this user no longer satisfies we will set that value to false.

When the audience is first created an identify call is sent for every user in the audience. Subsequent syncs will only send updates for those users which were added or removed since the last sync.

Supported Sources and Connection Modes