Getting Started with Identity Management

Introduction

Users might use different browsers, move from a mobile device to a laptop, or periodically clear browsing data. Mixpanel's identity management system offers the ability to link users’ movements across different platforms, giving a holistic view of the user journey.

Mixpanel is able to link together every user’s journey using our identity merge events to create an identity cluster. An identity cluster contains a collection of distinct_ids that connect to an individual user. Connecting multiple identifiers to an individual user results in accurate reporting by properly attributing events to the user that performs them, regardless of the device they are presently using.

Understanding how to use Mixpanel’s identity management tools greatly expands your ability to glean actionable insight from event data.

Individual Users

Users often travel across platforms, making it challenging to connect their journey. To connect a user journey and its associated data, Mixpanel connects multiple distinct identifiers, called distinct_ids, to one user.

Mixpanel connects all of a user’s identifiers and tracks that cluster of distinct_ids. This means that most tracked users won’t have one distinct_id, but a collection of them. An “identity cluster” is the name for this collection of distinct_ids.

Mixpanel ultimately applies logic to these clusters to determine which value to use as the cardinal identifier in event, user, and MTU calculations. This identifier is called the canonical distinct_id.

Canonical Distinct ID

Although data can be resolved back to a user using any distinct_id from an identity cluster, all Mixpanel report calculations use a single identifier from the cluster. This identifier is selected by Mixpanel and is referred to as the canonical distinct_id. You cannot chose which ID will be used as canonical.

Once merged, the events for all distinct_ids in a cluster will display with the canonical distinct_id. Additionally, all profile updates will be redirected to a single profile with the canonical distinct_id for the cluster.

This means that you may see events with a distinct_id that is different from what you originally sent into Mixpanel. If Mixpanel changed the distinct_id of an event to the canonical distinct_id, Mixpanel will append a property called $distinct_id_before_identity to the event with the original distinct_id value.

To reflect the dynamics of a user journey, the canonical distinct_id can change, but will always be included in the identity cluster connected to an individual.

Local Distinct IDs

While the canonical distinct_id is used in report calculations, there can still be other distinct_ids in the cluster connected to an individual user.

There will be an identifier on a user’s device at the time that they are interacting with an application with Mixpanel. This identifier is referred to as the local distinct_id.

The local distinct_id can be randomly generated, or it can be the assigned ID that is connected to the user after an identify call. Regardless of what the local distinct ID is at any given time, it ultimately connects to the cluster of distinct_ids.

The local distinct_id sometimes can be the canonical distinct_id, and other times it won’t. Regardless, it will always live in the individual’s cluster of distinct_ids. Do recall, however, that it won’t always be visible in reports and data exports.

User Identification

While Mixpanel ultimately handles the cluster of distinct_ids and the canonical distinct_id, you can still assign your own identifiers, or local distinct_id, to an individual user.

Identify

Use the identify method to connect your chosen identifier to an anonymous distinct_id. In most cases, this identifier should already exist somewhere in your stack. This could be a user id in a server or a cardinal id in a data warehouse, for example.

The identify method in our client-side SDKs will trigger an $identify event when appropriate. The two distinct_ids from that event will be merged into a cluster when merge criteria are passed.

Alias

The $create_alias event can also be used to merge distinct_ids. The alias method in our client and server-side SDKs will trigger this event when appropriate.

Alias can merge two non-anonymous distinct_ids together if other merge criteria are passed.

Merge

The $merge event is the tool that allows you to join any two distinct_ids into one identity cluster. In other words, this is combining data that appears to be from separate users into one user.

Use ID Merge when you are confident that two separate non-anonymous identifiers belong to one user (a Salesforce and Mixpanel identifier for example). By sending the $merge event, you can join these two distinct_ids into one cluster that connects to an individual.

NOTE: For all merging events, the merging of two distinct_ids cannot be undone. Additionally, if either (or both) the distinct_ids being merged are already part of an identity cluster, the result will be a single identity cluster containing all distinct_ids from both clusters.

Identification Examples

The following are examples of common identification flows. These examples assume that Mixpanel is implemented using a client-side SDK.

Identify New User

The typical flow of a new user will be to:

1. Land on an application.
   • Mixpanel’s SDK assigns a random distinct_id to the unidentified user.
2. Sign up for your application.
   • You call identify using your assigned distinct_id.
   • The user now has a random distinct_id and your assigned distinct_id in their cluster of identifiers.

Mixpanel uses one of these two distinct_ids as the Canonical ID for calculations.

Identify Returning User

The typical flow of a returning user will be to:

1. Land on an application.
   • Mixpanel assigns a random distinct_ID to the unidentified user.
2. Sign up for your application.
   • You call identify using your assigned distinct_id.
   • The user now has a random distinct_id and your assigned distinct_id in their cluster of identifiers.
3. Log out.
   • Your user switches to a different device, or you call reset, which treats the next user as new.
4. Log in for your application on a new device.
   • You call identify.
   • Mixpanel recognizes the previously used assigned distinct_id. The user now has a new random distinct_id added to their cluster of identifiers.

Mixpanel uses one of these three distinct_ids as the canonical distinct_id for calculations.

Merge

Merging identifiers is essentially combining two identity clusters.

If you have one user with a cluster of distinct_ids, a second user with a cluster of distinct_ids, and you merge them, then you will now have one identity cluster.

This cluster is treated as an individual user, and one canonical distinct_id will be selected from the cluster.