Inherits From: LiObject
Declared In: User.h

Overview

The User class is a default class provided by Applicasa to help developers easily add users and user-based functionality to their applications.

Users are an integral part of any successful application. Applicasa's User class provides a base object for creating, editing, and enhancing user accounts.

It is worth mentioning that, as with all Applicasa-provided default object classes, the User class fields can only be added to. Developers cannot remove default properties and fields from the class, but they can use the web console to add additional fields to the User class as their application requires.

Tasks

Creating and Editing Users

- registerUsername:andPassword:withBlock:
- saveWithBlock:
- increaseField:byValue:
- uploadFile:toField:withFileType:extension:andBlock:

Updating Credentials

+ updateUsername:usingPassword:withBlock:
+ updatePassword:forOldPassword:withBlock:
+ forgotPasswordForUsername:withBlock:

Logging In and Out

+ loginWithUsername:andPassword:withBlock:
+ logoutWithBlock:

Retrieving Users

+ getCurrentUser
+ getById:queryKind:withBlock:
+ getArrayWithQuery:queryKind:withBlock:
+ getLocalArrayWithRawSQLQuery:andBlock:

Facebook Integration

- facebookLoginWithBlock:
+ facebookFindFriendsWithBlock:
+ facebookLogoutWithBlock:

Checking Behavior Profile

+ getCurrentSpendingProfile
+ getCurrentUsageProfile

Properties

userId

The item's unique ID value.

@property (nonatomic, retain) NSString *userId;

Discussion:

This is a user's unique ID value as recorded in the Applicasa datastore. It is set by the datastore when you register a new user. You can use this for such tasks as, among other custom uses, querying users by their ID value to retrieve a specific object from the datastore.

userName

A user's username.

@property (nonatomic, retain, readonly) NSString *userName;

Discussion:

This is a user's username. It cannot be edited directly. This value is created and updated with the registerUsername:andPassword:withBlock: and updateUsername:usingPassword:withBlock: methods.

userFirstName

A user's first name.

@property (nonatomic, retain) NSString *userFirstName;

Discussion:

A user's first name. This field is editable.

userLastName

A user's last name.

@property (nonatomic, retain) NSString *userLastName;

Discussion:

A user's last name. This field is editable.

userEmail

A user's email address.

@property (nonatomic, retain) NSString *userEmail;

Discussion:

A user's email address. This field is editable.

userPhone

A user's phone number.

@property (nonatomic, retain) NSString *userPhone;

Discussion:

A user's phone number. This field is editable.

userPassword

A user's password.

@property (nonatomic, retain, readonly) NSString *userPassword;

Discussion:

A user's password. It cannot be edited directly. This value is created and updated with the registerUsername:andPassword:withBlock: and updatePassword:forOldPassword:withBlock: methods.

userLastLogin

The user's last login date.

@property (nonatomic, retain, readonly) NSDate *userLastLogin;

Discussion:

The user's last login date. It cannot be edited directly, and is updated by Applicasa when loginWithUsername:andPassword:withBlock: succeeds.

userRegisterDate

The user's registration date.

@property (nonatomic, retain, readonly) NSDate *userRegisterDate;

Discussion:

The user's registration date. It cannot be edited directly, and is set by Applicasa when registerUsername:andPassword:withBlock: succeeds.

userLocation

The user's current location.

@property (nonatomic, retain) CLLocation *userLocation;

Discussion:

The user's current location, updated whenever location-related methods from LiUserLocation are called.

userIsRegistered

A boolean value that indicates whether the current user is anonymous or not.

@property (nonatomic, assign, readonly) BOOL userIsRegistered;

Discussion:

This value is readonly, and defaults to FALSE for new users. It is set to TRUE when registerUsername:andPassword:withBlock: succeeds.

userIsRegisteredFacebook

A boolean value that indicates whether the current user is registered through Facebook.

@property (nonatomic, assign, readonly) BOOL userIsRegisteredFacebook;

Discussion:

This value is readonly, and defaults to FALSE for new users. It is set to TRUE when a user successfully authenticates via facebookLoginWithBlock:.

userLastUpdate

