MoEngage highly recommends using the optional step for MoEngage Web SDK integration.
Pre-defined Attributes
Use the following MoEngage methods to make use of the standard user attributes.
Moengage.add_first_name("Dominick");
Moengage.add_last_name("Cobb");
Moengage.add_email("[email protected]");
Moengage.add_mobile("+12399999999");
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
// 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. 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. /** 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: '[email protected]' });
/** 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: '[email protected]', u_mb: '7777777777', uid: 'unique_id_value' });
InformationUpdates 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.
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 |
/** 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: '[email protected]' });
Moengage.getUserIdentities();
/**
returns an object with the user's current set identities and their values:
{ u_em: '[email protected]', u_mb: '7777777777', uid: 'valueOfID' }
*/
Critical - Very Important Integration GuidelineNever 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.
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.
Moengage.destroy_session();
Update User
/** 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: '[email protected]', u_mb: '7777777777' });
/** Update the identities - you can update one or more identities. */
Moengage.identifyUser({ u_em: '[email protected]', u_mb: '8888888888' });
CriticalidentifyUser 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:Moengage.identifyUser({ u_em: '[email protected]', uid: UNIQUE_ID }).then(() => {
Moengage.add_mobile('7777777777')
});
Track User Attributes
Ensure that you are tracking user attributes in the following cases:
- 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.
- When the value of an existing attribute is updated.
- 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).
- 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.
Moengage.identifyUser({ u_em: '[email protected]', uid: UNIQUE_ID }).then(() => {
window.open('[https://www.moengage.com](https://www.moengage.com)')
});
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.
