Segment

Overview

Segment, a Customer Data Platform (CDP), enables you to track event data and route it to various downstream destinations. As a native partner, Mixpanel seamlessly integrates with Segment. If you use Segment for tracking, you can send your data to Mixpanel with just a few clicks.

How the Integration Works

In the simplest form, the Segment libraries (“Sources”) generate messages about what is happening in your site or app, and send them to the Segment servers. Segment then translates the content of those messages into different formats for use by other tools (which we call ‘Destinations’), and sends the translated messages to those tools. The Segment servers also archive a copy of the data, and can send data to your storage systems (such as databases, warehouses, or bulk-storage buckets).

Mixpanel is one of the supported Segment destinations. With this integration, you can easily send your data collected from your Segment source into your Mixpanel project as a downstream destination.

For detailed instructions on how to install the Segment tracking library, please refer to the Segment Getting Started Guide.

Quick Start

1. Integrate with Segment

Once you’ve installed and initialized a Segment library in your application, get your data into Mixpanel by following the instructions for setting up the Mixpanel (Actions) Destination

2. Identify Users

The next thing you need to do is identify your users, so that you can understand your users. We recommend calling identify when your user sign up and log in.

When you call Segment’s identify API, Mixpanel will set the specified userId as the Mixpanel distinct_id. Any traits you provide in the call will be applied as profile properties for the targeted user in Mixpanel.

3. Track User Actions

Lastly, track your users’ actions using Segment’s track API call, which would trigger Mixpanel’s import API and ingest an event in your project.

4. Check for Success

Open up Events View in Mixpanel to view incoming events.

Configure the Destination

We recommend using the Mixpanel Actions destination.

Once you have installed the Segment library and see tracked data in your Segment instance, get your data into your Mixpanel project by setting up a destination following the Segment documentation here.

Below is a high-level summary of the steps to setup the Mixpanel destination:

1. In Segment, click the Catalog tab, filter for Destinations, and select Mixpanel to add the destination.

2. Select a Segment source to stream to the destination.

3. Set a name for the destination then choose a framework. We recommend Actions destination. (Learn more about the framework options)

4. Provide your Mixpanel project credentials in the Basic Settings, then click the toggle at the bottom to enable the destination. The project credentials are found in your project settings.

Data Mapping

Segment’s Actions framework allows you to configure how Segment sends the data it receives from your source to Mixpanel.

Preset Actions

The Mixpanel Actions destination comes with a preset of default mappings that you can use out the box. You can find them in the “Mappings” tab of the destination settings.

Preset Name	Segment Trigger	Mixpanel Action
Order Completed Calls	Event type = “track” and event = “Order Completed”	Import Event “Order Completed”
Track Calls	Event type = “track” and event != “Order Completed”	Import Event
Screen Calls	Event type = “screen”	Import Event “Viewed {name}“
Identify Calls	Event type = “identify”	Identify User (Simplified API /Original API) and Set Profile Properties
Page Calls	Event type = “page”	Import Event “Viewed {name}“
Group Calls	Event type = “group”	Identify Group

Note that the id Segment event property is a reserved property that is mapped to distinct_id in Mixpanel. Avoid sending events with an id event property from Segment.

Customize Mappings

Note that context (learn more here) is a Segment concept which does not have an equivalent in Mixpanel’s data model. If there are keys inside of the context dictionary that you need to add to your event and it is not a default property that is already in the mapping, you will need to edit the properties object to manually include it.

You can customize the preset actions mapping or create new mappings to further configure your event payload before they are sent to Mixpanel.

To edit an existing mapping, click the ”…” button in the actions table. To create a new mapping, click the “New Mapping” button in the top right of the UI.

Editing or creating new mappings is done in 4 steps.

1. Set Condition

Define the conditions under which the action should run. You can specify the conditions using a combination of Event Type, Event Name, and Event Property.

Let’s say you want to create a mapping that is triggered for any events tracked on Android. In this case, we can set the condition to Event Type equal Track and Event Property platform equal android:

2. Sample Payload

For testing your mapping, set an example payload. You can use an existing event from your source, load a Segment-generated sample event, or create a sample payload manually.

Ensure that this example payload matches the condition you set above so that the Action applies to your expected payload. As a best practice, insert an example payload that you know should not match the condition to verify that your condition is specific enough to target only your expected payload.

Since we’re creating a mapping for any events tracked on Android, we insert a test event payload that includes the property platform set to android:

3. Edit Mapping

Edit the mapping of the Action to configure your output payload in your desired format. In this stage, we are essentially creating a Segment payload using data that is generated from Segment’s SDK, which will then be sent to Mixpanel’s destination mapping code for additional processing.

On the left side of the UI, you can configure the output value using the available data from your Segment source payload. On the right side of the UI, you can define the property names for the Segment payload that will be sent to Mixpanel.

