Search results for "{{ search.query }}"

No results found for "{{search.query}}". 
View All Results

Tracking users

All user related APIs are part of WebEngage Web SDK's user object.

Identifying users

WebEngage SDK automatically creates a unique ID (LUID) which the WebEngage backend uses to uniquely identify users. These are “anonymous” profiles to which you can assign unique User IDs (CUID). Assigning a CUID helps collect the user's activity and information across systems in a single unified profile.

A user profile's ID once assigned, cannot be changed. Although ID can be any String that uniquely identifies users in your system, we recommend using system generated user IDs from your database instead of information that can change over time such as email addresses, usernames or phone numbers.

The usual places to assign IDs are

  • On user signups
  • On user logins
  • On screen or page views where user identity becomes known
  • When the user context changes


  • An ID can be of maximum 100 characters.

You can assign an ID by calling the login method. All attributes, events and session information accumulated before this API has been called get associated to an anonymous user created by default. Once login is called, all of this stored information is attributed to this identified user.


Make sure you call login as soon as the user logs in to your application, or whenever earliest you are able to identify the user.


Make sure you call logout when the logged-in user logs out, or you do not want to attach any future event, session or user data with this user, until login is called again.

User attributes

There is often additional identifying information, such as name and email address, associated with user profiles. WebEngage provides setters for assigning these attributes to users. These attributes can be used to segment users and target campaigns to a specific group. Additionally, they can be referred to personalize campaign messages to each user.

Attributes can be set on “anonymous” profiles as well.

Each session has its own user attributes, but they get copied from one session to the next. This is in contrast to event parameters, which may take on different values per event. For this reason, you generally use user attributes for things that do not change much within the session, or with which you want the entire session associated.

Setting system attributes


  • String type attribute values must be less than 1000 characters long. Any characters beyond that will be truncated.


webengage.user.setAttribute('we_email', '');

Hashed Email

If you are averse to passing your users' personally identifiable information, WebEngage enables you to pass hashed email IDs and to set up private Email Service Provider API endpoints at your end.

webengage.user.setAttribute('we_hashed_email', '144e0424883546e07dcd727057fd3b62');

Birth Date in yyyy-mm-dd format

webengage.user.setAttribute('we_birth_date', '1986-08-19');

Phone Number

webengage.user.setAttribute('we_phone', '+551155256325');

The String we_phone must be in E.164 format, eg. +551155256325, +917850009678.

Hashed Phone Number

If you are averse to passing your users' personally identifiable information, WebEngage enables you to pass hashed phone numbers and to set up private SMS Service Provider API endpoints at your end.

webengage.user.setAttribute('we_hashed_phone', 'e0ec043b3f9e198ec09041687e4d4e8d');


webengage.user.setAttribute('we_gender', 'male');

Gender values can be one of male, female or other.

First Name

webengage.user.setAttribute('we_first_name', 'John');

Last Name

webengage.user.setAttribute('we_last_name', 'Doe');


webengage.user.setAttribute('we_company', 'Alphabet Inc.');

Opt In Status

You can set the subscription preference of your users (for SMS, Email and Web Push) using the methods described below. Users who are opted out of a particular channel will not receive any communication on that channel. Users are by default opted into all channels. Setting setOptIn to false for a particular channel opts the user out of that channel.

webengage.user.setAttribute('we_email_opt_in', true); //Email

webengage.user.setAttribute('we_sms_opt_in', true); //SMS

webengage.user.setAttribute('we_push_opt_in', true); //Web Push

You can use setAttribute to attach custom attributes to the user as well. These data types are allowed for below APIs: String, Number, Boolean, Date, Array, Object. Array can contain one of these data types.


  • Attribute names must be less than 50 characters long. String type attribute values must be less than 1000 characters long. Any characters beyond that will be truncated.
  • In addition to the system attributes, you can create at most 25 user attributes of each data type.
  • You cannot start your attribute names with we_.
  • If attribute value is Array or Object, it cannot be used to create user segments. It can only be used to personalize campaigns.

String attribute

webengage.user.setAttribute("Category", "GOLD");

Number attribute

webengage.user.setAttribute("Value Index", 5.06);

Boolean attribute

webengage.user.setAttribute("Inactive", false);

Date attribute

webengage.user.setAttribute("Registered On", new Date("2015-11-09T10:01:11.000Z"));

Array attribute

The Array attribute value must not contain any data type other than ones specified above.

webengage.user.setAttribute("Contact Numbers": [

1. User attribute names are case sensitive.
2. Attribute name must not start with we_. Attribute names starting with we_ are reserved for WebEngage's internal use, and will be ignored if used for custom attributes.
3. For custom user attributes, the first datapoint synced to WebEngage defines the data type for that attribute in WebEngage. Therefore, data types must be consistent with the data that you want to store for the attribute. If you change the data type later, attribute data will stop flowing to WebEngage.

You can define multiple user attributes in one go using JavaScript Object. The keys of this Object will be attribute names and values will be respective attribute values. These attribute values must be one of the above specified data types or Object.

    /* System attributes */
    "we_first_name" : "John",
    "we_last_name" : "Doe",
    "we_email" : "",
    "we_gender" : "male",

    /* Strings */
    "Category" : "GOLD",

    /* Numbers */
    "Value Index" : 5.06,

    /* Booleans */
    "Inactive" : false,

    /* Dates */
    "Registered On" : new Date("2015-11-09T10:01:11.000Z"),

    /* arrays */
    "Contact Numbers": [

    /* Objects */
    "Address": {
        "Flat"     : "Z-62",
        "Building" : "Pennant Court",
        "Locality" : "Penn Road",
        "City"     : "Wolverhampton",
        "State"    : "West Midlands",
        "PIN"      : "WV30DT"


What's Next

Tracking events

Tracking users