Web SDK User Attributes Tracking

Track user attributes like email, name, and gender on your website using the MoEngage Web SDK.

MoEngage highly recommends using the optional step for MoEngage Web SDK integration.

User attributes are specific traits of a user such as an email, username, mobile, gender and so on. User Attributes helps target users based on these attributes across devices or installs or to personalize the messages.

Pre-defined Attributes

Use the following MoEngage methods to make use of the standard user attributes.

JavaScript

Moengage.add_first_name("Dominick");
Moengage.add_last_name("Cobb");
Moengage.add_email("[e-mail]");
Moengage.add_mobile("[phone]");
Moengage.add_user_name("Dominick (Dom) Cobb"); // Full name for user
Moengage.add_gender("M");
Moengage.add_birthday(new Date(1980, 2, 31));

Custom Attributes

JavaScript

	// string
	Moengage.add_user_attribute("ATTRIBUTE_NAME_1", "value");
	// Integer - Numeric
	Moengage.add_user_attribute("ATTRIBUTE_NAME_2", 1);
	// Double - Numeric
	Moengage.add_user_attribute("ATTRIBUTE_NAME_3", 5.99);
	// Date
	Moengage.add_user_attribute("ATTRIBUTE_NAME_4", new Date(2021, 2, 10));
	// Boolean
	Moengage.add_user_attribute("ATTRIBUTE_NAME_5", false);
	// Arrays can be only in string or in number format.
	// Array (all items should be of same data type)
	Moengage.add_user_attribute('colors', ['blue', 'green', 'red']);
	// Array (all items should be of same data type)
	Moengage.add_user_attribute('ids', [77892, 1123, 3311]);
	 
	// Object (upto 2 levels and maximum payload size of 150 KB is supported)
	 
	// The value of the highest-level key has to be of primitive JavaScript type or Date
	Moengage.add_user_attribute('someCustAttr', { 'key1': { 'subKey1': 'someVal1', 'subKey2': true, 'subKey3': 125676, 'subKey4': new Date() }, 'key2': [1, 4, 5, 3] });

User Login and Logout

ID is used to uniquely identify a user within the MoEngage dashboard.

Ensure log in and log out of users are implemented correctly during the visit to your website and users are authenticated.

If the user log in and log out is not handled correctly, user data may get corrupted.

When you go live with MoEngage web SDK for the first time, ensure that you are setting the ID of your existing website users on page load.

As soon as the user is authenticated, ensure that the user id is passed on to the MoEngage SDK using the login method. After the user logs out of your app, ensure to call the logout method of MoEngage.

Use the following MoEngage methods on user login, user log out and user update:

Log In

For SDK versions below 2.52.2 refer to this document.

Please ensure that you are using the latest integration script before using the below MoEngage methods.

JavaScript

/** if a single argument is passed into identifyUser method, it will be treated as ID */
Moengage.identifyUser(UNIQUE_ID); // UNIQUE_ID is used to uniquely identify a user
/** if email has been chosen as identity */
Moengage.identifyUser({ u_em: '[e-mail]' });
/** if mobile has been chosen as identity */
Moengage.identifyUser({ u_mb: '7777777777' });
/** you can set two or more identities at the same time */
Moengage.identifyUser({ u_em: '[e-mail]', u_mb: '7777777777', uid: 'unique_id_value' });

Information

Updates are made to SDK functions to improve user identification and session management.

• Forced Logout: The MoEngage SDK no longer automatically logs out the previous user when a new user is detected on the device. Logout should now be explicitly called for workspaces enabled with Identity resolution to avoid data corruption.
• SetUniqueID: IdentifyUser function supports multiple identifiers, which replaces the need of using SetUniqueID function for user identification. Note that SetUniqueID is marked for removal in the future releases of SDK versions - it is important to use identifyUser instead especially if you are using Identity resolution in your workspace.
• SetAlias: For workspaces with the Identity resolution feature enabled, MoEngage SDK stores the previous identifier values. When IdentifyUser function is used to track the new identifier values, MoEngage SDK detects the change in identifier value and reports accordingly.
• If you call the IdentifyUser function without logging out, then the existing logged-in user’s ID is updated.

Refer to our help document to learn more about the feature.

Here, u_em, u_mb, uid are standard user attributes. Please refer to the below table to identify user with standard user attributes:

