Use mixpanel.alias() and mixpanel.identify() methods to keep the identity of your users consistent throughout their interactions in your site or app.
The correct implementation of these methods permits you to use your own user IDs, without breaking your Mixpanel reports (particularly Funnels).
Manage Identity with Alias and Identify Methods
An ideal integration enables you to track the actions of your users across your site or app. An example of a typical user journey would be if a user first engages your site anonymously, decides to signup, and logs in later.
Mixpanel provides two methods to let you track those actions;
- When a new user signs up, call mixpanel.alias("YOUR_USER_ID") once.
- When a user logs in, call mixpanel.identify("YOUR_USER_ID").
Here’s an example of how alias and identify work together to manage user identity:
- Sally comes to your website for the first time. Mixpanel assigns Sally a randomly generated ID, which is known as a Mixpanel distinct_id.
- Mixpanel assigns Sally the distinct_id “12345”. Now all her actions are tied to that distinct_id.
- After clicking through a few pages, she successfully signs up for an account.
- The signup confirmation page calls the mixpanel.alias() method and passes Sally’s email address as an argument. For example, mixpanel.alias(“email@example.com").
- The mixpanel.alias(“firstname.lastname@example.org”) method doesn't change her Mixpanel distinct_id. It adds the ID "email@example.com" to a Mixpanel lookup table and maps it to the original Mixpanel distinct_id “12345”.
- Now Mixpanel calls the mixpanel.identify("firstname.lastname@example.org") method and passes the ID ("email@example.com") to all subsequent pages and logins whenever Mixpanel sees data for "firstname.lastname@example.org”.
- Mixpanel remaps her original distinct_id of “12345”. So all actions Sally takes–whether on your site, in your app, or anonymously before she signed up for her account–maps to her.
The image below illustrates the identity management process.
Avoid Calling mixpanel.alias() on a User More Than Once
An alias can only point to one Mixpanel distinct_id.
If you’ve already mapped “email@example.com” to Mixpanel distinct_id “12345”, any attempt to map firstname.lastname@example.org to Mixpanel distinct_id 67890 fails.
In the previous example, Sally came to your website. Suppose she decides to download your app on her phone and logs in. The mixpanel.alias() method does not work here. Even though Sally has not used your app on this device before, she is not a new user.
If Mixpanel calls the mixpanel.alias() method, it would attempt to map the email to the random Mixpanel distinct_id from the phone. To remedy this scenario, add the mixpanel.alias() method to associate the original Mixpanel distinct_id “12345”, where all Sally’s actions are already stored.
If an identify or track call arrives to Mixpanel with a new distinct_id too quickly after an alias call, a race condition occurs between the event and the alias call.
Usually there are no issues when your identify and track calls arrive ~1 second after the alias. When the alias queue is backed up, Mixpanel queues events as well, alleviating the race condition.