Assigning Your Own Unique IDs to Users

Managing identity (distinct_id) yourself.

User identification in Mixpanel is handled through a property called "distinct_id." Distinct_id must be sent with every event that you wish to tie to a user.

There are advantages to managing distinct_id yourself. Most importantly, it allows you to track the same user across platforms, browsers, and between server and client side events. In our JavaScript, Android , iOS , and Actionscript libraries you can manage this process through the use of super properties (via the identify functions). Super properties are simply properties that are appended by the library onto every event for a given user automatically. When sending server side events, however, you must keep track of which distinct_id value to send with each event on your own.

Identifying users from our JS/AS3 or mobile libraries

If you are sending events from a library that supports super properties, then you can assign a distinct_id value to a user by calling the identify method. When you identify a user, it changes the value for distinct_id in that user's super properties. This means that every subsequent event sent by that user will be attributed to the new id. This does not mean that events previously sent by that user will be attributed to the new id. They will remain in our system with the old id and cannot be edited.

Use caution when employing the identify method since it may break a funnel or diminish totals on a retention report. If, for instance, you identify a user in the middle of a funnel, the funnel will appear to break or under-report since Mixpanel will no longer be able to follow one distinct_id value through the entire sequence of events for that user. Identifying a user with the same distinct_id value they already have does not cause issues.

The most common place to use the identify method is when a user authenticates. In most cases you are simply calling the same distinct_id value that the user already has, which is fine. The goal is to ensure that all authenticated behavior is properly attributed to a given user regardless where they are located. However, it is true that for users who return with a new distinct_id value, the pre-authentication events will not be associated with the post authentication events. Luckily, in most cases the only funnel that spans both unauthenticated and authenticated events is your sign-up funnel, which can be accommodated using our aliasing feature.

Using Alias

Currently the Alias method is available for the JavaScript, iOS, and Android libraries (and for HTTP requests using the special "$create_alias" event). Alias allows you to continue using one distinct_id value throughout your signup funnel (and forever more) despite the fact that you'd like to begin using your internal value for distinct_id going forward. When you call alias, mixpanel will create a look-up table for the value you alias to. All subsequent events sent bearing that distinct_id will have their distinct_id values over-written with the original value that had been sent by the user before alias was called. More on alias here.

Important: do not fire alias every time a user authenticates. This is not how the method is designed to be used and will only cause problems. Alias should be called exactly once per user, at signup.

Identifying a user via HTTP

Since distinct_id is simply a property sent with every event to Mixpanel, there is no way to identify a user via HTTP. The Identify method makes a local change to the list of properties that get appended onto every subsequent event. If you would like to "identify" a user via HTTP, all you have to do is begin sending events with the desired distinct_id included in the properties.

Aliasing a user via HTTP

You can alias a user via HTTP by emulating the call being made by the JS library. It looks like this (before it's encoded to base64):

    {
    "event": "$create_alias",
    "properties": {
        "alias": "123"
        "distinct_id": "123456789ABCDEF0=="
        "time": 1362068619,
        "token": "our-token"
        }
    }

The above JSON is dispatched in the data param in a call to our track endpoint. More on sending requests to the track endpoint here. The "distinct_id" param here is the pre-alias distinct_id, and the "alias" param is the alias to be added to the lookup table for that user.