How should I be using alias and identify to make sure user identity stays consistent?

You can keep users’ identities consistent throughout their interactions with your site and app (or both) by properly using mixpanel.alias() and mixpanel.identify() calls. Implementing these methods correctly will allow you to successfully use your own user IDs without breaking your Mixpanel reports (particularly Funnels).

Ideal implementation

The ideal integration that will allow you to track users from anonymous browsing all the way through signup and subsequent logins:

  1. When a new user signs up, call mixpanel.alias("YOUR_USER_ID") once ;
  2. When a user logs in, call mixpanel.identify("YOUR_USER_ID").

How do alias and identify work?

How alias and identify work together to allow you to manage user identity is best illustrated by walking through an example:

  • Sally comes to your website for the first time. Mixpanel assigns Sally a randomly generated ID, which is known as a Mixpanel distinct_id (for more information, see: How do Mixpanel’s libraries assign unique identifiers by default?).

  • For this example, let’s say she’s assigned the distinct_id 12345; now, everything she does on your website is being associated with that Mixpanel distinct_id.

  • After clicking through a few pages, she successfully signs up for an account.

  • On the signup confirmation page, you call mixpanel.alias(“sally@gmail.com").

  • Calling mixpanel.alias(“sally@gmail.com”) doesn't actually change her Mixpanel distinct_id; instead, what it does do is add the ID "sally@gmail.com" to a lookup table on Mixpanel’s end and map it to the original Mixpanel distinct_id.

  • Now, you can start calling mixpanel.identify(“sally@gmail.com”) on all subsequent pages and logins, and whenever Mixpanel sees data for "sally@gmail.com,” Mixpanel knows to remap it to 12345 (her original distinct_id). So all actions Sally takes - whether on your website, in your app, or anonymously before she even signed up for her account - will go to the same place and be attributed to the same user.

alt text

Avoid calling mixpanel.alias() on a user more than once

Avoid calling mixpanel.alias() on a user more than one time; an alias can only point to one Mixpanel distinct_id. If you’ve already mapped sally@gmail.com to Mixpanel distinct_id 12345, an attempt to then map sally@gmail.com to Mixpanel distinct_id 67890 will silently fail.

Continuing on the example from above, let’s say Sally now access your app for the first time. She downloads the app and logs in. You should not call mixpanel.alias() in this situation. Even though we have never seen Sally on this device before, she is not a new user. If you did try to alias, Mixpanel would attempt to map the email to the random Mixpanel distinct_id from the phone; instead, what you want is that alias to be associated with the original Mixpanel distinct_id, in this case 12345, where all of Sally’s actions are already stored. To do that, you would simply call mixpanel.identify().

Additional resources on managing user identities in Mixpanel

Developer documentation for managing user identity using: