Sign Up

Getting users registered with your application is the first step for user management.

Kii Cloud allows users to register with a username/password combination. Optionally, registration can be performed with phone numbers and/or email addresses. When assigning an email address or phone number to a user, you can let Kii Cloud take the steps necessary to verify the credentials (either through a verification email or an SMS).

For more details on the user sign up, please read User Sign up and Sign in.

User Sign-Up

The following sample code shows how to sign up a user with the username user_123456, the e-mail address user_123456@example.com, a phone number +819012345678 and a password 123ABC.

// Create a KiiUser builder.
KiiUser.Builder builder;
builder = KiiUser.BuilderWithName("user_123456");
builder.SetEmail("user_123456@example.com");
builder.SetGlobalPhone("+819012345678");

// Create a user.
KiiUser user = builder.Build();

// Register the user.
user.Register("123ABC", (KiiUser registeredUser, Exception e) => {
  if (e != null)
  {
    // Handle the error.
    return;
  }
});

The basic steps are as follows:

  1. Create a KiiUser instance by calling the BuilderWithName method with a username, optionally setting an email address and phone number with the SetEmail and SetGlobalPhone methods. Then call the Build method.
  2. Register this KiiUser instance with the Register method passing the password as the parameter. At this point, a new account will be created and the user will be signed-in.

If the user with the same name already exists, you will get the ConflictException. Please read Types of Errors for the details on how you can handle the exception in your application.

Sign Up without a Username

You can also create a new account without a username. To create an account with an e-mail address or a phone number, use the BuilderWithEmail and BuilderWithPhone methods respectively. Note that in this case, the email and phone number (SMS) verification must be disabled (please check the next section for more details on the verification mechanism).

Sign up with a Local Phone Number

When you want to specify a local phone number, please also set a valid 2-letter country code using the Country property like in the following example:

string phoneNumber = "09051903944";
string country = "JP";
string password = "123456";

// Create a user.
KiiUser user = KiiUser.BuilderWithPhone(phoneNumber).Build();

// Set the two-letter country code.
user.Country = country;

// Register the user.
user.Register(password, (KiiUser registeredUser, Exception e) => {
  if (e != null)
  {
    // Handle the error.
    return;
  }
});

Auto-detecting How User is Specified

If your application provides a user registration UI with an input field that accepts multiple identifier types, you can use the KiiUser.BuilderWithIdentifier(string). This method accepts one of email address, phone number or username, determines which identifier type is specified, and create a new user.

// Create a KiiUser builder.
KiiUser.Builder builder = null;

try {
  string identifier = "09012345678";

  // Set the indentifier to the KiiUser builder.
  builder = KiiUser.BuilderWithIdentifier(identifier);
} catch (ArgumentException e) {
  // 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 settter.
  string username = "user_123456";
  builder.SetName(username);
} catch (ArgumentException e) {
  // Handle the error.
  return;
}

// Create a user.
KiiUser user = builder.Build();

// If you set a local phone number as an identifier,
// set a country code to the KiiUser instance.
try {
  string country = "JP";
  user.Country = country;
} catch (ArgumentException e) {
  // Handle the error.
  return;
}

string password = "123ABC";

// Register the user.
user.Register(password, (KiiUser registeredUser, Exception e) => {
  if (e != null)
  {
    // Handle the error.
    return;
  }
});

The KiiUser.BuilderWithIdentifier(string) accepts a username, email address, or phone number. The method identifies which identifier type is specified and creates a KiiUser instance accordingly with the KiiUser.Builder.Build() method. If you pass a local phone number, please set a 2-letter country code in the KiiUser instance.

Each identifier can be set with the setter methods of the KiiUser.Builder instance. The set 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. Please read User Identifiers and the Monodoc for more information.

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 Data from other Users feature).

You can, for example, prepare an application scope bucket. When a new user is created, your application can register an object with the UserID (or URI) of this user in the application scope bucket. Later, your application can get a list of users by getting the objects in the bucket. By registering user attributes such as the user names, 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. Please read 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 (please read Security for the related discussion). Consider setting some access controls and accessing the bucket only via Server Code with App Administrator Privilege to protect the data.

Using Email/Phone Verification

You can configure your application to verify the user's email address and phone number. Please read Email Address and Phone Number Verification for the overview on the email and phone verification.

