Simplified ID Merge

Check your project's ID Merge version before proceeding. If your project is using Original ID Merge, refer to the documentation on Simplified ID Merge here.

Overview

• System use $device_id and$user_id to manipulate distinct_id

Usage

If using our Web/Mobile SDKs or a CDP like Segment or Rudderstack, there are only 2 steps:

1. Call .identify(<user_id>) when a user signs up or logs in. Pass in the user's known identifier (eg: their ID from your database).
2. Call .reset() when a user logs out.

Any events prior to calling .identify are considered anonymous events. Mixpanel's SDKs will generate a $device_id to associate these events to the same anonymous user. By calling .identify(<user_id>) when a user signs up or logs in, you're telling Mixpanel that $device_id belongs to a known user with ID user_id. Under the hood, Mixpanel will stitch the event streams of those users together. This works even if a user has multiple anonymous sessions (eg: on desktop and mobile). As long as you always call .identify when the user logs in, all of that activity will be stitched together.

Mechanism

• talk about the $user_id and$device_id in detail

$device_id

• autogenerated by client-side SDK and attached to all events
• this becomes distinct_id attached to event if $user_id not present
• all events should have this property
• aka anonnymous ID

$user_id

• Calling identify SDK function sets the user_id value passed to the function as the $user_id for all events moving forward
• $user_id will always becomes distinct_id for the event whenever it is present
• when $user_id and $device_id are detected in the same event for the first time, merge occurs

Example User Flows

• Charlie example.

Mimic below but update to Original ID Merge

Let's walk through a few user flows where ID Merge is useful, and when to call .identify() and .reset() to use ID Merge properly.

Note: these flows walk through how distinct_id is set in Simplified ID Merge; in Original ID Merge, the value of distinct_id is not deterministic. See the FAQ for more details on how distinct_id is set.

New User Signup

1. A user lands in your product on a new device and interacts with your product before signing up. Our SDK will assign the user a random $device_id and persist it. All events tracked at this point will send only a $device_id.

   Event	$device_id	$user_id	distinct_id (set by Mixpanel)	Notes
   1	D1		$device:D1
   2	D1		$device:D1

2. The user returns later and signs up for your product. You call .identify(<user_id>). All events sent after this point are tracked with both the original $device_id and the new $user_id. Mixpanel will retroactively set the $user_id on any prior events with the user’s $device_id so that both event streams are joined.

   Event	$device_id	$user_id	distinct_id (set by Mixpanel)	Notes
   1	D1		$device:D1 ⇒ U1	Retroactively updated
   2	D1		$device:D1 ⇒ U1	Retroactively updated
   3	D1	U1	U1	Links D1 ⇒ U1

Returning User

1. The user from the previous flow returns, but is on a new device and has not logged in yet.

   Event	$device_id	$user_id	distinct_id (set by Mixpanel)	Notes
   1	D1		$device:D1 ⇒ U1
   2	D1		$device:D1 ⇒ U1
   3	D1	U1	U1	Links D1 ⇒ U1
   4	D2		$device:D2	New device D2
   5	D2		$device:D2

2. The user logs in. Call .identify(U1) to tell us that the user on this device is the same $user_id we have seen before.

   Event	$device_id	$user_id	distinct_id (set by Mixpanel)	Notes
   1	D1		$device:D1 ⇒ U1
   2	D1		$device:D1 ⇒ U1
   3	D1	U1	U1	Links D1 ⇒ U1
   4	D2		$device:D2 ⇒ U1	Retroactively updated
   5	D2		$device:D2 ⇒ U1	Retroactively updated
   6	D2	U1	U1	Links D2 ⇒ U1

Multiple Users, One Device

1. A first user begins using a new device.

   Event	$device_id	$user_id	distinct_id (set by Mixpanel)	Notes
   1	D1		$device:D1

2. The user logs in. Call .identify(U1), which links the $device_id to their $user_id.

   Event	$device_id	$user_id	distinct_id (set by Mixpanel)	Notes
   1	D1		$device:D1 ⇒ U1	Retroactively updated
   2	D1	U1	U1	Links D1 ⇒ U1

3. The user logs out. At this point, you should call .reset(), or manually generate a new $device_id if you are managing it yourself. A new user shows up and tracks events using this new $device_id.

   Event	$device_id	$user_id	distinct_id (set by Mixpanel)	Notes
   1	D1		$device:D1 ⇒ U1
   2	D1	U1	U1	Links D1 ⇒ U1
   3	D2		$device:D2	Reset generated new ID: D2
   4	D2		$device:D2

4. This new user (U2) now logs in. Call .identify(U2).

   Event	$device_id	$user_id	distinct_id (set by Mixpanel)	Notes
   1	D1		$device:D1 ⇒ U1
   2	D1	U1	U1	Links D1 ⇒ U1
   3	D2		$device:D2 ⇒ U2	Retroactively updated
   4	D2		$device:D2 ⇒ U2	Retroactively updated
   5	D2	U2	U2	Links D2 ⇒ U2

Limitations

• cannot link 2 anon $device_id without assigning a$user_id
• cannot have 2 $user_id in a cluster
• no $merge for fixing mistakes
• $merge profile direction not predictable