Moving to Identity Merge

Identity merge is an overhaul of Mixpanel's identity management capabilities. We've made drastic improvements to our identity resolution infrastructure and added new tools to give users more power and transparency in mapping user actions together.  These improvements are available without the need for any code changes to existing implementations - simply enable Identity Merge and ensure your SDK version is up to date to receive the benefits.

This article covers the improvements to Mixpanel's identity management infrastructure, how to check if your project has Identity Merge enabled, and the changes you can expect when the new system is enabled. 

Find more information on how the new identity merge system works in the new Getting Started with Identity Management article and Managing User Identity section of API spec. 

Benefits of the New System

The new system improves the behavior of identify(), alias(), and adds a new event called $merge.  

All pre-authentication activity can now be mapped back to a user

The ID merge system makes it possible to link pre and post authenticated event streams under a single identifier. This eliminates “false-uniques”, ensuring the most accurate conversion and drop-off rates in funnels and flows.

Previously, Mixpanel could only map pre-sign up activity back to a user who was later identified. Any activity a user did anonymously before signing in again could not be attributed to that user. 

Merge data with different unique identifiers

Mixpanel can now merge events with different unique identifiers. The existing identify and alias methods along with the new $merge event can now be used to merge event streams under a single user, even after data has been ingested.

Easier implementation while remaining backward compatible

Those with Mixpanel already implemented will not need to change anything in their implementations.  The identify and alias methods already implemented will be able to merge identifiers as soon as the ID merge system is enabled.

For new implementations, the updated functionality of the identify method makes implementation easier.  Just call identify with your chosen identifier as soon as you know who the user is to merge anonymous and identified distinct_ids.  Calling alias is no longer required.


Enable ID Merge

You can see if your project has Identity merge enabled by checking Identity Merge under Project Settings.


You can request for your organization to be added to the ID merge system via Organization Settings in the Identity Merge tab.  This will turn ID merge on for all projects in your organization.


For client-side implementations, make sure your SDK version is up to date so ID merge is able to link pre-authentication activity back to an authenticated user.  ID merge is supported with: 

    • Android: 5.6.3+
    • Flutter: 1.0.0+
    • iOS - obj: 3.4.7+
    • iOS - swift: 2.6.3+
    • Javascript: 2.29.0+
    • React Native: 1.0.0+
    • Unity: 2.0.0+ 
    • ... and all server side SDKs (python, php, etc)

Changes After Enabling ID Merge

An email will be sent to the user who enabled ID Merge when the migration is complete. You can expect the following changes after completion:

New events will show up in your project

Mixpanel will track new $identify, $merge and $create_alias events to help with debugging. These events do not count towards billing. By default, these events will be hidden from dropdowns. You can choose to unhide them in Lexicon. 

Unique user counts may decrease, user profile counts may decrease

Since ID merge can merge already ingested events together under a single user, you may notice a change in the unique counts of events in your project as your events are accurately attributed to the correct users.

If multiple user profiles exist when multiple distinct ids are merged, Mixpanel will hide all but one of the user profiles.

Reports will take some time to reflect merged identifiers

The Activity Feed within User Profiles will show events being merged immediately.  Unique counts in other Mixpanel reports like Funnels, Insights, Users and Cohorts will take up to 24 hours to properly reflect the merged state of identifiers.

Monthly Tracked User (MTU) tallies may decrease 

The MTU billing system is based on the number of users you track with Mixpanel.  Since ID Merge is able to map user activity together more effectively, you may notice a decrease in your MTU count.  Note: Previously months billing tallies will not be modified.

You can no longer control the canonical id for users in Mixpanel

The ID merge system will now determine which distinct_id is used as the canonical id for a user in Mixpanel. Any merged id can be used to query for information about a user with our APIs, but the results of the query may return a with different canonical distinct_id value than the one used in the query.  

To ensure the queried id is available in the results, it is best practice to send your chosen user id in as an explicit property for events and profiles. We recommend calling this property $user_id. 

Avoid using non-Mixpanel generated anonymous ids

The updated identify method comes with some built-in guardrails to help avoid users sharing a device from being incorrectly merged together. These guardrails require that anonymous activity is tracked with a distinct_id using a UUID v4 format (distinct_ids generated by Mixpanel's client-side SDKs meet this requirement).  Tracking anonymous activity with Mixpanel generated distinct ids will allow for correct merging behavior once a user is identified. Note: We’ve worked Segment to ensure their anonymous ids are also compatible with our new system.

User profiles will not automatically aggregate all user properties when merged 

This mainly affects implementations that have duplicate or anonymous user profiles.  

ID merge will map events from merged ids together.  When this happens, Mixpanel will display the profile with the Mixpanel determined canonical distinct id.  User property values will not be updated or added based on other profiles merged. To avoid losing profile properties, we recommend creating user profiles after a user has been identified.


Testing ID Merge

If you want to test the ID Merge system before enabling it in your primary organization, the easiest method is to create a new test organization. All organizations created after March 16th, 2020 will have identity merge enabled by default for all projects.

To create another organization you will need to sign up for a new Mixpanel account. After making a new account, create a project and invite any other users who want to test the id merge system to the project. Any data sent to the new project will follow the identity merge rules, giving the ability to test the new id merge behavior without affecting your primary organization's data.


Did this answer your question?



Please sign in to leave a comment.