40

Alias

How it works

An alias call helps you merge two user profiles—a userId and a previousId. The userId inherits the traits and activity of the previousId, so you can track activity going forward against the canonical userId.

Alias calls are typically useful in two situations:

1. You send data to a destination like Mixpanel that doesn’t automatically associate anonymous activity (under an anonymousId) with an identified person (a userId).
2. A person generates multiple user IDs and you need to unify them under a single userId value.

You should send the alias call immediately before the identify call for a person.

What comes first: alias or identify?

You should send the alias call immediately before the identify call for a person. This ensures that the anonymous activity is associated with the identified user before the identified user starts generating new activity.

Associating anonymous activity with a user ID

Most of our libraries and destinations automatically associate anonymous activity with a userId when you identify a person, so you won’t need to implement Alias calls. The main destination that doesn’t automatically associate anonymous activity with an identified user is Mixpanel. If you use Mixpanel, you’ll need to send Alias calls to associate anonymous activity with a userId.

You should send the alias call immediately before the identify call for a person. This ensures that the anonymous activity is associated with the identified user before the identified user starts generating new activity.

A typical call

A typical identify call is straightforward. It contains a userId and a previousId object. The userId is a person’s canonical identifier and the previousId is the identifier you want to remove or ignore in your downstream destinations.

analytics.alias("userId","previousId");

The full payload

While your requests are typically short, our libraries capture much more information. This helps us provide context, not only for the person you aliased, but the service you aliased them from.

Customer.io and our libraries typically populate integrations and timestamp values as shown in the payload below. If you use our JavaScript or mobile libraries, they’ll also populate context for you. If you use our server-side libraries, you’ll need to populate context yourself.

See common fields for more information about context, integrations, and timestamps in source payloads.

{
  "type": "identify",
  "userId": "97980cfea0067",
  "previousId": "97980cfea0067",
  "integrations": {
    "All": true
  },
  "messageId": "string",
  "receivedAt": "2019-08-24T14:15:22Z",
  "sentAt": "2019-08-24T14:15:22Z",
  "timestamp": "2019-08-24T14:15:22Z",
  "version": 0,
  "context": {
    "active": true,
    "ip": "string",
    "locale": "string",
    "userAgent": "string",
    "channel": "browser",
    "campaign": {
      "name": "string",
      "source": "string",
      "medium": "string",
      "term": "string",
      "content": "string"
    }
  }
}