User Profile Management

Learn how to manage user profiles and preferences in your iOS app using the Upshot iOS SDK.

Overview

Every time a user downloads/installs the App and opens it for the first time, the install is tracked and attributed to a new user. This new user is unique in the Upshot.ai universe but could be an existing user of your application who just switched devices or re-installed the App after deleting it or installed the App after resetting the device.

Every user has a set of attributes that can be tracked/set in the application, one of which is the unique id that the SDK generates to identify a user in its system. This will help you track/group all actions performed by a user on multiple devices into one profile.

Each user profile has one or more named properties that describe that user. Because they contain rich user data, profiles are excellent for creating audiences to target with personalized messaging.

Upshot.ai defines some standard attributes for each user profile and allows you to set your user profile's custom attributes.

For detailed user profile information and implementation examples, refer to our User Profile Reference.

Default Device/App-Specific Attributes

The SDK automatically collects the following device and app-specific attributes:

Device Model
Device OS Version
TimeZone on the device
Network Carrier
TimeZoneDaylight
TimeZoneAbbreviation
IP based location
Latitude (if available)
Longitude (if available)
SystemLocaleCode
BuildVersion
AppVersion

Predefined Attributes

Upshot.ai provides predefined attributes with specific data types:

Personal Information

First Name
Middle Name
Last Name
User Name
Language
E-Mail
Occupation
Qualification
Phone
Gender
Marital Status
Age
Location
LocaleCode
Date Of Birth
emailOptout
smsOptout
pushOptout
dataOptout
ipOptout

Demographics

gender (NSNumber); // 1-male, 2-female, 3-other, 4-reset
maritalStatus (NSNumber); // 1-single, 2-engaged, 3-married, 4-widow, 5-divorced, 6-reset
orientation (NSNumber);

Date of Birth

year (NSNumber); // Should be greater than 1900
month (NSNumber);
day (NSNumber);

Location

latitude (NSNumber);
longitude (NSNumber);
carrier (NSString);

External IDs

Facebook ID
Googleplus ID
Twitter ID
Foursquare ID
Linkedin ID
Enterprise UID
Advertising ID
Pinterest ID
AppuID (application register Id)
APNSID (Device Token)
otherExternalIds

Opt-in/Opt-out Settings

email_opt (NSNumber); // 1 for opt-out, 0 for opt-in
sms_opt (NSNumber); // 1 for opt-out, 0 for opt-in
push_opt (NSNumber); // 1 for opt-out, 0 for opt-in
data_opt (NSNumber); // 1 for opt-out, 0 for opt-in
ip_opt (NSNumber); // 1 for opt-out, 0 for opt-in

Setting User Profile

Basic Usage

Objective-C

BKUserInfo *userInfo = [[BKUserInfo alloc] init];
userInfo.email = @"sample@gmail.com";
userInfo.userName = @"userName";
userInfo.phone = @"+919999999999";
userInfo.gender = BKGenderMale;
userInfo.maritalStatus = BKMaritalStatusSingle;

BKExternalId *externalId = [[BKExternalId alloc] init];
externalId.appuID = @"RegistrationId";
userInfo.externalId = externalId;

BKDob *dob = [[BKDob alloc] init];
dob.day = [NSNumber numberWithInteger:1];
dob.month = [NSNumber numberWithInteger:1];
dob.year = [NSNumber numberWithInteger:1990];
userInfo.dateOfBirth = dob;

NSDictionary*others = @{
@"Score" : NSNumber numberWithInteger:100],
@"UserType": @"VIP"
};
userInfo.others = others;

[userInfo buildUserInfoWithCompletionBlock:^(BOOL success, NSError * _Nullable error) {

}];

Swift

let userInfo = BKUserInfo()
userInfo.email = "sample@gmail.com"
userInfo.userName = "userName"
userInfo.phone = "+919999999999"
userInfo.gender = .male
userInfo.maritalStatus = .single

let externalId = BKExternalId()
externalId.appuID = "RegistrationId"
userInfo.externalId = externalId
let dob = BKDob()
dob.day = 1
dob.month = 1
dob.year = 1990
userInfo.dateOfBirth = dob

let others = ["Score":100,
"UserType": "VIP"] as [String : Any]
userInfo.others = others

