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:
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 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 BackendlessUser
instance representing the user must be retrieved from the server (either via login or the data object retrieval APIs).
// set property value. The property name is the value of the "key" argument
public void setProperty( String key, Object value )
// adds properties to the existing ones
public void putProperties( Map<String, Object> properties )
// removes all existing properties (including the built-in ones such
// as email and password, and sets the provided properties
public void setProperties( Map<String, Object> properties )e
Retrieve User Property Values¶
The following API can be used to get a user property value:
// get property value. Return value must be cast to the expected data type.
public Object getProperty( String key )
// get all user object properties
public Map<String, Object> getProperties()
There is a special consideration for a user property containing a collection of related data. For any one-to-many user property, the related data is returned as an array. Before application casts the array object to an array of a specific type, it must check if the size of the array is greater than zero. The following code demonstrates the recommended approach:
// suppose the user object contains a relation user property called "events":
Object[] eventsObjectArray = (Object[]) user.getProperty( "events" );
Event[] eventsArray;
// if array is not empty, it can be cast to an array of specific type
if( eventsObjectArray != null && eventsObjectArray.length > 0 )
eventsArray = (Event[]) eventsObjectArray;
Example¶
The example below describes how to retrieve the phoneNumber
user property.
public void loginUserAndGetProperties()
{
Backendless.UserService.login( "spidey@backendless.com",
"greeng0blin",
new AsyncCallback<BackendlessUser>()
{
@Override
public void handleResponse( BackendlessUser loggedUser )
{
Toast.makeText( MainActivity.this,
"User has been logged in: " + loggedUser,
Toast.LENGTH_SHORT ).show();
BackendlessUser user = Backendless.UserService.CurrentUser();
if( user != null )
{
// get user's phone number (i.e. custom property)
String phoneNumber = (String) user.getProperty( "phoneNumber" );
Toast.makeText( MainActivity.this,
String.format( "phone number: %s", phoneNumber ),
Toast.LENGTH_SHORT ).show();
}
else
{
Toast.makeText( MainActivity.this,
"User hasn't been logged",
Toast.LENGTH_SHORT ).show();
}
}
@Override
public void handleFault( BackendlessFault fault )
{
new AlertDialog.Builder( MainActivity.this ).
setMessage( "Server reported an error: " + fault ).
setIcon( android.R.drawable.ic_dialog_alert ).
setPositiveButton( android.R.string.ok, null ).show();
}
} );
}
Defining properties with Console¶
User property management is available in the schema editor of the Users
table. To open the schema editor:
- Login to Backendless Console and select your application.
- Click the Data icon, and select the Users table.
- 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