User

In Monaca, you can add user account functionality to your app by using the following Monaca Backend JavaScript APIs.

User.register()

Sign a user up with his/her username and password.

monaca.cloud.User.register(username: String, password: String, [properties: Object]) : $.Promise

Parameter

Return Value

Within the done() callback, there is a user JSON Object which has the following properties:

• _id : {String}
• _username : {String}
• _createdAt : {Number} unixtime
• _updateAt : {Number} unixtime
• and other user-defined properties.

Errors Code

Errors are returned as Error object.

Example

The following snippet shows how to create a new user account with the username "[email protected]", password "password" and age 21.

monaca.cloud.User.register("[email protected]", "password", {age:21})
.done(function(result)
{
   console.log("Welcome, " + result.user._username);
   console.log("You are " + result.user.age + " years old.");
}
)
.fail(function(err)
{
   console.log("Err#" + err.code +": " + err.message);
});

User.validate()

Validate registration parameters.

monaca.cloud.User.validate(username: String, [properties: Object]) : $.Promise

Parameter

Return Value

Errors Code

Errors are returned as Error object.

Example

The following code illustrates an example of a user validation by checking whether the username "[email protected]" already exists.

monaca.cloud.User.validate("[email protected]")
.done(function(result)
{
   console.log("Validation passed!");
})
.fail(function(err)
{
   console.log("Err#" + err.code +": " + err.message);
});

User.unregister()

Unregister the current user. The current user must be authenticated.

monaca.cloud.User.unregister(password: String) : $.Promise

Parameter

Return Value

Errors Code

Errors are returned as Error object.

Example

The below snippet demonstrates how to unregister the current user whose password is "password".

monaca.cloud.User.unregister("password")
.done(function(result)
{
    console.log("You are unregistered");
})
.fail(function(err)
{
    console.log("Err#" + err.code +": " + err.message);
});

User.login()

Sign in a user.

monaca.cloud.User.login(username: String, password: String) : $.Promise

Parameter

Return Value

Within the done() callback, there is a user JSON Object which has the following properties:

• _id : {String}
• _username : {String}
• _createdAt : {Number} unixtime
• _updateAt : {Number} unixtime
• and other user-defined properties.

Errors Code

Errors are returned as Error object.

Example

The following is a typical example of how to login a user with a username "[email protected]" and password "password".

monaca.cloud.User.login("[email protected]", "password")
.done(function(result){
    console.log("Hello again, " + result.user._username);
})
.fail(function(err)
{
    console.log("Err#" + err.code +": " + err.message);
});

User.isAuthenticated()

Return a boolean value whether the user has logged-in or not.

monaca.cloud.User.isAuthenticated() : Boolean

Parameter

• None

Return Value

Example

if (false == monaca.cloud.User.isAuthenticated()) {
    // Go to login
}

User.autoLogin()

When the user restarts the app, this function automatically logs in the user. It is required to enable auto-login feature with Monaca Cloud IDE.

monaca.cloud.User.autoLogin() : $.Promise

Parameter

• None

Return Value

Within the done() callback, there is a user JSON Object which has the following properties:

• _id : {String}
• _username : {String}
• _createdAt : {Number} unixtime
• _updateAt : {Number} unixtime
• and other user-defined properties.

Errors Code

Errors are returned as Error object.

Example

The following code will enable automatic login for a user.

monaca.cloud.User.autoLogin()
.done(function(result)
{
   console.log("Hello again, " + result.user._username);
})
.fail(function(err)
{
   console.log("Err#" + err.code +": " + err.message);
});

User.logout()

Sign out the user. The user must be authenticated. When the user signs out, auto-login will be disabled.

monaca.cloud.User.logout() : $.Promise

Parameter

• None

Return Value

Errors Code

Errors are returned as Error object.

Example

The following example will show how to log out the current user.

monaca.cloud.User.logout()
.done(function(result)
{
   console.log("You are successfully logged out");
})
.fail(function(err)
{
   console.log("Err#" + err.code +": " + err.message);
});

User.updatePassword()

Update password for the current user. The user must be authenticated.

monaca.cloud.User.updatePassword(oldPassword: String, newPassword: String) : $.Promise

Parameter

Return Value

Errors Code

Errors are returned as Error object.

Example

