Login

Top  Previous  Next

Registered users can login to establish their identity with the application using the API below. The login operation requires two properties: one marked as user identity and the second is password. Backendless automatically assigns the "AuthenticatedUser" role to all successfully logged in users. The role can be used to differentiate access to various resources (persistent objects, messaging channels, media streams) between authenticated users and guests.

Asynchronous Methods:

The method call does not block - it returns immediately. The AsyncCallback argument receives either the response or the fault returned by the Backendless servers.

public void Backendless.UserService.login( String login, 
                                           String password, 
                                           AsyncCallback<BackendlessUser> callback );

public void Backendless.UserService.login( String login, 
                                           String password,   
                                           AsyncCallback<BackendlessUser> callback,
                                           boolean stayLoggedIn, );

where:

login- a value for the property marked as identity.
password- user's password
callback- an object which receives either a return value or an error from the server. The class must implement the AsyncCallback<BackendlessUser> interface.
stayLoggedIn- requests to store the user's login information so the login form can be skipped next time the user launches the app. Use the following API to check if the application has user login information from previous runs:

// UserTokenStorageFactory is available in the com.backendless.persistence.local package

String userToken = UserTokenStorageFactory.instance().getStorage().get();

if( userToken != null && !userToken.equals( "" ) )
{  // user login is available, skip the login activity/login form }

Synchronous Method:

public BackendlessUser Backendless.UserService.login( String login, String password, boolean stayLoggedIn ) throws BackendlessException;

where:

login- a value for the property marked as identity.
password- user's password
stayLoggedIn- requests to store the user's login information so the login form can be skipped next time the user launches the app. Use the following API to check if the application has user login information from previous runs:

// UserTokenStorageFactory is available in the com.backendless.persistence.local package

String userToken = UserTokenStorageFactory.instance().getStorage().get();

if( userToken != null && !userToken.equals( "" ) )
{  // user login is available, skip the login activity/login form }

Errors:

The following errors may occur during the Login API call. See the Error Handling section for details on how to retrieve the error code when the server returns an error.

Error Code

Description

2002

Version is disabled or provided wrong application info (application id or secret key)

3000

Login has been disabled for the user account.

3001

Missing login settings, possibly invalid application id or version.

3002

User cannot login because Multiple Logins disabled and there is a logged in user for the account.

3003

Invalid login or password.

3006

Either login or password is an empty string value.

3034

User logins are disabled for the version of the application.

3036

Account locked out due to too many failed logins.

3038

One of the required parameters (application id, version, login or password) is null

3044

Multiple login limit for the same user account has been reached.

8000

Property value exceeds the length limit

 

Asynchronous Method Sample:

Backendless.initApp( appId, secretKet, version ); // where to get the argument values for this call
Backendless.UserService.login( username, password, new AsyncCallback<BackendlessUser>()
{
 public void handleResponse( BackendlessUser user )
  {
    // user has been logged in
  }

  public void handleFault( BackendlessFault fault )
  {
    // login failed, to get the error code call fault.getCode()
  }
});

Synchronous Method Sample:

Backendless.initApp( appId, secretKet, version ); // where to get the argument values for this call
BackendlessUser user;

try
{
  user = Backendless.UserService.login( username, password );
}
catch( BackendlessException exception )
{
  // login failed, to get the error code, call exception.getFault().getCode()
}

Validating User Login

The login operation provides a way to persist the user-token on the client side so it can be used when the application is restarted. This helps in streamlining the user experience since the user of the application does not need to login again. However, when the application restarts, it needs to check if the underlying user token, and hence the user session are still valid. This can be accomplished with the API below:

Asynchronous Methods:

The method call does not block - it returns immediately. The AsyncCallback argument receives either the response or the fault returned by the Backendless servers.

public void Backendless.UserService.isValidLogin( AsyncCallback<Boolean> callback );

where:

callback- an object which receives either a return value or an error from the server. The class must implement the AsyncCallback<Boolean> interface.

Synchronous Method:

public boolean Backendless.UserService.isValidLogin();

If user token is valid, objectId of the logged in user can be retrieved with the following call:

string currentUserObjectId = UserIdStorageFactory.instance().getStorage().get()

Subsequently the BackendessUser instance can be obtained with the following API:

Asynchronous call:

Backendless.Data.of( BackendlessUser.class ).findById( currentUserObjectId, AsyncCallback<BackendlessUser> callback )

Synchronous call:

Backendless.Data.of( BackendlessUser.class ).findById( currentUserObjectId )

Example:

Log in a user first. Make sure the stayLoggedIn argument is true. The value of true persists the information about the login for the use by subsequent starts/sessions of the application:

Backendless.UserService.login( "batman@backendless.com", "superm@n", true );

Then, check whether the login is valid - see the example below:

Synchronous example:

boolean isValidLogin = Backendless.UserService.isValidLogin();
System.out.println( "[SYNC] Is login valid? - " + isValidLogin );

Asynchronous example:

AsyncCallback<Boolean> isValidLoginCallback = new AsyncCallback<Boolean>()
{
  @Override
  public void handleResponse( Boolean response )
  {
    System.out.println( "[ASYNC] Is login valid? - " + response );
  }

  @Override
  public void handleFault( BackendlessFault fault )
  {
    System.err.println( "Error - " + fault );
  }

};

Backendless.UserService.isValidLogin( isValidLoginCallback );

Program Output

Is login valid? - true

 


Please let us know how we can improve the documentation by leaving a comment. All technical questions should be posted to the Backendless Support forum. We do not respond to the technical questions on the documentation pages.: