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 - |
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
Moengage.identifyUser({ u_em: 'emailValue@emailDomain.com', uid: UNIQUE_ID }).then(() => { |
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.