An NSDate value of the last time the object was updated.

@property (nonatomic, retain, readonly) NSDate *userLastUpdate;

Discussion:

The userLastUpdate value is calculated by the Applicasa SDK and datastore. It is advised that developers not alter this value directly.

userImage

A user's image URL.

@property (nonatomic, retain) NSURL *userImage;

Discussion:

An NSURL providing the location of the user's image file. This is provided as a default field for setting profile images in applications, if desired. It is a URL to the image, not the image itself.

userMainCurrencyBalance

A user's current main currency balance within an application's virtual economy.

@property (nonatomic, assign) int userMainCurrencyBalance;

Discussion:

A user's current main currency balance within an applications virtual economy. This is constantly updated whenever a user performs virtual store actions, such as In-App Purchases, buying VirtualGood items, etc.

userSecondaryCurrencyBalance

A user's current secondary currency balance within an application's virtual economy.

@property (nonatomic, assign) int userSecondaryCurrencyBalance;

Discussion:

A user's current secondary currency balance within an applications virtual economy. This is constantly updated whenever a user performs virtual store actions, such as In-App Purchases, buying VirtualGood items, etc.

userFacebookID

A user's Facebook ID.

@property (nonatomic, retain, readonly) NSString *userFacebookID;

Discussion:

A user's Facebook ID, saved when a user registers or logs in via Facebook if your application is using Applicasa's Facebook Kit.

Class Methods

loginWithUsername:andPassword:withBlock:

Authenticates a user and logs them in if successful.

+ (void) loginWithUsername:(NSString *)username andPassword:(NSString *)password withBlock:(LiBlockAction)block;

Parameters:

username
An NSString indicating the user's username.

password
An NSString indicating the user's password.

block
A block that must match the signature (NSError *error, NSString *itemID, Actions action).

Discussion:

Authenticates a user via Applicasa, logging them in if usernameand password are correct. A developer can then use the block parameter to respond to method completion if desired. The block must match the signature (NSError *error, NSString *itemID, Actions action).

updateUsername:usingPassword:withBlock:

Updates an existing user's username.

+ (void) updateUsername:(NSString *)newUsername usingPassword:(NSString *)password withBlock:(LiBlockAction)block;

Parameters:

newUsername
An NSString indicating the user's new username.

password
An NSString indicating the user's current password, for verification.

block
A block that must match the signature (NSError *error, NSString *itemID, Actions action).

Discussion:

This method allows a developer to update an existing user's username, supplying their current password to verify their identity. The developer provides a block to handle method completion. The block must match the signature (NSError *error, NSString *itemID, Actions action).

updatePassword:forOldPassword:withBlock:

Updates an existing user's password.

+ (void) updatePassword:(NSString *)newPassword forOldPassword:(NSString *)forOldPassword withBlock:(LiBlockAction)block;

Parameters:

newPassword
An NSString indicating the user's new password.

forOldPassword
An NSString indicating the user's current password, for verification.

block
A block that must match the signature (NSError *error, NSString *itemID, Actions action).

Discussion:

This method allows a developer to update an existing user's password, supplying their current password to verify their identity. The developer provides a block to handle method completion. The block must match the signature (NSError *error, NSString *itemID, Actions action).

logoutWithBlock:

Logs a user out of your application.

+ (void) logoutWithBlock:(LiBlockAction)block;

Parameters:

block
A block that must match the signature (NSError *error, NSString *itemID, Actions action).

Discussion:

Logout a user out of your application. A developer can then use the block parameter to respond to method completion if desired. The block must match the signature (NSError *error, NSString *itemID, Actions action).

forgotPasswordForUsername:withBlock:

Handles situations where users have forgotten their password.

+ (void) forgotPasswordForUsername:(NSString *)username withBlock:(LiBlockAction)block;

Parameters:

username
An NSString indicating the username for which a password is forgotten.

block
A block that must match the signature (NSError *error, NSString *itemID, Actions action).

Discussion:

Handles situations where users have forgotten their password. If the provided username has an email address saved to their user record, a password will be emailed. If not, an error will be returned to the block.