This verification feature is disabled by default. You can toggle the verification on/off on the developer portal. Please check Enabling/Disabling Verification to learn more.

When using the verification feature, a user needs to register at least one identifier (i.e. username, email address or phone number) that can be used without any verification. If the email verification is enabled, for example, a user needs to register either their username or phone number with its verification turned off. Likewise, a user needs to register either their username or email address with its verification turned off if the phone verification is enabled. If both email and phone verification are enabled, a user needs to register their username.

When enabled, the email address and/or phone number will be verified as follows.

E-mail Verification

When the email verification is enabled and an account is registered with an email address, Kii Cloud will send a verification email to the user with a verification link. Signing in with the specified email address will only be allowed if the user previously clicked on the verification link. When the email verification is finished, Kii Cloud will notify the completion via another email.

The email verification is also launched when it is enabled and a user modifies their email address. Signing in with the new email address will be allowed after the user clicks a link in the verification email. When the verification is finished, the user will be notified with another email. The old email will be invalidated at this time. You can use the KiiUser#PendingEmail property to check the old (pending) email address.

Please also check the diagram in the overview.

Setting the Redirection URLs

You can specify web pages where users are redirected when they click the link in the verification email.

You can change the rediction URL on the developer portal. Please read Setting the Redirection URL to learn more.

Setting your Custom Email Templates

You can customize the content of the verification and completion emails by setting the templates. The templates can be set per user locale.

You can customize the email templates on the developer portal. Please read Customizing Emails to learn more.

Please also check a sample code for setting the user locale.

Resending Verification Email

The verification email will be sent automatically to the user when the user registration and the user attribute modification are made.

You can also request to resend the verification email. As shown in the sample code below, execute the RequestResendEmailVerification method while the user is logged-in to request the resend of the verification email.

// Resend a verification mail.
KiiUser.RequestResendEmailVerification((Exception e) => {
  if (e != null)
  {
    // Handle the error.
    return;
  }
});

Phone (SMS) Verification

When the phone verification is enabled and an account is registered with a phone number, Kii Cloud will send an SMS message with a verification code. Your application should then ask the user to type in the verification code to complete the registration. Signing-in with the specified phone number will only be allowed if the user previously submitted the correct verification code.

The phone verification is also launched when it is enabled and a user modifies their phone number. Signing in with the new phone number will be allowed after the user sends the code in the verification SMS message. The old phone number will be invalidated when the verification process is finished. You can use the KiiUser#PendingPhone property to check the old (pending) phone number.

Please also check the diagram in the overview.

Please Note: You must specify a valid mobile phone number in an international phone number format (starting with + and your country code) to properly begin the SMS verification process.

After receiving the SMS verification code from the user, your application should call the VerifyPhone method to complete the verification process.

// Get the currently logged-in user.
KiiUser user = KiiUser.CurrentUser;

// Get a verification code.
string code = "XYZXYZXYZ";

// Verify the phone number using the code sent via SMS.
user.VerifyPhone(code, (KiiUser verifiedUser, Exception e) => {
  if (e != null)
  {
    // Handle the error.
    return;
  }
});

Setting your Custom SMS Template

You can customize the content of the SMS message on the developer portal. Please read Configuring Phone (SMS) Verification to learn more.

Sending Verification SMS

The verification SMS will be sent automatically to the user when the user registration and the user attribute modification are made.

You can also request to resend the verification SMS. As shown in the sample code below, execute the RequestResendPhoneVerificationCode method while the user is logged-in to request the resend of the verification SMS.

// Resend a verification SMS message.
KiiUser.RequestResendPhoneVerificationCode((Exception e) => {
  if (e != null)
  {
    // Handle the error.
    return;
  }
});

Localize the Email Template

By setting a user locale, you can switch the email templates used in the verification process.

You can get the locale of the user device from the CultureInfo.CurrentCulture property. When setting the locale in the KiiUser, please use an instance of the LocaleContainer class as shown in the next snippet. The LocaleContainer class will convert the format of the locale from the platform-specific one to the common one that can be interpreted by the server.

string password = "123456";

// Create a user.
KiiUser user = KiiUser.BuilderWithName("user_123456").Build();

// Set the browser locale.
user.Locale = new LocaleContainer(CultureInfo.CurrentCulture);

// Register the user.
user.Register(password, (KiiUser registeredUser, Exception e) => {
  if (e != null)
  {
    // Handle the error.
    return;
  }
});