Spec: Alias

The Alias method is an advanced method used to merge 2 unassociated user identities, effectively connecting 2 sets of user data in one profile.

Syntax

The Alias call has the following fields:

The Alias method follows the format below:

analytics.alias(userId, [previousId], [options], [callback]);

Here’s the payload of a basic Alias call that will associate this user’s existing id (email address) with a new one (a database ID), with most common fields removed:

{
  "type": "alias",
  "previousId": "jen@email.com",
  "userId": "507f191e81"
}

Here’s the corresponding JavaScript event that would generate the above payload. If you’re using Segment’s JavaScript library, Segment automatically passes in the user’s anonymousId as previousId for you:

analytics.alias("507f191e81");

If you’re instrumenting a website, the Anonymous ID is generated in the browser so you must call Alias from the client-side. If you’re using a server-side session ID as the Anonymous ID, then you must call Alias from the server-side.

Examples

Here’s a complete example of an Alias call:

{
  "anonymousId": "507f191e810c19729de860ea",
  "channel": "browser",
  "context": {
    "ip": "8.8.8.8",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/40.0.2214.115 Safari/537.36"
  },
  "integrations": {
    "All": true,
    "Mixpanel": false,
    "Salesforce": false
  },
  "messageId": "022bb90c-bbac-11e4-8dfc-aa07a5b093db",
  "previousId": "39239-239239-239239-23923",
  "receivedAt": "2015-02-23T22:28:55.387Z",
  "sentAt": "2015-02-23T22:28:55.111Z",
  "timestamp": "2015-02-23T22:28:55.111Z",
  "type": "alias",
  "userId": "507f191e81",
  "version": "1.1"
}