In Monaca, you can add user account functionality to your app by using the following Monaca Backend JavaScript APIs.
Method/Property | Description |
---|---|
monaca.cloud.User.register() | Sign up a user |
monaca.cloud.User.validate() | Validate registration parameters |
monaca.cloud.User.unregister() | Unregister the current user |
monaca.cloud.User.login() | Sign in a user |
monaca.cloud.User.isAuthenticated() | Check whether a user has signed in or not |
monaca.cloud.User.autoLogin() | Sign in a user automatically |
monaca.cloud.User.logout() | Sign out a user |
monaca.cloud.User.updatePassword() | Update password for the current user |
monaca.cloud.User.sendPasswordResetToken() | Email a token of new password |
monaca.cloud.User.resetPasswordAndLogin() | Reset password and relogin |
monaca.cloud.User.getProperty() | Get a property value of a user |
monaca.cloud.User.getProperties() | Get property values of a user |
monaca.cloud.User.saveProperty() | Update a property of a user |
monaca.cloud.User.saveProperties() | Update a properties of a user |
monaca.cloud.User._oid | Public identifier of a user |
Sign a user up with his/her username and password.
monaca.cloud.User.register(username: String, password: String, [properties: Object]) : $.Promise
Parameter
Name | Type | Description | Requirement |
---|---|---|---|
username |
String | The username for the user | Must not be a duplicate name of an existing user. Must not include any space characters. Must not be shorter than X characters. Must not be longer than 255 characters. It can be an email address. |
password |
String | The password for the user | Must not include any space characters. Must not be shorter than Y characters. Must not be longer than 80 characters. |
properties |
String | Additional properties of the user. The object needs to be a valid JSON format. The key must not start with an underscore. This parameter is optional. | Key names must consist of [a-zA-Z0-9] characters and must start with [a-zA-Z] . Data size must not exceed the size limit (500KB ). |
X
and Y
values can be set in Backend Setting page under Security section on Monaca Cloud IDE.
Return Value
Type | Description |
---|---|
$.Promise object | Use done() , fail() and always() methods to process result. |
Within the done()
callback, there is a user
JSON Object which has the following properties:
_id
: {String}_username
: {String}_createdAt
: {Number} unixtime_updateAt
: {Number} unixtimeErrors Code
Errors are returned as Error object.
Code | Description |
---|---|
-32602 |
Invalid params |
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);
});
Validate registration parameters.
monaca.cloud.User.validate(username: String, [properties: Object]) : $.Promise
Parameter
Name | Type | Description |
---|---|---|
username |
String | The username for the user |
properties |
JSON Object | The properties of the user |
Return Value
Type | Description |
---|---|
$.Promise object | Use done() , fail() and always() methods to get results. |
Errors Code
Errors are returned as Error object.
Code | Description |
---|---|
-32602 |
Invalid params |
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);
});
Unregister the current user. The current user must be authenticated.
monaca.cloud.User.unregister(password: String) : $.Promise
Parameter
Name | Type | Description |
---|---|---|
password |
String | The password for the user |
Return Value
Type | Description |
---|---|
$.Promise object | Use done() , fail() and always() methods to get results. |
Errors Code
Errors are returned as Error object.
Code | Description |
---|---|
-32602 |
Invalid params |
11 |
User login is required. |
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);
});
Sign in a user.
monaca.cloud.User.login(username: String, password: String) : $.Promise
Parameter
Name | Type | Description |
---|---|---|
username |
String | The username of the user |
password |
String | The password of the user |
Return Value
Type | Description |
---|---|
$.Promise object | Use done() , fail() and always() methods to process result. |
Within the done()
callback, there is a user
JSON Object which has the following properties:
_id
: {String}_username
: {String}_createdAt
: {Number} unixtime_updateAt
: {Number} unixtimeErrors Code
Errors are returned as Error object.
Code | Description |
---|---|
-32602 |
Invalid params |
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);
});
Return a boolean value whether the user has logged-in or not.
monaca.cloud.User.isAuthenticated() : Boolean
Parameter
Return Value
Type | Description |
---|---|
Boolean |
true if already authenticated, otherwise false . |
Example
if (false == monaca.cloud.User.isAuthenticated()) {
// Go to login
}
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
Return Value
Type | Description |
---|---|
$.Promise object | Use done() , fail() and always() methods to process result. |
Within the done()
callback, there is a user
JSON Object which has the following properties:
_id
: {String}_username
: {String}_createdAt
: {Number} unixtime_updateAt
: {Number} unixtimeErrors Code
Errors are returned as Error object.
Code | Description |
---|---|
13 |
Invalid operation (When auto-login feature is disabled). |
-32602 |
Invalid params |
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);
});
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
Return Value
Type | Description |
---|---|
$.Promise object | Use done() , fail() and always() methods to get results. |
Errors Code
Errors are returned as Error object.
Code | Description |
---|---|
-32602 |
Invalid params |
11 |
User login is required. |
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);
});
Update password for the current user. The user must be authenticated.
monaca.cloud.User.updatePassword(oldPassword: String, newPassword: String) : $.Promise
Parameter
Name | Type | Description |
---|---|---|
oldPassword |
String | Old password |
newPassword |
String | New password |
Return Value
Type | Description |
---|---|
$.Promise object | Use done() , fail() and always() methods to get results. |
Errors Code
Errors are returned as Error object.
Code | Description |
---|---|
-32602 |
Invalid params |
11 |
User login is required. |
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);
});
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
Name | Type | Description |
---|---|---|
username |
String | The name of the user |
options |
JSON Object |
|
Return Value
Type | Description |
---|---|
$.Promise object | Use done() , fail() and always() methods to get results. |
Errors Code
Errors are returned as Error object.
Code | Description |
---|---|
-32602 |
Invalid params |
13 |
Invalid operation (When the user has already logged-in). |
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);
});
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
Name | Type | Description |
---|---|---|
username |
String | The username of the user |
newPassword |
String | The new password |
token |
String | The token which the user received via email, sent by User.sendPasswordResetToken() |
Return Value
Type | Description |
---|---|
$.Promise object | Use done() , fail() and always() methods to get result. |
Within the done()
callback, there is a user
JSON Object which has the following properties:
_id
: {String}_username
: {String}_createdAt
: {Number} unixtime_updateAt
: {Number} unixtimeErrors Code
Errors are returned as Error object.
Code | Description |
---|---|
-32602 |
Invalid params |
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);
});
Get a property value of the user. The user must be authenticated.
monaca.cloud.User.getProperty(name: String) : $.Promise
Parameter
Name | Type | Description |
---|---|---|
name |
String | A property name |
Return Value
Type | Description |
---|---|
$.Promise object | Use done() , fail() and always() methods to get result. |
Errors Code
Errors are returned as Error object.
Code | Description |
---|---|
11 |
User login is required. |
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);
})
Get an array of property values of the user. The user must be authenticated.
monaca.cloud.User.getProperties(names: Array) : $.Promise
Parameter
Name | Type | Description |
---|---|---|
name |
Array of String | Properties names |
Return Value
Type | Description |
---|---|
$.Promise object | Use done() , fail() and always() methods to get result. |
Within the done()
callback, there is:
user-defined property name
: Any user-defined property nameErrors Code
Errors are returned as Error object.
Code | Description |
---|---|
11 |
User login is required. |
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);
})
Update a property value of the user. The user must be authenticated.
monaca.cloud.User.saveProperty(name: String, value: String) : $.Promise
Parameter
Name | Type | Description | Requirement |
---|---|---|---|
name |
String | Property name | Must consist of [a-zA-Z0-9] characters and must start with [a-zA-Z] . |
value |
String | The value of the corresponding property name to be added or updated |
Return Value
Type | Description |
---|---|
$.Promise object | Use done() , fail() and always() methods to get result. |
Errors Code
Errors are returned as Error object.
Code | Description |
---|---|
-32602 |
Invalid params |
11 |
User login is required. |
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");
})
Update an array of property values of a user. The user must be authenticated.
monaca.cloud.User.saveProperties(properties: Object) : $.Promise
Parameter
Name | Type | Description |
---|---|---|
properties |
JSON Object | Additional properties of a user to be added/updated |
Return Value
Type | Description |
---|---|
$.Promise object | Use done() , fail() and always() methods to get result. |
Errors Code
Errors are returned as Error object.
Code | Description |
---|---|
-32602 |
Invalid params |
11 |
User login is required. |
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");
})
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: