Skip to content

User Properties

When a user registers with an application, he provides information which establishes user's identity. For one application these properties may include name, phone number and email address, for another it could be user id, age and gender. Backendless User Service allows each application to have a custom set of properties associated with the user entity.

Defining properties with the API

User properties must be defined in the object representing a user. When user registers or user object is updated, Backendless saves the property values in the Users table of Backendless Data service. If a property is not declared on the server-side, Backendless automatically creates a definition for it. This behavior can be turned off/on using the Dynamic Schema Definition configuration setting in the console (select Data > Configuration). The setting is turned on by default:

dynamic-schema-definition.zoom70

Set/Update User Property

Important

When setting or updating a user property, the values must be of "primitive" data types (boolean, string, number, date). To assign a non-primitive value, use the Data relation API .

The following API can be used to set or update properties in a user object:

Methods to set/add user properties are available in the BackendlessUser class. When registering a new user, the methods below can be used on a new instance of BackendlessUser. When updating an existing user, the instance must be retrieved from the server (either via login or standard data object retrieval).

BackendlessUser *user = [BackendlessUser new];

// adds the new property to the user object
NSMutableDictionary *userProperties = [NSMutableDictionary dictionaryWithDictionary:user.properties];
userProperties[@"newProperty"] = propertyValue;
user.properties = userProperties;

// clears (removes) all user properties and replaces them with the specified collection
user.properties = @{@"propertyName": propertyValue};

let user = BackendlessUser()
// sets the new property to the user object
user.properties["newProperty"] = propertyValue

// clears (removes) all user properties and replaces them with the specified collection
user.properties = ["propertyName": propertyValue]

Retrieve User Property Values

The following API can be used to get or delete user property values:

BackendlessUser *user = // some BackendlessUser object

// retrieves value of a property with the specified name
id value = user.properties[@"propertyName"];

// retrieves all properties for the user object
NSDictionary *properties = user.properties;

// removes the property identified by the name
NSMutableDictionary *userProperties = [NSMutableDictionary dictionaryWithDictionary:user.properties];
[userProperties removeObjectForKey:@"propertyName"];
user.properties = userProperties;

// removes all properties identified by names
NSMutableDictionary *userProperties = [NSMutableDictionary dictionaryWithDictionary:user.properties];
[userProperties removeObjectsForKeys:@[@"propertyName1", @"propertyName2"]];
user.properties = userProperties;

let user = // some BackendlessUser object

// retrieves value of a property with the specified name
let value = user.properties["propertyName"]

// retrieves all properties for the user object
let properties = user.properties

// removes the property identified by the name
user.properties.removeValue(forKey: "propertyName")

// removes all properties identified by names
let propertyNames = ["propertyName1", "propertyName2"]
for propertyName in propertyNames {
    user.properties.removeValue(forKey: propertyName)
}

Example

The example below describes how to retrieve the phoneNumber user property.

[Backendless.shared.userService loginWithIdentity:@"spidey@backendless.com" password:@"greeng0blin" responseHandler:^(BackendlessUser *loggedInUser) {
    NSString *phoneNumber = loggedInUser.properties[@"phoneNumber"];
    if (phoneNumber) {
        NSLog(@"User's email: %@, phoneNumber: %@", loggedInUser.email, phoneNumber);
    }
} errorHandler:^(Fault *fault) {
    NSLog(@"Error: %@", fault.message);
}];

Backendless.shared.userService.login(identity: "spidey@backendless.com", password: "greeng0blin", responseHandler: { loggedInUser in
    if let email = loggedInUser.email,
       let phoneNumber = loggedInUser.properties["phoneNumber"] as? String {
        print("User's email: \(email), phoneNumber: \(phoneNumber)")
    }
}, errorHandler: { fault in
    print("Error: \(fault.message ?? "")")
})

Defining properties with Console

User property management is available in the schema editor of the Users table. To open the schema editor:

  1. Login to Backendless Console and select your application.
  2. Click the Data icon, and select the Users table.
  3. Click the Schema menu.

There are built-in user properties, such as email, name and password. The email and name properties can be deleted if they do not apply to your app, although it is recommended to keep the email property, since it is used for other purposes (for instance, password recovery). The password property cannot be deleted.

Identity Property/Column

It is required that one of the properties is marked as identity. This is the property Backendless uses for the Login and Restore Password operations. As users register, Backendless ensures the value for the identity property is unique.

Password Property/Column

"password" is a special property/column. Backendless automatically adds the column when an application is created. The following rules apply to the password column:

  • Password cannot be removed from the application.
  • Password cannot be used as identity.
  • Password is a required property

users-schema.zoom80