User attributes are specific traits of a user, like an email, username, mobile, gender, etc.
This information is helpful in order to target users based on these attributes across devices or installs.
info |
Default & Predefined User Attributes We track certain user attributes by default in our SDK, and also we have predefined attribute names for certain common user info tracked by these SDK methods. Make sure to use these and not track the same info with the different attribute names. Find the list of default and predefined user attributes tracked by SDK here. |
User Login / Logout
It is important that you handle user login and logout as mentioned below. There is a definite possibility that your data gets corrupted if this is not done properly.
- Make sure to get hold of a
unique id
for your app users and pass that information to our SDK using the setUniqueID(_:) method. We use thisunique id
to identify a user and also to merge user profiles across installs and platforms.
- And also, once the user logs out of your app, it is necessary to call resetUser() of SDK so that we create a new anonymous user and track the events following this to the new user's profile.
Kindly ensure you call the following methods on user login/logout.
Login
MoEngageSDKAnalytics.sharedInstance.setUniqueID(UNIQUE_ID) // UNIQUE_ID is used to uniquely identify a user.
[[MoEngageSDKAnalytics sharedInstance] setUniqueID:UNIQUE_ID]; // UNIQUE_ID is used to uniquely identify a user.
Note: The following values are not allowed in the UniqueID field: "unknown", "guest", "null", "0", "1", "true", "false", "user_attribute_unique_id", "(empty)", "na", "n/a", "", "dummy_seller_code", "user_id", "id", "customer_id", "uid", "userid", "none", "-2", "-1", "2"
warning |
UNIQUE ID chaos
|
Logout
MoEngageSDKAnalytics.sharedInstance.resetUser()
[[MoEngageSDKAnalytics sharedInstance] resetUser];
Updating User Attribute Unique ID
warning |
Important Please make sure that you use setAlias(_:) for updating the User Attribute Unique ID and not setUniqueID(_:) as calling setUniqueID(_:) with a new value will reset the current user and lead to the creation of unintended users in our system. |
In a scenario where you have to update the existing user's Unique ID value make use of setAlias(_:) method as shown below with the updated Unique ID value:
MoEngageSDKAnalytics.sharedInstance.setAlias(UPDATED_UNIQUE_ID)
[[MoEngageSDKAnalytics sharedInstance] setAlias:UPDATED_UNIQUE_ID];
Default User Attributes
Some default SDK User Attribute can be set for eg. email-id, mobile number, gender, user name, birthday. The default attributes tracked by SDK can be set as shown below :
MoEngageSDKAnalytics.sharedInstance.setName(userName)
MoEngageSDKAnalytics.sharedInstance.setLastName(userLastname)
MoEngageSDKAnalytics.sharedInstance.setFirstName(userFirstName)
MoEngageSDKAnalytics.sharedInstance.setEmailID(userEmailID)
MoEngageSDKAnalytics.sharedInstance.setMobileNumber(userPhoneNo)
MoEngageSDKAnalytics.sharedInstance.setGender(.male) //Use UserGender enumerator for this
MoEngageSDKAnalytics.sharedInstance.setDateOfBirth(userBirthdate)//userBirthdate should be a Date instance
MoEngageSDKAnalytics.sharedInstance.setLocation(MoEngageGeoLocation(withLatitude: userLocationLat, andLongitude: userLocationLng)) //userLocationLat and userLocationLng are double values of the location coordinates
[[MoEngageSDKAnalytics sharedInstance] setName:userName];
[[MoEngageSDKAnalytics sharedInstance] setLastName:userLastname];
[[MoEngageSDKAnalytics sharedInstance] setFirstName:userFirstName];
[[MoEngageSDKAnalytics sharedInstance] setEmailID:userEmailID];
[[MoEngageSDKAnalytics sharedInstance] setMobileNumber:userPhoneNo];
[[MoEngageSDKAnalytics sharedInstance] setGender:UserGenderMale]; // Use UserGender enumerator for this
[[MoEngageSDKAnalytics sharedInstance] setDateOfBirth:userBirthdate];//userBirthdate should be a NSDate instance
[[MoEngageSDKAnalytics sharedInstance] setLocation:[[MoEngageGeoLocation alloc] initWithLatitude:userLocationLat andLongitude:userLocationLng]];//userLocationLat and userLocationLng are double values of the location coordinates
warning |
Note
|
Custom User Attributes
To set custom attributes just provide custom keys different to the ones present in here. Following is an example :
MoEngageSDKAnalytics.sharedInstance.setUserAttribute("Bengaluru", withAttributeName: "Current_city")
MoEngageSDKAnalytics.sharedInstance.setUserAttribute(["Bengaluru","Delhi","Chennai"], withAttributeName: "Current_cities")
[[MoEngageSDKAnalytics sharedInstance] setUserAttribute:@"Bengaluru" withAttributeName:@"Current_city"];
NSArray *myArray = @[@"Bengaluru", @"Delhi", @"Chennai"];
[[MoEngageSDKAnalytics sharedInstance] setUserAttribute:myArray withAttributeName:@"Current_cities"];
User Attributes have the following restrictions :
- User Attribute Names should not contain dot(.)
- User Attribute Names should not start with dollar sign($)
- User Attribute Values should be a String or Number
info |
Note You can not use "moe_" as a prefix while naming events, event attributes, or user attributes. It is a system prefix and using it might result in periodic blacklisting without prior communication. |
JSON Attributes
From MoEngage-iOS-SDK v9.17.5, we have added support for JSON and array of JSON user attributes. Following is an example
MoEngageSDKAnalytics.sharedInstance.setUserAttribute(["item-id" : 123,"item-type" : "books","item-cost" : ["amount" : 100,"currency" : "USD"]],withAttributeName: "product")
MoEngageSDKAnalytics.sharedInstance.setUserAttribute([["item-id" : 123,"item-cost" : ["amount" : 100,"currency" : "USD"]],["item-id" : 323,"item-cost" : ["amount" : 90,"currency" : "USD"]]],withAttributeName: "products")
[MoEngageSDKAnalytics.sharedInstance setUserAttribute:@{@"item-id" : @123,@"item-type" : @"books",@"item-cost" : @{@"amount" : @100,@"currency" : @"USD"}} withAttributeName:@"product"];
[MoEngageSDKAnalytics.sharedInstance setUserAttribute:@[@{@"item-id" : @123,@"item-cost" : @{@"amount" : @100,@"currency" : @"USD"}} , @{@"item-id" : @323,@"item-cost" : @{@"amount" : @90,@"currency" : @"USD"}}] withAttributeName:@"products"];
Date and Time User Attributes
Date and time attributes can be set as user attributes. For this refer to the methods in the code block below:
//1. Track UserAttribute using Date instance
MoEngageSDKAnalytics.sharedInstance.setUserAttributeDate(Date(), withAttributeName: "Date Attr 1")
//2. Track UserAttribute using ISO Date String in format "yyyy-MM-dd'T'HH:mm:ss'Z'"
MoEngageSDKAnalytics.sharedInstance.setUserAttributeISODate("2020-01-12T18:45:59Z", withAttributeName: "Date Attr 2")
//3. Track UserAttribute using Epoch value
MoEngageSDKAnalytics.sharedInstance.setUserAttributeEpochTime(663333, withAttributeName: "Date Attr 3")
//1. Track UserAttribute using Date instance
[[MoEngageSDKAnalytics sharedInstance] setUserAttributeDate:[NSDate date] withAttributeName:@"DateAttr1"];
//2. Track UserAttribute using ISO Date String in format "yyyy-MM-dd'T'HH:mm:ss'Z'"
[[MoEngageSDKAnalytics sharedInstance] setUserAttributeISODate:@"2020-01-12T18:45:59Z" withAttributeName:@"DateAttr2"];
//3. Track UserAttribute using Epoch value
double timestampEpochValue = [[NSDate date] timeIntervalSince1970];
[[MoEngageSDKAnalytics sharedInstance] setUserAttributeEpochTime:timestampEpochValue withAttributeName:@"LastPurchaseDate"];
Location Attributes
The location of a user or any location can be set as a user attribute. For this use setLocation(_:withAttributeName:) method and pass lat, the long value of the location as shown in the following example :
MoEngageSDKAnalytics.sharedInstance.setLocation(MoEngageGeoLocation.init(withLatitude: 72.90909, andLongitude: 12.34567), withAttributeName: "attribute name")
[[MoEngageSDKAnalytics sharedInstance] setLocation:[[MoEngageGeoLocation alloc] initWithLatitude:23.33 andLongitude:26.22] withAttributeName:@"attribute name"];
Tracking User Locale
For tracking the locale settings of the user device use trackLocale() method as shown below:
MoEngageSDKAnalytics.sharedInstance.trackLocale()
[[MoEngageSDKAnalytics sharedInstance] trackLocale];
Reserved keywords for User Attributes
Below is the list of keys that should not be used when tracking user attributes.
- USER_ATTRIBUTE_UNIQUE_ID
- USER_ATTRIBUTE_USER_EMAIL
- USER_ATTRIBUTE_USER_MOBILE
- USER_ATTRIBUTE_USER_NAME
- USER_ATTRIBUTE_USER_GENDER
- USER_ATTRIBUTE_USER_FIRST_NAME
- USER_ATTRIBUTE_USER_LAST_NAME
- USER_ATTRIBUTE_USER_BDAY
- MOE_TIME_FORMAT
- MOE_TIME_TIMEZONE
- USER_ATTRIBUTE_NOTIFICATION_PREF
- USER_ATTRIBUTE_OLD_ID
- MOE_TIME_FORMAT
- MOE_TIME_TIMEZONE
- USER_ATTRIBUTE_DND_START_TIME
- USER_ATTRIBUTE_DND_END_TIME
- MOE_GAID
- MOE_ISLAT
- status