User Attribute Name	Key name to be used in identifyUser method
ID	uid
Email (Standard)	u_em
Gender	u_gd
Birthday	u_bd
Name	u_n
First Name	u_fn
Last Name	u_ln
Mobile Number (Standard)	u_mb

You can identify a user with custom user attributes as well if the same have been chosen as identities in your MoEngage dashboard.

JavaScript

	/** replace custom_attribute_name with the actual name of your custom user attribute and attributeValue with the actual value you want to assign to the attribute */
	Moengage.identifyUser({ custom_attribute_name: 'attributeValue' });
	/** you can set two or more identities at the same time */
	Moengage.identifyUser({ cust_attr_1: 'value1', cust_attr_2: 'value2' });
	/** you can set custom user identity and standard user identity at the same time */
	Moengage.identifyUser({ cust_attr_1: 'value1', cust_attr_2: 'value2', u_em: '[e-mail]' });

If you want to retrieve the current state of identities set for the user, you can use the below method:

JavaScript

	Moengage.getUserIdentities();
	/**
	  returns an object with the user's current set identities and their values:
	  { u_em: '[e-mail]', u_mb: '7777777777', uid: 'valueOfID' }
	*/

Critical - Very Important Integration Guideline

Never use both the login methods - identifyUser and add_unique_user_id (login method of SDK versions below 2.52.2) in your project. Use only either one of the methods. Using both the methods can lead to inconsistent user profile creation and merging in your MoEngage account.

In order the get the value of a tracked user attributes, you can use the below method:

JavaScript

Moengage.getUserAttribute(ATTRIBUTE_NAME);
/**
  Pass the attribute name as the paramaeter and it will return the value of the attribute if present.
  Note: This method only returns locally tracked user attributes. if the user logs out and then logs in, the previously tracked attributes will not be fetched using this method.
*/

Log Out

Logs out the current user.

JavaScript

Moengage.destroy_session();

Update User

JavaScript

/** Set the ID for the first time */
Moengage.identifyUser(UNIQUE_ID);
/** Update the ID */
Moengage.identifyUser(NEW_UNIQUE_ID);
/** Set the identities for the first time */
Moengage.identifyUser({ uid: UNIQUE_ID, u_em: '[e-mail]', u_mb: '7777777777' });
/** Update the identities - you can update one or more identities. */
Moengage.identifyUser({ u_em: '[e-mail]', u_mb: '8888888888' });

Critical

identifyUser and destroy_session methods should be called in proper order. So make sure, you track other attributes after these methods are executed completely. Since these return promise, you can track data like this:

JavaScript

Moengage.identifyUser({ u_em: '[e-mail]', uid: UNIQUE_ID }).then(() => { 
  Moengage.add_mobile('7777777777')
});

Track User Attributes

Ensure that you are tracking user attributes in the following cases:

1. When a new attribute is set for a user. For example, set the Email Id or Mobile No. attribute for the user after a user logs in or signs up on the website.
2. When the value of an existing attribute is updated.
3. When you go live for the first time with MoEngage web SDK integration, ensure that you are passing the user attributes set for your existing website users after page load (if they are not already sent to MoEngage).
4. For more information on supported data types and data tracking policies, please refer to Data Tracking Policies.

Make sure that you are not using a single unique id for all the users, this is possible only when the unique id value is hardcoded, instead of retrieving from your servers.

Attribute tracking via Google Tag Manager (GTM)

You can follow the documentation at Google Tag Manager(GTM) to track attribute via GTM.

Tracking at the time of Redirection

In case of redirection to another page immediately after tracking attribute or events, make sure that the tracking is completed and then you redirect.

JavaScript

Moengage.identifyUser({ u_em: '[e-mail]', uid: UNIQUE_ID }).then(() => {
    window.open('[https://www.moengage.com](https://www.moengage.com)')
});

If you cannot wait for the tracking to complete and need to redirect immediately, then it is suggested to track the data on the next page after redirection.

User Attribute Caching

Duplicate User Attributes won’t be tracked for 6 hours.

For more information about the default attributes collected by MoEngage SDK, refer to Web SDK Data Collection.

For further assistance, please contact your MoEngage Customer Success Manager (CSM) or the Support team.