Signing up

The most basic method to create a user in Kii Cloud is specifying an identifier such as a username and a password. This topic explains how to create a user with a username, an email address, or a phone number.

Identifying a user

When a user is created, it can be identified with any of a username, email address, phone number, and a combination of them.

For example, a user becomes available by taking the following steps.

  1. Create and register a user by specifying the username "id123456" and password "123ABC".
  2. Authenticate a user by specifying the username "id123456" and password "123ABC".

Once the user registration or user authentication is done, this user is treated as logged in (the user will be automatically logged in after the registration).

You can also identify users with their email addresses and phone numbers (check the table below).

Information to be provided on user registration Information to be provided on user authentication
Username Email address Phone number Password Identifier accepted Password
Yes - - Required Username Required
Yes - Yes Required Username or phone number Required
Yes Yes - Required Username or email address Required
Yes Yes Yes Required Username or email address or phone number Required
- - Yes *1 Required Phone number Required
- Yes *2 - Required Email address Required
- Yes *3 Yes *3 Required Email address or phone number Required

*1 You need to disable the phone verification; you will get an error otherwise.
*2 You need to disable the email verification; you will get an error otherwise.
*3 You need to disable either the phone verification or the email verification; you will get an error otherwise.

For example, suppose that a user registers with the username "id123456", the email address "user@mydomain.com" and password "123ABC". In this case, the user can login with one of the two ways:

  • Login with the username "id123456" and password "123ABC".
  • Login with the username "user@mydomain.com" and password "123ABC".

Please note that a user can set their email address or phone number instead of their username upon the registration. If you do not want to let them use these values for the authentication purpose (but still want to save them), consider storing the values in custom fields (See User Attributes) or storing them in a dedicated user scope bucket.

When logging in, you can specify a username, or email address or (international) phone number instead of a username in the same API. The SDK will interpret the identifier starting with "@" as an email address, the one starting with "+" as a phone number and all others as a username.

A user can change his email address and phone number after the registration, but he cannot change the username.

