User Aliasing

Analytics supports several aliasing use cases. This topic describes the use cases and provides best practices for managing user aliasing.

Use Cases

Identity Reconciliation

Users interact with digital environments in many different ways. When a new user accesses your website or app, they are unknown, so a unique Anonymous ID is assigned to track their online behavior. Users may remain anonymous for the duration of their visit or they might create an account, log in, or otherwise share identifiable information. Once the user becomes known, it’s important to reconcile the known identity with any previously anonymous user identities, and to combine the activity timelines of each ID. This creates a unified user activity timeline and enables a complete analysis of the full customer journey. Without user reconciliation, an individual user may be assigned multiple user IDs, which can cause duplication of user counts and fragmentation of user activity in your data. The process of reconciling known and unknown user identities is called aliasing. Aliasing is also known as identity reconciliation, stitching, or merging. 

Cross-Device Identification

Users can access your website or app from a variety of devices and locations. Maybe a user creates a profile on your website using their laptop, then downloads your app onto their smartphone and also onto their tablet. Maybe they log in on a friend’s phone to place an order. In addition to reconciling known and unknown user identities, aliasing combines the activity timelines of each device, platform, and geographic location. This again creates a unified activity timeline to provide a complete analysis of the full customer journey.

Cross-Domain Tracking

Aliasing can also help with cross-domain tracking. To achieve this, pass the Anonymous ID from the second domain as an aliasing parameter. Then contact your Customer Success Manager for more information on how to enable cross-domain tracking with aliasing.

How Does Aliasing Work?

Depending on your integration type, aliasing is achieved in different ways. For example, if you send events to Analytics in real-time by using Segment, Amazon Kinesis, or via the Analytics API, the process is different than if you send events to Analytics daily through a data warehouse integration. The following documentation describes our process for aliasing user identities in real-time integrations.

An aliasing API call consists of three components: 

  1. Anonymous ID: The anonymous ID is an ID used to identify a user before they register, log in, or otherwise identify themselves.
  2. User ID: The user ID is the ID used to uniquely identify a user in your database. This should be an immutable field that is recorded in the user table. As mentioned, the user ID is created and assigned whenever a user makes themselves known. 
  3. API Key: The project API Key is used to direct the alias call toward which Analytics project.

After receiving an aliasing call, Analytics reconciles the anonymous ID and the user ID, and handles all incoming events from both IDs as the same user. In short, they’re “stitched” together. Multiple anonymous IDs may be aliased to a single user ID, however you may not alias multiple user IDs to a single anonymous ID, nor may you alias a user ID to another user ID. Alias calls are processed once per day, so please allow up to 24 hours for best results.

JavaScript (SDK) Alias Calls


The Analytics client automatically generates a universally unique identifier (UUID) to apply to all events until “Indicative.setUniqueID(id)” is called. “Indicative.sendAlias()” can be called to alias the UUID to the ID parameter defined within “Indicative.setUniqueID(id)”

Indicative.setUniqueID(id, true)

After setting the new unique ID, then this will automatically call “Indicative.sendAlias()”. If you perform “callIndicative.setUniqueID(id)” without ‘true’, then the alias call will not be sent.

Best Practices

It is recommended that an alias call be made once, at the first instance of the user identifying themselves, such as upon registration or profile creation. We also recommend caution, as improper use of aliasing can cause unforeseen issues with data accuracy. To mitigate this risk, Analytics enforces the following strict aliasing rules:

Anonymous ID and User ID must be different
Anonymous ID may be aliased to only one User ID
Multiple Anonymous IDs may be aliased to one User ID
Anonymous ID may not be aliased to another Anonymous ID
User ID may not be aliased to another User ID
If an ID has already been defined as a User ID, then it cannot be reclassified as a Anonymous ID
You may not “chain” alias calls (i.e. Anonymous ID > User ID1 > User ID2)
Alias calls only impact future data received. 
Aliasing is stateful, which means we build an accumulated view of your aliasing calls over time.

Event Aliasing from mParticle

When user profiles and events are sent from the mParticle CDP to Analytics, Analytics will inherit all aliasing functionality that was performed using IDSync. This means that Analytics automatically has access to the same unified view of user profiles and events established within mParticle. 

Retroactive aliasing

For customers on the Enterprise plan, alias calls can be performed retroactively to combine two activity timelines that have already been processed. Retroactive aliasing is useful when events performed anonymously before an aliasing API call is received need to be reconciled with a known user profile. Retroactive aliasing takes place once every 24 hours.

For example, consider the events below, all performed by the same customer:

  • Event 1: Customer views a registration page, establishing user_id A
  • Event 2: user_id A submits registration
  • Event 3: Customer successfully registers while using a different device, establishing user_id B
  • Aliasing API call is made, establishing that user_id A is user_id B
  • Event 4: user_id B views an ad
  • Event 5: user_id A views a login screen
  • Event 6: user_id B logs in successfully

In this sequence, only event 3 would need to be retroactively reconciled with the known user ID, while events 1, 2, 4, 5, and 6 would be immediately associated with the unified profile following the aliasing API call. Once daily retroactive aliasing is complete, the event in step 3 becomes associated with the same user profile as the rest of the events.

This diagram further illustrates retroactive aliasing:


Custom Aliasing

Custom aliasing rules may be supported for Enterprise customers only. This can be requested by contacting Support or your Customer Success Manager.

Third Party Aliasing

Aliasing calls from a third party are not supported. Analytics rejects these calls because they are considered “chained” alias calls (i.e. Anonymous ID > Third Party User ID > Indicative User ID). If you are concerned that your method of integration is causing aliasing issues, please contact Support or your Customer Success Manager.

Aliasing with GDPR

Under GDPR privacy regulations, users have the option to opt into or out of session tracking. If a user does not consent to tracking, then all personally identifiable information (PII) must not be collected and existing PII must be deleted. The only data that is tracked by the Analytics client is the Anonymous ID, a random string ID used to unify a single user session. This ID does not persist across multiple user sessions. It is not possible to alias the IDs of users who opt out of session tracking.

Was this page helpful?