Overview

Identity resolution involves linking and matching an individual's attributes from different data sources to create a unified identity representation. It combines various data elements to establish connections and create a comprehensive view of the user. Resolving these users into a single user profile enables marketers to accurately segment and personalize the users based on the data collected across various online and offline resources and avoid duplication.
The Identity Resolution feature of MoEngage allows you to integrate multiple profiles of the same user using different identifier attributes (such as ID, EmailID, Mobile Number, etc.) obtained from various online and offline data sources (ingested into MoEngage via Data APIs, MoEngage SDKs, and CSV files). When multiple sources include clear identity information, such as a customer ID, email ID, or phone number, you can utilize these attributes as identifiers to build a single unified customer profile in MoEngage. This maintains a single source of truth for each user, allowing you to seamlessly track their behavior on your application and set your business strategies accordingly.

Use Cases

Identity resolution plays a critical role in the following scenarios:

• A user browses a public listing page on a brand's website, providing their email ID (tracked as Email ID attribute in MoEngage) and phone number (tracked as Mobile Number (standard) user attribute in MoEngage). While buying a product at the brand offline store, the same user uses their phone number to complete their purchase. The brand aims to link the browsing activity on the website to the user who purchased at the store using their phone number.
• A brand offers multiple user registration methods such as email login, mobile OTP, and social media logins like Facebook. However, these methods generate different user profiles for the same individual. The brand aims to consolidate these multiple profiles into a single unified profile as it gathers additional information when the user engages in further activities.

Configure Multiple Identifiers

The first step in using Identity resolution is to activate the right set of user attributes as identifiers. You can configure up to five identifiers at a workspace level. The standard user attribute ID is set as the default identifier. You can opt to configure other user attributes, such as email and mobile number, as additional identifiers. Note that at least one identifier must be active at any given time.

For example, if you choose email ID and mobile number as identifiers, MoEngage checks the email ID and mobile number for all users. In cases where multiple users share the same mobile number but have distinct email IDs, the system consolidates those users into a single profile as one of the identifier values matches successfully.

When comparing user profiles, if there are conflicting values, the system will prioritize and consider the values from the user profiles with the latest last-seen timestamp (by default behavior that can be changed) during the merging process. This prioritized profile is called the retained profile, and the de-prioritized profile is called the merged profile. The merged profile is deleted after the events and user attributes are transferred to the retained profile.

Perform the following steps to configure multiple identifiers in the MoEngage dashboard (Only Admins can view and access Identity resolution):

1. On the left navigation menu in the MoEngage dashboard, go to Settings > Data > Identity resolution.
2. On the Identity resolution page, click +Add identifier(s). You can add up to five identifiers for identity resolution.
   
   1. By default, ID is listed as an identifier for merging user profiles using identity resolution. The Active tag represents the identifier currently used for identity resolution for merging users in your current workspace.
   2. All the identifiers added are listed on this page. Click the ellipsis icon () to perform the following:
      1. Pause identity resolution: This option allows you to pause merging the user based on that identifier.
          
      2. View/Edit exceptions: This option allows you to view or edit exceptions of that identifier. In the View/Edit exception dialog box, select the exception from the list and click Save.
         
3. The Merge settings option takes you to Step 2: Review merge rules.
4. On the Add identifier(s) page, you can perform the following steps:

Step 1: Select Identifiers

1. Select the checkbox next to the User attributes you want to select as identifiers for identity resolution.
2. You can view the Description for each attribute.
3. Exceptions: MoEngage does not ingest user attributes with exceptional values detected in their Identifier user attributes. As identifiers are used to uniquely identify users, values that do not achieve this distinctiveness, such as null and blanks, are excluded from the system. These values are set as exceptions by default and cannot be edited or removed. You can add additional exceptions, provided they are in string format.
4. You can view the various Data sources from which these identifiers are obtained. If an identifier is collected from multiple data sources, selecting that identifier for identity resolution is advantageous. This approach enhances the reliability of the identity-matching process across various channels.
5. The Tracked data types denote the various data types for which the data for that attribute has been tracked in MoEngage so far.
   

   info	Information User attributes of type String are supported to be activated as identifiers. User attributes of any other data type selected as identifiers are converted to String for existing data and incoming data.

6. Click Next.

Step 2: Review Merge Rules