If we want to append “ANDROID” to the names of events coming from this Android actions mapping, specify this in the Event Name row on the left-hand side:

To include the messageId from the sample Segment payload as a Mixpanel event property called “Segment Message ID”, edit the Event Properties mapping:

By default, the track preset takes the entire properties object from the Segment payload and uses it to generate “Event Properties” for the Mixpanel event payload. To edit the event properties mapping, you will need to manually define each property key-value pairs manually.

4. Preview Payload

Once you are done with configuring the mapping, preview how your sample payload is mapped through the Action by expanding on the “Event context”. You can also ingest the sample payload into Mixpanel to see how it will appear in your project by clicking “Send test event to destination”.

Note that while the Event Content tab is helpful for showing how your properties are getting mapped through the Action, your payload will go through additional processing before getting ingested in Mixpanel. Send the test payload to destination in order to preview how your event will appear inside your project.

Implementing Group Analytics using Segment

There are 4 parts to implementing Group Analytics via Segment. Learn more about Group Analytics here and the Segment Group Spec here.

1. Define the Group Key in Mixpanel

Create the Group Key in Mixpanel Project Settings. In this example, we are setting company_id as the group key.

2. Configure your Group Actions Mapping

If a Group Key mapping is not specified, Segment will use $group_id as the group key by default. In this case, set your group key in Mixpanel to $group_id.

Edit the Group action preset or create a new action mapping to target your group calls. You should manually type in the group key in the mapping to the same as it appears in the Mixpanel settings.

Additionally, make sure the “Group ID” is mapped to the value of the groupId.

Since we set the group key to company_id earlier, we manually enter it as the Group Key in the mapping. The groupId is the default key that Segment uses as the identifier for a group, so we map it to the Group ID.

3. Create Group Profiles

Calling Segment SDK function analytics.group() will create Group Profile/Group Profile Properties in Mixpanel.

//the groupId is "some_company"
//the second argument contain 3 group profile properties to be set
analytics.group("some_company", {
    "$name": "some_company_name",
    "employees": 100,
    "id": "some_company"
})

Example Group Profile/Group Profile Properties created from the group method above:

4. Add Group Key as a User Profile Property

In order to use Group Profile Properties when analyzing User Profiles, the user profile must have the Group Key/Group ID Value as a profile property.

Declare the Group Key in the identify method as a profile property (trait):

5. Add Group Key as an Event Property to Events

In order to connect events to a Group, the event must have the Group Key/Group ID Value as an event property.

The Group Key must be explicitly declared as an event property on every event track call in order for the event to be compatible with Group Analytics.

If you are using Segment Device Mode (Classic destination):

• Declare the Group Key as a Super Property so that the Group Key is sent in as an Event Property to client-side events.
• By default, all traits specified in the identify call will be registered as super properties. This means if you have the “Automatically set all Traits as Super Properties and People Properties” setting turned on, all traits specified in the identify call will be added as both a super property and profile property for the user.

Debugging

For debugging purposes, it can be useful to see exactly what Segment is sending to Mixpanel. You can validate this data through the Segment Source Debugger. In the Segment Source Debugger, you can select the event you are looking to validate:

Click the “Validate” button in the top right corner and choose “Mixpanel” as the destination. After the event has been sent, you can click to view the request from Segment to grab the data payload:

You can then copy the data payload and decode it in a base64 decoder to see the JSON event that was sent to Mixpanel.

Setting up Autocapture with Segment

Note: In most cases, we do not recommend implementing Autocapture with Segment to minimize the risks of identity management issues. Please consult with a member of our team if you choose to use this approach.

It is possible to use Mixpanel’s Autocapture in conjunction with Segment; the following tutorial will show you how to implement Autocapture on your website in a way that integrated with cloud mode.

The Segment SDK does not currently support an Autocapture mechanism, so the way to integrate is to load the Mixpanel Javascript SDK on your website, and then use a snippet which implements Segment’s middleware pattern to ensure that the user and device_ids match in the Segment and autocaptured data.

In this setup, the autocaptured event data will go directly to Mixpanel and will not pass through the Segment pipeline - however the user’s identity will be kept in sync between both systems allowing you to have consistent user flows in Mixpanel that properly join autocaptured data and Segment tracked data.

In the following code snippet we:

• Embed the Segment SDK in our app
• Send an event (app loaded) to Segment; this event is forwarded to Mixpanel
• Embed the Mixpanel SDK in our app
  • Activate Autocapture to track all track clicks
  • Ensure that Mixpanel, when loaded looks for Segment’s user and device_ids
• Register middleware with Segment to ensure that, when Segment loads, it propagates identity data to Mixpanel

