Tracking User Attributes and User Identity

Identity Management

Setting identifiers is important to:

Tie user behavior across platforms.
Ensure unnecessary or stale users are not created.
Identify users across installs and re-installs.

Call the API below to pass the identifier to the MoEngage SDK.

var moe = MoECordova.init(YOUR_WORKSPACE_ID);
moe.identifyUser("identifier");

This method replaces the deprecated setUniqueId() and setAlias(). If you are using either of these methods, replace them with identifyUser().
The following values are not allowed in the identifier field: unknown, guest, null, 0, 1, true, false, user_attribute_unique_id, (empty), na, n/a, "", dummy_seller_code, user_id, id, customer_id, uid, userid, none, -2, -1, 2.

If your application has multiple identifiers for a user, pass all identifiers to the SDK using the API below.

var moe = MoECordova.init(YOUR_WORKSPACE_ID);
moe.identifyUser({ "identifierName1": "identifierValue1", "identifierName2": "identifierValue2" });

Use the standard identifier keys below when passing common attributes as identifiers:

User attribute	Key
ID	`uid`
Email	`u_em`
Gender	`u_gd`
Birthday	`u_bd`
Name	`u_n`
First name	`u_fn`
Last name	`u_ln`
Mobile number	`u_mb`

For custom identifiers, use any key name that is not in the reserved keywords list. Behavior of multiple identifyUser() calls:

If you call identifyUser() without logging out first, the existing logged-in user’s identifiers are updated.
If you call identifyUser() multiple times with different identifier names, the SDK appends the new identifier to the already set identifiers. Refer to the Identity resolution documentation to learn more.
For workspaces with Identity resolution enabled, the SDK stores previous identifier values and detects changes when identifyUser() is called with new values.

If a network issue prevents the identifier from reaching the MoEngage server, the SDK caches the identifyUser() call and retries automatically once the network is available or the next time the app opens.

To enable or disable the SDK and data tracking, refer to Compliance.

Forced Logout: The MoEngage SDK no longer automatically merges or logs out the previous user when a new user is detected on the device. Call logout() explicitly before identifying a new user to avoid data corruption.

Logout

The application needs to notify the MoEngage SDK whenever the user is logged out of the application. Call the API whenever the user is logged out of the application to notify the SDK.

var moe = MoECordova.init(YOUR_WORKSPACE_ID);
moe.logout();

Logout clears the data and identity of the current user on the device and resets the SDK state. Call identifyUser() again when the next user logs in. For how identifiers map to user profiles, refer to Identity resolution.

Logout Callback Listener

Clearing user data and resetting the SDK state is an asynchronous process. Wait for the SDK to complete logout before navigating the user away or clearing your app’s local state. Register a listener for the onLogoutComplete event to detect successful logout.

var moe = MoECordova.init(YOUR_WORKSPACE_ID);
moe.on('onLogoutComplete', function (payloadInfo) {
    console.log("Received callback 'onLogoutComplete', data: " + JSON.stringify(payloadInfo));
});

Minimum plugin version required: Core 10.1.0.

Logout Callback Data

The onLogoutComplete callback receives the following payload:

{
  "type": "MoELogoutComplete",
  "accountMeta": {
    "appId": ""
  },
  "platform": "android/ios"
}

type - Event type that triggered the callback. Always MoELogoutComplete for logout.
accountMeta.appId - The Workspace ID of MoEngage.
platform - Native platform from which the callback is triggered. Possible values - android, ios

SDK User Attributes Keys

You can also set the default user attributes like mobile number, gender, user name, birthday, location, etc using the below APIs

var moe = MoECordova.init(YOUR_WORKSPACE_ID);
moe.setUserName("abc");
moe.setFirstName("abc");
moe.setLastName("xyz");
moe.setEmail("[email protected]");
moe.setPhoneNumber(1234567890);
moe.setGender("Male"); // OR Female
moe.setLocation(25.23, 73.23);
// Format - ISO-8601 String
moe.setBirthdate("1970-01-01T12:00:00Z");

For setting custom user attributes, use the method setUserAttribute(key, value).

var moe = new MoECordova.init(YOUR_WORKSPACE_ID);
moe.setUserAttribute("<attribute_name>", "<attribute_value>");

Date attributes and Birthday in ISO-8601 format -yyyy-MM-dd’T’HH:mm:ss’Z’

var moe = MoECordova.init(YOUR_WORKSPACE_ID);
moe.setUserAttributeLocation("attribute", 25.23, 73.23);

You can use the following method set the timestamp user attribute :

var moe = MoECordova.init(YOUR_WORKSPACE_ID);
moe.setUserAttributeISODateString("LastPurchaseDate", "1970-01-01T12:00:00Z");

You can not use “moe_” as a prefix while naming events, event attributes, or user attributes. It is a system prefix and using it might result in periodic blacklisting without prior communication.

Custom Boolean User Attribute

iOS(optional)

Starting from version 9.x.x of cordova-moengage-core, the default tracking for the custom boolean attribute will be changed to boolean(true/false) from double(0/1). To configure this, use analyticsConfig with shouldTrackUserAttributeBooleanAsNumber and pass true to track the boolean as double. By default, this is set as false to track boolean as true/false Refer to the initialization code snippet below.

let initializationConfig = {analyticsConfig: {shouldTrackUserAttributeBooleanAsNumber: true}};
var moe = MoECordova.init(YOUR_WORKSPACE_ID, initializationConfig);

Refer to the example code below for tracking the boolean user attribute

var moe = new MoECordova.init(YOUR_WORKSPACE_ID); 
      
/// If shouldTrackUserAttributeBooleanAsNumber is passed as true then `boolean attribute True` will tracked with value 1 else true  
moe.setUserAttribute("boolean attribute True", true); 
      
/// If shouldTrackUserAttributeBooleanAsNumber is passed as true then `boolean attribute False` will tracked with value 0 else false  
moe.setUserAttribute("boolean attribute False", false);

Reserved keywords for User Attributes

Below is the list of keys that should not be used when tracking user attributes.

USER_ATTRIBUTE_UNIQUE_ID
USER_ATTRIBUTE_USER_EMAIL
USER_ATTRIBUTE_USER_MOBILE
USER_ATTRIBUTE_USER_NAME
USER_ATTRIBUTE_USER_GENDER
USER_ATTRIBUTE_USER_FIRST_NAME
USER_ATTRIBUTE_USER_LAST_NAME
USER_ATTRIBUTE_USER_BDAY
USER_ATTRIBUTE_NOTIFICATION_PREF
USER_ATTRIBUTE_OLD_ID
MOE_TIME_FORMAT
MOE_TIME_TIMEZONE
USER_ATTRIBUTE_DND_START_TIME
USER_ATTRIBUTE_DND_END_TIME
MOE_GAID
INSTALL
UPDATE
MOE_ISLAT
status
user_id
source

​Identity Management

​Login with a Single Identifier

​Login with Multiple Identifiers

​Logout

​Logout Callback Listener

​Logout Callback Data

​SDK User Attributes Keys

​Custom Boolean User Attribute

​iOS(optional)

​Reserved keywords for User Attributes

Identity Management

Login with a Single Identifier

Login with Multiple Identifiers

Logout

Logout Callback Listener

Logout Callback Data

SDK User Attributes Keys

Custom Boolean User Attribute

iOS(optional)

Reserved keywords for User Attributes