A developer uses the block parameter to respond to method completion. The block must match the signature (NSError *error, NSString *itemID, Actions action).

getById:queryKind:withBlock:

Class method for retrieving an object by ID value.

+ (void) getById:(NSString *)Id queryKind:(QueryKind)queryKind withBlock:(GetUserFinished)block;

Parameters:

Id
An NSString value representing the ID value of the object you wish to retrieve.

queryKind
A QueryKind constant indicating which type of query you wish to perform. Options are FULL, LIGHT, and LOCAL.

block
A block that allows a developer to respond to method completion. Must match the signature (NSError *error, User *object).

Discussion:

This method allows a developer to retrieve an object from the Applicasa datastore, indicate what kind of query the developer wishes to perform, and requires a block that matches the signature (NSError error, User object).

Applicasa provides a great deal of power to your queries via the queryKind parameter. This allows you to specify whether you want to perform a network query that looks up all related objects for their most recent values (FULL); a network query that only retrieves deltas of the most recent data for the given object itself, without looking up related objects (LIGHT); or a local-only query that hits the offline sqlite datastore Applicasa creates to ensure your application keeps working even when a network connection does not exist (LOCAL).

getArrayWithQuery:queryKind:withBlock:

Class method for retrieving an object with a custom query.

+ (void) getArrayWithQuery:(LiQuery *)query queryKind:(QueryKind)queryKind withBlock:(GetUserArrayFinished)block;

Parameters:

query
An LiQuery instance representing the query for the objects you wish to retrieve.

queryKind
A QueryKind constant indicating which type of query you wish to perform. Options are FULL, LIGHT, and LOCAL.

block
A block that allows a developer to respond to method completion. Must match the signature (NSError *error, NSArray *array).

Discussion:

This method allows a developer to retrieve an object from the Applicasa datastore, indicate what kind of query the developer wishes to perform, and requires a block that matches the signature (NSError *error, NSArray *array). The array instance passed to the block will contain all the User objects that matched your query.

Applicasa provides a great deal of power to your queries via the queryKind parameter. This allows you to specify whether you want to perform a network query that looks up all related objects for their most recent values (FULL); a network query that only retrieves deltas of the most recent data for the given object itself, without looking up related objects (LIGHT); or a local-only query that hits the offline sqlite datastore Applicasa creates to ensure your application keeps working even when a network connection does not exist (LOCAL).

getLocalArrayWithRawSQLQuery:andBlock:

Class method for retrieving an object locally (only) with a raw SQL statement.

+ (void) getLocalArrayWithRawSQLQuery:(NSString *)rawQuery andBlock:(GetUserArrayFinished)block;

Parameters:

rawQuery
An SQL query representing the objects you wish to retrieve.

block
A block that allows a developer to respond to method completion. Must match the signature (NSError *error, NSArray *array).

Discussion:

This method allows a developer to retrieve an object from the local Applicasa datastore via a raw SQL query, and requires a block that matches the signature (NSError *error, NSArray *array). The array instance passed to the block will contain all the User objects that matched your query.

facebookFindFriendsWithBlock:

Finds a user's Facebook friends.

+ (void) facebookFindFriendsWithBlock:(LiBlockFBFriendsAction)block;

Parameters:

block
A block for taking action after a user's friends are found (or, in the case of an error, not found). Must match the signature (NSError *error, NSArray *friends, Actions action).

Discussion:

Finds a user's Facebook friends, requiring a block parameter for additional processing or action after friends are found. The block must match the signature (NSError *error, NSArray *friends, Actions action).

facebookLogoutWithBlock:

Logs a user out of your application via Facebook

+ (void) facebookLogoutWithBlock:(LiBlockAction)block;

Parameters:

block
A block for taking action after a user is logged out via Facebook. Must match the signature (NSError *error, NSString *itemID, Actions action).

Discussion:

Logs a user out of your application via Facebook, requiring a block parameter for additional processing or action after logout is complete. The block must match the signature (NSError *error, NSString *itemID, Actions action).

getCurrentSpendingProfile

Returns a user's current spending profile as determined by Applicasa behavior analytics.

+ (LiSpendingProfile) getCurrentSpendingProfile;

