Web SDK User Attributes Tracking

info	Note 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.

Moengage.add_first_name("Dominick");
Moengage.add_last_name("Cobb");
Moengage.add_email("dom@level5.com");
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.

warning

Warning

If the user log in 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.

info	Note 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: 'emailValue@emailDomain.com' });
/** 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: 'emailValue@emailDomain.com', u_mb: '7777777777', uid: 'unique_id_value' });

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.

/** 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: 'emailValue@emailDomain.com' });

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

Moengage.getUserIdentities();
/**
  returns an object with the user's current set identities and their values:
  { u_em: 'emailValue@emailDomain.com', u_mb: '7777777777', uid: 'valueOfID' }
*/

warning

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.

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: 'emailValue@emailDomain.com', u_mb: '7777777777' });
/** Update the identities - you can update one or more identities. */
Moengage.identifyUser({ u_em: 'updatedValue@emailDomain.com', u_mb: '8888888888' });

warning

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:


Moengage.identifyUser({ u_em: 'emailValue@emailDomain.com', 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.

info	Note 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: 'emailValue@emailDomain.com', uid: UNIQUE_ID }).then(() => {
    window.open('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.

To contact the MoEngage Support team, you can raise a ticket through the Support Web Form within the MoEngage dashboard. For more information, refer here.