Tracking Users

All user related APIs are part of WebEngage iOS SDK's WEGUser object. You get an instance of WebEngage WEGUser object as follows:

let weUser: WEGUser = WebEngage.sharedInstance().user
WEGUser* weUser = [WebEngage sharedInstance].user;

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 NSString 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.

[weUser login:@"9SBOkLVMWvPX"];

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.

//Available >= 3.4.12
[weUser logout];

//Deprecated >= 3.4.12, use login instead
[weUser loggedout];

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 user attributes


  • NSString type attribute values must be less than 1000 characters long. Any characters beyond these limits will be truncated.


weUser.setEmail("[email protected]")
[weUser setEmail:@"[email protected]"];

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.

//(Available >= 3.4.2)
[weUser setHashedEmail:@"144e0424883546e07dcd727057fd3b62"];

Birth Date

var comps = DateComponents() = 19
        comps.month = 08
        comps.year = 1996
        let date: Date? = comps)
//(Available >= 3.4.14, use setBirthDate for < 3.4.14)

NSDateComponents *comps = [[NSDateComponents alloc] init];
[comps setDay:19];
[comps setMonth:08];
[comps setYear:1996];
NSDate *date = [[NSCalendar currentCalendar] dateFromComponents:comps];

[weUser setBirthDate:date];

Birth Date in yyyy-mm-dd format

[weUser setBirthDateString:@"1986-08-19"]; //yyyy-mm-dd

Phone Number

[weUser setPhone:@"+551155256325"];

The NSString 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 phone numbers and to set up private SMS Service Provider API endpoints at your end.

//(Available >= 3.4.2)
[weUser setHashedPhone:@"e0ec043b3f9e198ec09041687e4d4e8d"];


[weUser setGender:@"male"];

First Name

[weUser setFirstName:@"John"];

Last Name

[weUser setLastName:@"Doe"];


weUser.setCompany("Alphabet Inc.")
[weUser setCompany:@"Alphabet Inc."];

Opt In Status

To set the subscription preference of your users (for Push, In-app, SMS, Email and WhatsApp) use setOptInStatusForChannel. Users who are opted out of a particular channel will not receive any communication on that channel. By default, users are opted in to Push, In-app, SMS and Email. The WhatsApp opt-in is false by default and you need to explicitly set it to true once you have received the opt-in permission from the user.

weUser.setOptInStatusFor(WEGEngagementChannel.push, status: true)
[weUser setOptInStatusForChannel:WEGEngagementChannelPush status:YES];

WEGEngagementChannel is an enum and can have four values: WEGEngagementChannelPush, WEGEngagementChannelInApp, WEGEngagementChannelSMS, WEGEngagementChannelEmail, WEGEngagementChannelWhatsapp. Setting setOptInStatusForChannel to false for a particular channel opts the user out of that channel.


To set user location manually, use this method. If auto location tracking is enabled, WebEngage SDK will manage location updates on its own. However, you can call this method to set user location if you have disabled auto location tracking, or to manually set the location.

weUser.setUserLocationWithLatitude(19.0822, andLongitude: 72.8417)
[weUser setUserLocationWithLatitude:@19.0822 andLongitude:@72.8417];

Deleting system user attributes

WebEngage allows you to delete any system attributes that you had created previously if you no longer need them.

[weUser deleteAttribute:@"email"];

WEGUserProfileAttribute is an enum and can have following values:

User Profile Attribute




Date of birth




First name


Last name



Setting custom user attributes

Use these APIs to attach custom attributes to the user.

Simple custom user attributes

User attributes of the data types NSString, NSNumber and NSDate are called simple custom user attributes. They can be used to both create user segments as well as to personalize campaigns.


  • Attribute names must be less than 50 characters long. NSString type attribute values must be less than 1000 characters long. Any characters beyond these limits 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_.

NSString attribute

weUser.setAttribute("Twitter username", withStringValue: "origjohndoe86")
[weUser setAttribute:@"Twitter username" withStringValue:@"@origjohndoe86"];

NSNumber attribute

weUser.setAttribute("Points earned", withValue: 78732)
[weUser setAttribute:@"Points earned" withValue:[NSNumber numberWithInteger:78732]];

Boolean attribute

weUser.setAttribute("Subscribed to email", withValue: true)
[weUser setAttribute:@"Subscribed to email" withValue:[NSNumber numberWithBool:YES]];

NSDate attribute

var comps = DateComponents() = 19
comps.month = 8
comps.year = 1996
let date: Date? = comps)
weUser.setAttribute("Last order date", withDateValue: date)
NSDateComponents *comps = [[NSDateComponents alloc] init];
        [comps setDay:19];
        [comps setMonth:8];
        [comps setYear:1996];
        NSDate *date = [[NSCalendar currentCalendar] dateFromComponents:comps];
        [weUser setAttribute:@"Last order date" withDateValue:date];

1. User attribute names are case sensitive.
2. attributeName 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.

Complex custom user attributes

User attributes of NSArray and NSDictionary data types are called complex custom user attributes. NSArray can contain any type of simple or complex attributes. They can be used to personalize campaigns as shown below.

Note that you will not be able to use complex attributes as segment filters, as you can see in the segment creation screen below.

NSArray attribute

NSArray values must be one of the simple or complex attribute types.

weUser.setAttribute("Brand affinity", withArrayValue: ["Hugo Boss","Armani Exchange", "GAS", "Brooks Brothers"])
[weUser setAttribute:@"Brand affinity" withArrayValue:@[@"Hugo Boss",@"Armani Exchange", @"GAS", @"Brooks Brothers"]];

NSDictionary attribute

Values in the NSDictionary must be one of the simple or complex attribute types.

let userAddress = ["Flat": "Z-62", "Building": "Pennant Court", "Locality": "Penn Road", "City": "Wolverhampton", "State": "West Midlands", "PIN": "WV30DT"]
weUser.setAttribute("Address", withDictionaryValue: userAddress)
NSDictionary *userAddress=@{
  @"Building":@"Pennant Court",
  @"Locality":@"Penn Road",
  @"State":@"West Midlands",

[weUser setAttribute:@"Address" withDictionaryValue:userAddress];

Deleting custom user attributes

WebEngage allows you to delete any custom attributes that you had created previously if you no longer need them.

weUser.deleteAttribute("Points earned")
weUser.deleteAttributes(["Twitter username", "Subscribed to email", "Points earned"])
[weUser deleteAttribute:@"Points earned"];
[weUser deleteAttributes:@[@"Twitter username", @"Subscribed to email", @"Points earned"]];

Updated about a month ago

So, what's next?

Tracking events

Tracking Users

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.