userInfo.build { (status, error) in

}

Custom User Profile Attributes

Upshot.ai allows you to define application-specific custom attributes as part of the user profile.

Examples of Custom Attributes:

1. Score
2. Level in the game
3. Loyalty Points
4. Status info or badges like "Power user", "Novice user", "Gold Member", etc

Objective-C

// Create custom user profile with custom attributes
BKUserInfo *userInfo = [[BKUserInfo alloc] init];
// Standard attributes
userInfo.email = @"sample@gmail.com";
userInfo.userName = @"userName";
// Custom attributes
NSDictionary *customUserDetails = @{
    @"loyaltyPoints": @1250,
    @"membershipTier": @"Gold",
    @"gameLevel": @15,
};
userInfo.others = customUserDetails;

// Set user profile
[userInfo buildUserInfoWithCompletionBlock:^(BOOL success, NSError * _Nullable error) {

}];

Swift

// Create custom user profile with custom attributes
// Standard attributes
let userInfo = BKUserInfo()
userInfo.email = "sample@gmail.com"
userInfo.userName = "userName"
// Custom attributes
let customUserDetails: [String: Any] = [
    "loyaltyPoints": 1250,
    "membershipTier": "Gold",
    "gameLevel": 15,
]
userInfo.others = customUserDetails;
userInfo.build { (status, error) in

}

User Logout

Whenever a user logs out, the app should inform Upshot.ai that the user has logged out.

Objective-C

// Logout by clearing appuID
BKUserInfo *userInfo = [[BKUserInfo alloc] init];
BKExternalId *externalId = [[BKExternalId alloc] init];
externalId.appuID = @"";
userInfo.externalId = externalId;

[userInfo buildUserInfoWithCompletionBlock:^(BOOL success, NSError * _Nullable error) {

}];

Swift

// Logout by clearing appuID
let userInfo = BKUserInfo()
let externalId = BKExternalId()
externalId.appuID = ""
userInfo.externalId = externalId

userInfo.build { (status, error) in

}

Get User ID

This method returns the UserID generated by Upshot.ai:

// Returns a string which represents the userID generated by Upshot
Upshot.getUserId(function (userId) {
  console.log("User ID:", userId);
});

Important Notes & Validation

Validation Rules

• Phone Numbers: Must start with + and contain only numeric values (Ex: +9999999999). SDK will discard numbers that don't follow this pattern.
• String Fields: Maximum 64 characters for value type string fields like firstName, lastName, userName, etc.
• Custom Attribute Keys: Special characters won't be allowed except underscore (_). Keys should start with alphabets only. SDK will replace special characters with empty string.
• Date of Birth: Year should be greater than 1900.

Gender Values

1 - male;
2 - female;
3 - other;
4 - reset;

Marital Status Values

1 - single;
2 - engaged;
3 - married;
4 - widow;
5 - divorced;
6 - reset;

Best Practices

1. Consistent Data Format: Always use consistent data formats for dates, phone numbers, and other structured data
2. Privacy Compliance: Respect user privacy settings and opt-out preferences
3. Data Validation: Validate user input before sending to Upshot.ai
4. Regular Updates: Keep user profiles updated as user information changes
5. Custom Attributes: Use meaningful names for custom attributes that align with your business logic
6. Error Handling: Always handle the response callback to ensure profile updates are successful

Validation in Dashboard

You can validate UserProfile data in the Dashboard Live Events section to ensure the data is being captured correctly.

Common Use Cases

• User Registration: Set basic profile information when users sign up
• Profile Completion: Track profile completion percentage
• Preference Management: Store user preferences and settings
• Subscription Tracking: Track subscription status and billing information
• Gaming Progress: Store game levels, scores, and achievements
• E-commerce: Track purchase history, loyalty points, and shopping preferences
• Social Integration: Link social media accounts and preferences

Troubleshooting

Common Issues

Profile Not Updating:

• Verify the response callback returns true
• Check that required fields are properly formatted
• Ensure special characters in keys are handled

Phone Number Rejected:

• Verify phone number starts with + symbol
• Ensure only numeric characters after +
• Check country code is included

Custom Attributes Not Appearing:

• Verify attribute keys start with alphabets
• Remove special characters except underscore
• Check key length doesn't exceed limits -->