Return Value:

An LiSpendingProfile enum value.

Discussion:

Returns a user's calculated spending profile within an application in relation to all app users. The returned LiSpendingProfile enum value will be one of LiSpendingProfileNone, LiSpendingProfileZombie (rare or no in-app spending), LiSpendingProfileTourist (occasional in-app spending), LiSpendingProfileTaxPayer (regular in-app spending), or LiSpendingProfileRockefeller (heavy in-app spending).

getCurrentUsageProfile

Returns a user's current usage profile as determined by Applicasa behavior analytics.

+ (LiUsageProfile) getCurrentUsageProfile;

Return Value:

An LiUsageProfile enum value.

Discussion:

Returns a user's calculated usage profile within an application in relation to all app users. The returned LiUsageProfile enum value will be one of LiUsageProfileNone, LiUsageProfileCivilian (rare or no app usage), LiUsageProfilePrivate (occasional app usage), LiUsageProfileSergeant (regular app usage), or LiUsageProfileGeneral (heavy app usage).

getCurrentUser

Returns the current application User object.

+ (User *) getCurrentUser;

Return Value:

A User object.

Instance Methods

saveWithBlock:

Instance method for saving an existing User instance.

- (void) saveWithBlock:(LiBlockAction)block;

Parameters:

block
A block that must match the signature (NSError *error, NSString *itemID, Actions action).

Discussion:

Saves existing User objects and allows a developer to respond to method completion with the block parameter. This block must match the signature (NSError *error, NSString *itemID, Actions action).

NOTE: Creating new users, unlike other LiObject classes, cannot be done with the standard init methods and a call to saveWithBlock:. Creating users requires using the registerUsername:andPassword:withBlock: method.

registerUsername:andPassword:withBlock:

Registers a new user to your Applicasa datastore.

- (void) registerUsername:(NSString *)username andPassword:(NSString *)password withBlock:(LiBlockAction)block;

Parameters:

username
An NSString indicating the new user's username.

password
An NSString indicating the new user's password.

block
A block that must match the signature (NSError *error, NSString *itemID, Actions action).

Discussion:

This is the method to use when registering new users for an Applicasa-backed application. When a user launches the app, Applicasa's framework creates an anonymous User instance for developers. It is then up to you to prompt anonymous users for a username and password to successfully register them. Once registered, you can prompt for additonal information, update the User instance, and then use saveWithBlock: to update the User to the datastore.

increaseField:byValue:

Increases numeric fields by a supplied value.

- (void) increaseField:(LiField)field byValue:(NSNumber *)value;

Parameters:

field
The field you wish to update, a constant from LiField.

value
An NSNumber indicating the value by which you wish to increase field.

Discussion:

Increases numeric fields by a supplied value.

uploadFile:toField:withFileType:extension:andBlock:

Instance method for uploading a file to a given object field.

- (void) uploadFile:(NSData *)data toField:(LiField)field withFileType:(AMAZON_FILE_TYPES)fileType extension:(NSString *)ext andBlock:(LiBlockAction)block;

Parameters:

data
An NSData object representing the image data you wish to upload.

field
The LiField constant indicating to which field name you wish to upload.

fileType
A valid fileType argument indicating what type of file you are uploading. Valid values are Image, Text, and Pdf.

ext
An NSString indicating the extension of the file you are uploading.

block
A block that must match the signature (NSError *error, NSString *itemID, Actions action).

Discussion:

This method enables a developer to upload a file to an object field via the Applicasa SDK. It uploads the file to Amazon S3, and provides a block that allows you to respond to method completion. The block must match the signature (NSError *error, NSString *itemID, Actions action).

facebookLoginWithBlock:

Logs a user into your application via Facebook

- (void) facebookLoginWithBlock:(LiBlockAction)block;

Parameters:

block
A block for taking action after a user is authenticated via Facebook. Must match the signature (NSError *error, NSString *itemID, Actions action).

Discussion:

Logs a user into your application via Facebook, requiring a block parameter for additional processing or action after Facebook user is found. The block must match the signature (NSError *error, NSString *itemID, Actions action).