When using an email address and phone number for authentication, you can also verify them (See Verifying the User's Email Address and Phone Number). By enabling this feature, you can let users log in only after these identifiers are verified.

Signing up a user

Signing up with the KiiUser factory method

The following sample code shows how to sign up a user with his/her username and password. In this case, a new user account is created with the username "user_123456" and a password "123ABC".

  • var username = "user_123456";
var password = "123ABC";

// Create a user.
var user = KiiUser.userWithUsername(username, password);

// Register the user.
user.register().then(
  function(theUser) {
    // Do something.
  }
).catch(
  function(error) {
    // Handle the error.
    var theUser = error.target;
    var errorString = error.message;
  }
);
  • var username = "user_123456";
var password = "123ABC";

// Create a user.
var user = KiiUser.userWithUsername(username, password);

// Register the user.
user.register({
  success: function(theUser) {
    // Do something.
  },
  failure: function(theUser, errorString) {
    // Handle the error.
  }
});

Here is another example. The following sample code shows how you can create a new account with the username "user_123456", an email address "user_123456@example.com" and a password "123ABC".

  • var username = "user_123456";
var emailAddress = "user_123456@example.com";
var password = "123ABC";

// Create a user.
var user = KiiUser.userWithEmailAddressAndUsername(emailAddress, username, password);

// Register the user.
user.register().then(
  function(theUser) {
    // Do something.
  }
).catch(
  function(error) {
    // Handle the error.
    var theUser = error.target;
    var errorString = error.message;
  }
);
  • var username = "user_123456";
var emailAddress = "user_123456@example.com";
var password = "123ABC";

// Create a user.
var user = KiiUser.userWithEmailAddressAndUsername(emailAddress, username, password);

// Register the user.
user.register({
  success: function(theUser) {
    // Do something.
  },
  failure: function(theUser, errorString) {
    // Handle the error.
  }
});

The following sample code shows how you can create a new account with the username "user_123456", a phone number "+819012345678" and a password "123ABC".

  • var username = "user_123456";
var phoneNumber = "+819012345678";
var password = "123ABC";

// Create a user.
var user = KiiUser.userWithPhoneNumberAndUsername(phoneNumber, username, password);

// Register the user.
user.register().then(
  function(theUser) {
    // Do something.
  }
).catch(
  function(error) {
    // Handle the error.
    var theUser = error.target;
    var errorString = error.message;
  }
);
  • var username = "user_123456";
var phoneNumber = "+819012345678";
var password = "123ABC";

// Create a user.
var user = KiiUser.userWithPhoneNumberAndUsername(phoneNumber, username, password);

// Register the user.
user.register({
  success: function(theUser) {
    // Do something.
  },
  failure: function(theUser, errorString) {
    // Handle the error.
  }
});

You can also create a new account without a username as in the sample code below.

  • Signing up with a combination of an email address and a password
  • var emailAddress = "user_123456@example.com";
var password = "123ABC";

// Create a user.
var user = KiiUser.userWithEmailAddress(emailAddress, password);

// Register the user.
user.register().then(
  function(theUser) {
    // Do something.
  }
).catch(
  function(error) {
    // Handle the error.
    var theUser = error.target;
    var errorString = error.message;
  }
);
  • var emailAddress = "user_123456@example.com";
var password = "123ABC";

// Create a user.
var user = KiiUser.userWithEmailAddress(emailAddress, password);

// Register the user.
user.register({
  success: function(theUser) {
    // Do something.
  },
  failure: function(theUser, errorString) {
    // Handle the error.
  }
});
  • Signing up with a combination of a phone number and a password
  • var phoneNumber = "+819012345678";
var password = "123ABC";

// Create a user.
var user = KiiUser.userWithPhoneNumber(phoneNumber, password);

// Register the user.
user.register().then(
  function(theUser) {
    // Do something.
  }
).catch(
  function(error) {
    // Handle the error.
    var theUser = error.target;
    var errorString = error.message;
  }
);
  • var phoneNumber = "+819012345678";
var password = "123ABC";

// Create a user.
var user = KiiUser.userWithPhoneNumber(phoneNumber, password);

// Register the user.
user.register({
  success: function(theUser) {
    // Do something.
  },
  failure: function(theUser, errorString) {
    // Handle the error.
  }
});

Note that in these cases, the email and phone number (SMS) verification must be disabled (See the next section for more details on the verification mechanism).

Other sign-up patterns, such as signing-up with {email address, phone number, password} and {username, email address, phone number, password}, are also supported. Please refer to the KiiUser Class description in the JSDoc for details.

In all cases, the errorString in the failure callback will return the string "USER_ALREADY_EXIST:" if the user with the same name already exists. See Error details for the details on how you can handle the exception in your application.

Signing up with the KiiUserBuilder class

Instead of using the factory method of the KiiUser class, you can also use a KiiUserBuilder instance to create a KiiUser instance. In this section, We present how to use the KiiUserBuilder#builderWithIdentifier(string, string).

  • var identifier = "09012345678";
var password = "123ABC";

// Create a KiiUser builder.
var builder = KiiUserBuilder.builderWithIdentifier(identifier, password);
if (builder == null) {
  // Handle the error.
  return;
}

try {
  // You can set a username, email address, global phone number, and
  // local phone number to a builder with a corresponding setter.
  var username = "user_123456";
  builder.setUsername(username);
} catch (e) {
  // Handle the error.
  return;
}

// Create a user.
var user = builder.build();

// If you set a local phone number as an identifier,
// set a country code to the KiiUser instance.
var country = "JP";
user.setCountry(country);

// Register the user.
user.register().then(
  function(theUser) {
    // Do something.
  }
).catch(
  function(error) {
    // Handle the error.
    var theUser = error.target;
    var errorString = error.message;
  }
);
  • var identifier = "09012345678";
var password = "123ABC";

// Create a KiiUser builder.
var builder = KiiUserBuilder.builderWithIdentifier(identifier, password);
if (builder == null) {
  // Handle the error.
  return;
}

try {
  // You can set a username, email address, global phone number, and
  // local phone number to a builder with a corresponding setter.
  var username = "user_123456";
  builder.setUsername(username);
} catch (e) {
  // Handle the error.
  return;
}

// Create a user.
var user = builder.build();

// If you set a local phone number as an identifier,
// set a country code to the KiiUser instance.
var country = "JP";
user.setCountry(country);

// Register the user.
user.register({
  success: function(retUser) {
    // Do something.
  },
  failure: function(theUser, errorString) {
    // Handle the error.
  }
});

The KiiUserBuilder#builderWithIdentifier(string, string) accepts a username, email address, or phone number in the first argument. The method accepts a password in the second argument. The method identifies which identifier type is specified in the first argument and creates a KiiUser instance accordingly with the KiiUserBuilder#build() method. If you pass a local phone number to the first argument, set a 2-digit country code in the KiiUser instance.

Each identifier can be set with the setter method of the KiiUserBuilder instance. The setter method validates the input. If the input is invalid, the setter method throws an exception. Please read the Limitations for more details.

Limitations

Some limitations (i.e., number and type of characters) apply to the user identifiers.

Some of the limits applied to identifiers are slightly different among SDKs. In this section, we will explain the strictest one in among the SDKs.

Username

A username must be 3 to 64 characters. The accepted characters are alphanumeric, "_" (underscore), "-" (hyphen) and "." (period).

It must be unique; a user will get an error when he tries to register the username that is already registered in the application.

A username is also used when a user queries other users (e.g. executing the findUserByUserName in the Kii Cloud SDK for Android).

Upper case alphabets in a username are converted to lower case when the username is registered.

Email address

An email address must be in the form of "username@domain".

  • The username part is composed of alphanumeric, ".", "_", "%", "+" and "-".
  • The domain part is composed of alphanumeric and ".".

The length of an email address must be 200 characters or shorter. The address must include "@" and must conform to RFC 822. Note that the details of error checking vary slightly depending on the platform.

It must be unique; a user will get an error when he tries to register or change his email address to the email address that is already registered in the application.

Phone number

You can specify a phone number in two ways (note that some SDK only accept the international phone number format):

  • International phone number format: This format will have a country code and local phone number after a "+" (plus) sign. The phone number is composed of 10 to 15 numbers (no hyphen or period). For example, the phone number "123-456-7890" in the United States is represented as "+11234567890".

  • Local phone number format: This format will use the domestic phone number. The country is expressed in two capital letters defined in libphonenumber. For example, the Android SDK asks you to specify the domestic phone number "1234567890" and the 2-letter country code "US". The REST API asks you to use the format "US-1234567890".

The international and local phone number formats are interoperable. The phone number "+11234567890" and "US-1234567890" identify the same user.

The phone number must be unique; a user will get an error when he tries to register or change his phone number to the number that is already registered in the application.

Only a mobile phone number is accepted. If a landline phone number is specified, an error will be returned. A library in the server determines the specified number is for a mobile phone or a landline.

Password

A password must be 4 to 50 characters. The accepted characters are alphanumeric and symbol (\u0020 to \u007e in Unicode).

Hint for creating a user list

Kii Cloud currently does not provide an API for getting a list of users; you need to implement the feature in your application if you want to get the list (Note: if you just need to get a single user, you might be able to implement it with Retrieving Other User's Data feature).

You can, for example, prepare an application scope bucket. When a new user is created, your application can register an object with the user ID (or URI) of this user in the application scope bucket. Later, your application can get a list of users by getting the KiiObjects in the bucket. By registering user attributes such as the usernames, you can also query for users with these attributes.

Please note that the overall performance of this method will degrade when the number of users increases dramatically. You will need to implement the feature so as to avoid querying the massive amount of users. See Performance for the related discussion.

Also note that any users can access the application scope bucket. Registering user's private information such as email addresses in the bucket make them vulnerable (See Security for the related discussion). Consider setting some access controls and accessing the bucket only via server code with the app administrator privilege to protect the data.