Important: the following snippet includes options for both simplified and original identity merge; please comment out the method you are not using.

<!DOCTYPE html>
<html>
<head>
	<title>segment + mixpanel autocapture</title>

	<!-- SEGMENT INSTALL (analytics.js) -->
	<script type="text/javascript">
		const SEGMENT_WRITE_KEY = `dHWN9FMfq2Ocmsjx4oAZQ48KQRrZrrl0`;
		!function () {
			var i = "analytics", analytics = window[i] = window[i] || []; if (!analytics.initialize) if (analytics.invoked) window.console && console.error && console.error("Segment snippet included twice."); else {
				analytics.invoked = !0; analytics.methods = ["trackSubmit", "trackClick", "trackLink", "trackForm", "pageview", "identify", "reset", "group", "track", "ready", "alias", "debug", "page", "screen", "once", "off", "on", "addSourceMiddleware", "addIntegrationMiddleware", "setAnonymousId", "addDestinationMiddleware", "register"]; analytics.factory = function (e) { return function () { if (window[i].initialized) return window[i][e].apply(window[i], arguments); var n = Array.prototype.slice.call(arguments); if (["track", "screen", "alias", "group", "page", "identify"].indexOf(e) > -1) { var c = document.querySelector("link[rel='canonical']"); n.push({ __t: "bpc", c: c && c.getAttribute("href") || void 0, p: location.pathname, u: location.href, s: location.search, t: document.title, r: document.referrer }); } n.unshift(e); analytics.push(n); return analytics; }; }; for (var n = 0; n < analytics.methods.length; n++) { var key = analytics.methods[n]; analytics[key] = analytics.factory(key); } analytics.load = function (key, n) { var t = document.createElement("script"); t.type = "text/javascript"; t.async = !0; t.setAttribute("data-global-segment-analytics-key", i); t.src = "https://cdn.segment.com/analytics.js/v1/" + key + "/analytics.min.js"; var r = document.getElementsByTagName("script")[0]; r.parentNode.insertBefore(t, r); analytics._loadOptions = n; }; analytics._writeKey = "RT8UgSD2nynW0HbEg6djCUWuEvD2kOQA";; analytics.SNIPPET_VERSION = "5.2.0";
				analytics.load(SEGMENT_WRITE_KEY);
				analytics.track('app loaded', { version: 1 }); // sample segment "track" event
				analytics.page('my page'); // sample segment "page" event
			}
		}();

		// ! IMPORTANT: tell Segment to propagate Ids to Mixpanel
		analytics.addSourceMiddleware(({ payload, next, integrations }) => {
			if (payload.obj.type === 'track' || payload.obj.type === 'page') {
				if (window.mixpanel) {
					const segmentDeviceId = payload.obj.anonymousId;
					// -------------------------------------------
					// Comment out one of the below mixpanel.register methods depending on your ID Management Version
					// Original ID Merge
					mixpanel.register({ $device_id: segmentDeviceId, distinct_id: segmentDeviceId });
					// Simplified ID Merge
					mixpanel.register({ $device_id: segmentDeviceId, distinct_id: "$device:" + segmentDeviceId });
					// -------------------------------------------	
				
				}
			}
			if (payload.obj.type === 'identify') {
				if (window.mixpanel) {
					const userId = payload.obj.userId;
					mixpanel.identify(userId);
				}
			}
			next(payload);
		});
	</script>
	<!-- MIXPANEL INSTALL -->
	<script type="text/javascript">
	const MIXPANEL_TOKEN = "0c1e0f968cd6b969ce6c84fe89c95830";
	(function (f, b) { if (!b.__SV) { var e, g, i, h; window.mixpanel = b; b._i = []; b.init = function (e, f, c) { function g(a, d) { var b = d.split("."); 2 == b.length && ((a = a[b[0]]), (d = b[1])); a[d] = function () { a.push([d].concat(Array.prototype.slice.call(arguments, 0))); }; } var a = b; "undefined" !== typeof c ? (a = b[c] = []) : (c = "mixpanel"); a.people = a.people || []; a.toString = function (a) { var d = "mixpanel"; "mixpanel" !== c && (d += "." + c); a || (d += " (stub)"); return d; }; a.people.toString = function () { return a.toString(1) + ".people (stub)"; }; i = "disable time_event track track_pageview track_links track_forms track_with_groups add_group set_group remove_group register register_once alias unregister identify name_tag set_config reset opt_in_tracking opt_out_tracking has_opted_in_tracking has_opted_out_tracking clear_opt_in_out_tracking start_batch_senders people.set people.set_once people.unset people.increment people.append people.union people.track_charge people.clear_charges people.delete_user people.remove".split(" "); for (h = 0; h < i.length; h++) g(a, i[h]); var j = "set set_once union unset remove delete".split(" "); a.get_group = function () { function b(c) { d[c] = function () { call2_args = arguments; call2 = [c].concat(Array.prototype.slice.call(call2_args, 0)); a.push([e, call2]); }; } for (var d = {}, e = ["get_group"].concat(Array.prototype.slice.call(arguments, 0)), c = 0; c < j.length; c++) b(j[c]); return d; }; b._i.push([e, f, c]); }; b.__SV = 1.2; e = f.createElement("script"); e.type = "text/javascript"; e.async = !0; e.src = "undefined" !== typeof MIXPANEL_CUSTOM_LIB_URL ? MIXPANEL_CUSTOM_LIB_URL : "file:" === f.location.protocol && "//cdn.mxpnl.com/libs/mixpanel-2-latest.min.js".match(/^\/\//) ? "https://cdn.mxpnl.com/libs/mixpanel-2-latest.min.js" : "//cdn.mxpnl.com/libs/mixpanel-2-latest.min.js"; g = f.getElementsByTagName("script")[0]; g.parentNode.insertBefore(e, g); } })(document, window.mixpanel || []);

	mixpanel.init(MIXPANEL_TOKEN, {
		autocapture: true,
		// ! IMPORTANT: tell Mixpanel to look for Segment's device ID
		loaded: function (mixpanel) {
			if (analytics && analytics.user) {
				const segmentDeviceId = analytics.user().anonymousId()
				if (segmentDeviceId) {
					// Comment out one of the below mixpanel.register methods depending on your ID Management Version
					// Original ID Merge
					mixpanel.register({ $device_id: segmentDeviceId, distinct_id: segmentDeviceId });
					// Simplified ID Merge
					mixpanel.register({ $device_id: segmentDeviceId });
				}
				const segmentUserId = analytics.user().id()
				if (segmentUserId) {
					mixpanel.identify(segmentUserId);
				}
			}
		}
	});
	</script>
</head>

<body>
	<h1>👋 hello segment + autocapture!</h1>
	<div class="buttons">
		<button id="clickMeButton">click me</button>
		<button id="dontClickMeButton">don't click me</button>
	</div>
</body>
</html>

FAQ

1. Why are my Segment data not appearing in my project?

This could be due to several reasons:

• Storing data in the EU: A common issue is that the data in Segment is enabled to be sent to an EU endpoint but the Mixpanel data is still being stored outside of the EU. Both endpoints for Segment and Mixpanel need to point to the EU as described here. If you have an existing Mixpanel project, you might need to have your data migrated to the EU. Please find further information here.

• Cloud implementation vs. device implementation (Only applies to Classic destination; Action is cloud-mode only): Segment can be implemented via a cloud-based implementation or as an SDK on the device directly. Device implementation will send the data to Mixpanel directly while the cloud implementation will send it to Segment first. You can confirm your implementation by querying for the Mixpanel library property of the events in your project:

  • Cloud Mode will show as Mixpanel Library: Segment: analytics.js

  • Device Mode will show as Mixpanel Library: Segment: web

• No user profile data in Mixpanel (Classic destination only): Segment does not track Mixpanel People by default. This is a setting you need to enable in your Segment settings. To enable Mixpanel People, change the “Use Mixpanel People” setting in your Segment Settings UI.

2. Why are there duplicated Segment events in my project?

Mixpanel SDKs assign an $insert_id to each tracked event.

This allows Mixpanel to ensure no event is tracked more than once and events will be deduplicated based on the insert_id. Segment does not assign an insert_id to events. If the ingestion of an event is not confirmed by Mixpanel’s servers fast enough, Segment will retry to send the event.

This can lead to duplicate events in Mixpanel, they will likely have different insert_ids as Mixpanel assigns each event without an insert_id a unique new one. This behavior can be caused by sending huge batches of data at the same time and can be avoided by reducing the batch size and frequency of event sending from Segment to Mixpanel.

3. How do I register super properties using Segment?

Super properties can only be set when you are running in device mode and using the Classic destination. The super properties are automatically set with every property you pass into the analytics.identify() method. To have more control over the super properties you set, you can explicitly set super properties in your Segment settings.

4. How do I track page views using Segment?

In analytics.js, a Page call is included in the initialization snippet by default right after analytics.load(). Otherwise, you will want you will want to call analytics.page() manually to track page view.

For the Preset Action, the default Event Name mapping for page call is Viewed {name}. To consolidate event names (e.g. “Page Viewed” or “Loaded a Page”), modify the Event Name mapping.

5. How can I filter for events that originate from Segment in my project?

Events coming from Segment are marked with the event property mp_lib (Mixpanel Library) set to the name of the Segment SDK used to generate the event. For example, events sent using Segment’s Javascript SDK will have the mp_lib property set to Segment: analytics.js.