The following code will update the password of a current user from "pass123" to "newPass123".

monaca.cloud.User.updatePassword("oldPassword", "newPassword")
.done(function(result)
{
    console.log("Your password is successfully changed");
})
.fail(function(err)
{
    console.log("Err#" + err.code +": " + err.message);
});

User.sendPasswordResetToken()

Send an email with a token to reset the password in case a user could not log in because of a forgotten password. Before sending this email, it is required to create an email template by using Monaca Cloud IDE in advance. Please refer to Mail Template Management for how to create an email template.

monaca.cloud.User.sendPasswordResetToken(username: String, options: Object) : $.Promise

Parameter

Return Value

Errors Code

Errors are returned as Error object.

Example

The following snippet shows an example of how to send an email with the new token to a user called "username" with his registered email address registered with "email" field.

monaca.cloud.User.sendPasswordResetToken("username", {emailPropertyName:"email"})
.done(function()
{
    console.log("An email was successfully sent.");
})
.fail(function(err)
{
    console.log("Err#" + err.code +": " + err.message);
});

User.resetPasswordAndLogin()

Reset the password of the current user and relogin with the new password.

monaca.cloud.User.resetPasswordAndLogin(username: String, newPassword: String, token: String) : $.Promise

Parameter

Return Value

Within the done() callback, there is a user JSON Object which has the following properties:

• _id : {String}
• _username : {String}
• _createdAt : {Number} unixtime
• _updateAt : {Number} unixtime
• and other user-defined properties.

Errors Code

Errors are returned as Error object.

Example

The following example demonstrates how to reset the password of a user and then login with the new password.

monaca.cloud.User.resetPasswordAndLogin("username", "newPassword", "000000")
.done(function(result)
{
    console.log(result.user._username + ", your password is successfully changed.");
})
.fail(function(err)
{
    console.log("Err#" + err.code +": " + err.message);
});

User.getProperty()

Get a property value of the user. The user must be authenticated.

monaca.cloud.User.getProperty(name: String) : $.Promise

Parameter

Return Value

Errors Code

Errors are returned as Error object.

Example

Refer to the following code for an example of how to get a property value of age of a user.

monaca.cloud.User.login("[email protected]", "password")
.then(function()
{
    return monaca.cloud.User.getProperty("age");
})
.then(function(age)
{
    console.log(age);
})

User.getProperties()

Get an array of property values of the user. The user must be authenticated.

monaca.cloud.User.getProperties(names: Array) : $.Promise

Parameter

Return Value

Within the done() callback, there is:

• user-defined property name: Any user-defined property name

Errors Code

Errors are returned as Error object.

Example

Below is how to get the values of 2 properties of a user.

monaca.cloud.User.login("[email protected]", "password")
.then(function()
{
    return monaca.cloud.User.getProperties(["age", "icon"]);
})
.then(function(properties)
{
    console.log(properties.age);
    console.log(properties.icon);
})

User.saveProperty()

Update a property value of the user. The user must be authenticated.

monaca.cloud.User.saveProperty(name: String, value: String) : $.Promise

Parameter

Return Value

Errors Code

Errors are returned as Error object.

Example

The following example illustrates how to add/update the user’s nickname to "John".

monaca.cloud.User.login("[email protected]", "password")
.then(function()
{
    return monaca.cloud.User.saveProperty("nickname", "John");
})
.then(function()
{
    cosole.log("Your nickname was changed");
})

User.saveProperties()

Update an array of property values of a user. The user must be authenticated.

monaca.cloud.User.saveProperties(properties: Object) : $.Promise

Parameter

Return Value

Errors Code

Errors are returned as Error object.

Example

The following example illustrates how to add/update 2 properties (nickname & email) of a user.

monaca.cloud.User.login("[email protected]", "password")
.then(function()
{
    return monaca.cloud.User.saveProperties({"nickname":"John", "email":"[email protected]"});
})
.then(function()
{
    cosole.log("Your nickname and email were changed");
})

User._oid

Public identifier of a user. When the user has logged-in, monaca.cloud.User._oid is a long string. Otherwise, oid is null.

monaca.cloud.User._oid

Example

var oid = monaca.cloud.User._oid;

See Also:

• User Management
• Backend API
• Backend Memo
• Backend Management API