1. Profile retention rules: This rule decides which user profile should be the retained profile. Perform the following steps to add profile retention rules:
   1. In the Rule 1 list, select a user attribute. The user profile containing any data for the selected user attribute will be considered as the retained profile. If Rule 1 is validated successfully, the retained profile is selected based on Rule 1. If Rule 1 fails to break the tie in cases where both users to be merged have data points for the selected user attribute, Rule 2 will be used. Rule 1 is an optional rule and by default is empty.
   2. In the Rule 2 list, select a user behavior. Based on the selected user behavior, the user profile containing that behavior is considered a retained profile. By default, Latest Last Seen is auto-populated and used to select the retained user profile. Note that Rule 2 is executed only if Rule 1 fails.
      For example, consider you have two customer profiles for the same user in which Profile 1 is received online, and Profile 2 is received offline.
      Scenario 1: The profile with data in the selected attribute is considered a retained profile.
      • Profile 1 has attributes such as ID, name, email ID, and mobile number. All these attributes contain data.
      • Profile 2 has attributes such as ID, name, email ID, and mobile number. All attributes contain data except for ID.
        If the attributes received online (Profile 1) are more accurate than offline (Profile 2) and you want Profile 1 to be considered a retained profile, select ID in the Rule 1 list. During merging, the system selects the profile that contains data for the ID attribute. Here, Profile 1 has data for ID, so it will considered as the retained profile.
      Scenario 2: When both the profiles have data in the selected attribute, Rule 1 fails, and Rule 2 is validated.

1. • • • • Profile 1 has attributes such as ID, name, email ID, mobile number, and first seen. All these attributes contain data.
         • Profile 2 has attributes such as ID, name, email ID, and mobile number, and first seen. All these attributes contain data.
           If you select ID in the Rule 1 list, Rule 1 fails as both Profile 1 and Profile 2 contain data for ID. So, Rule 2 gets validated.
           If you select Latest last seen in the Rule 2 list, the profile containing the latest last seen is considered a retained profile.
           
2. Attribute rules: This rule allows you to merge the data of your custom user attributes. Note that you can add a maximum of five attribute rules. By default, LTV (one of the MoEngage derived user attribute) is shown as an example where MoEngage takes the sum of LTV values of the 2 user profiles getting merged, the final resolved user profile will have the total sum of the LTV value of both the retained user and the merged user. Perform the following steps to add your own custom user attribute rules:
   1. Click Add rule.
   2. Select User attributes and Merge rules.
      For example, consider you have two customer profiles for the same user in which Profile 1 is received online, and Profile 2 is received offline. Each profile has a Loyalty_points attribute and has data in it, and if you want the SUM of both Loyalty_points when both these profiles are merged, perform the following:
      1. Select Loyalty_points in User attribute list.
      2. Select Sum of values in Merge rules list.
         So, whenever user profiles are merged, the resulting unified profile includes the Loyalty_points attribute, which comprises the combined sum of the Loyalty_points data from both profiles.
         
3. The Verify merge section shows how users are merged based on the profile retention and attribute rules you configured. Select I have verified all merge scenarios checkbox after verifying the merge scenarios.
   
4. Click Next.

Step 3: Activate Identity Resolution

This step provides the instructions to be considered before and after activating the identity resolution.

Irreversible changes to be considered before activating Identity resolution. The changes include:

• A user merged cannot be unmerged.
• For 48 hours after activation, the following actions are not possible on the Identity resolution page:
  • Adding new identifiers
  • Pausing, re-activating, and adding exceptions to existing identifiers
  • Changing Merge settings

After activating identity resolution:

• Existing users in the workspace merge over 48 hours
• New incoming users merge with existing users based on profile retention rules

Select By activating identity resolution, I understand the impact of merging the user check box and click Activate to activate identity resolution.

Data Ingestion Support

Following are the methods by which you can ingest data into MoEngage using multiple identifiers:

• Data APIs
• SDK
• File Imports

Data APIs:

In MoEngage, data ingestion uses an ID to create or update a user. For workspaces in MoEngage with Identity Resolution enabled, Data APIs (Track User, Create Event, Bulk Import) can be used to create or update users using a specific identifier, such as a mobile number or email ID, as configured.

You can:

• Create users through Server-to-Server Data APIs even when they do not have an ID (but have other identifiers).
• Create a user or track events of a user when identifiers other than ID (for example, email ID or phone number) are known.

Request Body

The following is a sample cURL request for a Bulk Import API consisting of the following payloads:

• User payload:  Attribute parameters must contain at least one of the identifiers you have configured based on which users in MoEngage will be created, updated, or merged.
• Event payload: Identifiers set up in the workspace must be mentioned within the user_identifiers parameter, as shown in the below example where moe_mobile is one of the identifiers in the workspace:
  
  JSON

  "user_identifiers":{
      "moe_mobile":"{{Mobile_Number}}"
  }

Sample cURL Request for Bulk Import API:

The following Bulk Import API consists of payloads for users and events. 

curl --location 'https://api-xx.moengage.com/v1/transition?app_id=O7NIHY0AT1K1FL8DR1J1' \

      --header 'Content-Type: application/json' \

      --header 'Authorization: Basic {{Authorization_Key}}' \

      --data '{

        "type": "transition",

        "elements": [


        {

          "type": "customer",

          "attributes": {

            "moe_mobile": "{{Mobile_Number}}",

            "first_name": "John"

          }

        },


        {

          "type": "event",

          "user_identifiers": {

            "moe_mobile": "{{Mobile_Number}}"

          },

          "actions": [

          {

            "action": "AddToCart",

            "attributes": {

              "product": "MacBook Air",

              "Brand": "Apple"

            }

          }

          ]

        }

        ]

      }'

SDK

Supported SDKs where Identity resolution changes are available:

• Android (13.6.00)
• iOS (9.23.0)
• WebSDK
• ReactNative
• Flutter

identifyUser() function is introduced in the new SDK versions that are compatible with Identity resolution. This function is a direct replacement of the SetUniqueID function and allows you to track users with multiple identifier attributes. Make sure to configure these identifiers in MoEngage before IdentifyUser function is implemented.

The following are examples of SDK sample codes where email and id are set as identifiers in a given workspace.

Sample Codes

MoEAnalyticsHelper.identifyUser(context, "android-native-uid")
MoEAnalyticsHelper.identifyUser(
    context,
    mapOf(
        "email" to "android@moengage.com",
        "id" to "android"
    )
)

MoEngageSDKAnalytics.sharedInstance.identifyUser(identity: "ios-native-uid")
MoEngageSDKAnalytics.sharedInstance.identifyUser(identities: [
    "email": "ios@moengage.com",
    "id": "ios"
])

Moengage.identifyUser({
  uid: 'uid1',
  email: 'email1@someEmail.com'
})

ReactMoE.identifyUser("react-native-uid");
ReactMoE.identifyUser({
    "id": "react-native",
    "email": "react-native@moengage.com"
})

final MoEngageFlutter _moengagePlugin = MoEngageFlutter(WORKSPACE_ID);
_moengagePlugin.identifyUser("flutter-uid");
_moengagePlugin.identifyUser({
    "email": "flutter@moengage.com",
    "id": "flutter"
})

File Imports

You can view the multiple identifiers configured for your workspace in the following sections:

User Imports in Segment

• If you have configured multiple identifiers for a given workspace, you can see them in the Map identifiers section in Step 2 while creating new user imports. You can only see ID under the Map identifiers section if multiple identifiers are not configured in this workspace. 
  
  

  info	Information The uploaded CSV must have at least one column with data matching any identifiers configured in MoEngage. After activating your identifiers in the workspace, please edit your existing periodic imports to map the identifiers to the right CSV column.

• For Anonymous user import, when the multiple identifiers feature is enabled for a MoEngage workspace and if an identifier user attribute is selected as an anonymous ID, the users from the import may merge with the existing users having the same identifier value. For example, if you have configured an email ID as an identifier and, while mapping identifiers, you choose an email ID as the anonymous ID, there is a chance that users from the import may merge with other users having the same email ID.
  

Data Imports in Data

• While creating a new user data import, if you have configured multiple identifiers for a given workspace, you can see them in the Map identifiers section while creating new user imports. You can only see ID under the Map identifiers section if multiple identifiers are not configured in this workspace. 
• If you have configured multiple identifiers for a given workspace while creating a new event data import, you can see them in Step 2: Import configuration and action under the Map identifiers section while creating new event imports. If multiple identifiers are not configured in this workspace, you can only see ID and Event time under the Map identifiers section.
  
  

  info	Information The uploaded CSV must have at least one column with data matching any identifiers configured in MoEngage.

   
• While creating new auxiliary data imports 
  In Step 2: Import configuration and action, when you turn on the Update user profile attributes (optional) toggle, you can view the multiple identifiers for that workspace in the Map identifiers section. You can only see ID under the Map identifiers section if multiple identifiers are not configured in this workspace.
  

Impact of Merging Users

The following are the effects of user merging on various campaigns and channels:

On Data

• User attribute info: When merged, all user attribute information of the retained user is retained. If user attributes in merged users do not exist in retained users, those attributes are transferred to the retained user profile.

• Device info: When merged, all devices are merged into the retained user, and no device information is lost.
• Events info: All events of the merged user are transferred to the retained user, hence no events are lost during a user-merge. The resolved user will have events of all the merged users.
• Other data callouts: Users cannot be un-merged after merging. Be careful when configuring identifiers for your workspace.

On Segment

• Active segments: When users are merged, the total number of users in active segments may decrease because users are merged into a single profile.
• Custom segments: Whenever the custom segment is updated, the user count may change.

On Campaign

• User merging may impact the overall reachability number. When merged, the contact details of the merged user will be lost, and hence, a campaign’s overall reachability may be reduced. This also impacts the overall campaign stats.
• Only Data APIs (TrackUser, CreateEvent, BulkImport API) support tracking users with multiple identifiers. Other APIs in MoEngage may still require ID at the moment.

Reachability Impact

Enable Multi-ID in Shopify