Predefined Fields

Kii Cloud SDK provides the predefined fields for storing the following user attributes:

Field Name JSON Field Name Explanation
User ID userID User ID used in REST API (Example: 1234567-89ab-cdef-0123-456789abcdef`)
Internal User ID internalUserID User ID (for internal usage).
Username loginName Username for login. The field only exists when a user signs up with his username.
Email Address emailAddress Email address for login. The field only exists when a user signs up with his email address.
Email Verified Flag emailAddressVerified "false" if the email verification is enabled, but the email address is not yet verified. "true" otherwise.
Phone Number phoneNumber Phone number for login. The value is always stored in the international phone number format. The field only exists when a user signs up with his phone number.
Phone Verified Flag phoneNumberVerified "false" if the phone verification is enabled, but the phone number is not yet verified. "true" otherwise.
Display Name displayName Display name. The system does not use this value, so your application can put any value. The field only exists when a user specifies the display name. The display name can have 1 to 50 Unicode characters.
Country country 2-letter country code like US, JP or CN. The field only exists when a user specifies the country.
When you are using the domestic phone number format, this value will be used to interpret the number (e.g., if you set JP here with the phone number 09011111111, the SDK will interpret the phone number as +819011111111). The value will not be auto-filled from the international phone number format.
Locale locale User's locale. The value is used for deciding the template to be applied for the email address and phone number verification.

Users can browse other user's fields, but you need to enable the "Expose Full User Data to Others" option to allow them to browse all fields. If the option is disabled, you can only fetch UserID, username and display name. See Retrieving Other User's Data for more information.

Setting and updating predefined fields

We use the IdentityData and UserFields classes for setting the predefined fields. Each class holds the following information:

  • IdentityData
    • Username
    • Email address
    • Phone number
  • UserFields
    • Display name
    • Country
    • Locale

The user ID is assigned automatically when the user is created. You cannot modify the user ID.

The following example illustrates how to set the predefined fields.

  • try {
  // Set the username, email address, and phone number.
  IdentityData.Builder builder =
    IdentityData.Builder.newWithName("user_123456");
  builder.withEmail("user_123456@example.com")
         .withPhone("+919012345678");
  IdentityData identityData = builder.build();

  // Set the display name, country, and locale.
  UserFields userFields = new UserFields();
  userFields.putDisplayName("My_New_Name");
  userFields.putCountry("US");
  userFields.putLocale(new LocaleContainer(Locale.getDefault()));

  // Get the currently logged-in user.
  KiiUser user = KiiUser.getCurrentUser();

  // Update the user attributes.
  user.update(identityData, userFields);
} catch (IOException e) {
  // Handle the error.
} catch (AppException e) {
  // Handle the error.
}
  • // Set the username, email address, and phone number.
IdentityData.Builder builder =
  IdentityData.Builder.newWithName("user_123456");
builder.withEmail("user_123456@example.com")
       .withPhone("+919012345678");
IdentityData identityData = builder.build();

// Set the display name, country, and locale.
UserFields userFields = new UserFields();
userFields.putDisplayName("My_New_Name");
userFields.putCountry("US");
userFields.putLocale(new LocaleContainer(Locale.getDefault()));

// Get the currently logged-in user.
KiiUser user = KiiUser.getCurrentUser();

// Update the user attributes.
user.update(identityData, userFields, new KiiUserUpdateCallback() {
  @Override
  public void onUpdateCompleted(KiiUser kiiUser, Exception exception) {
    if (exception != null) {
      // Handle the error.
      return;
    }
  }
});

If an existing field is not explicitly specified for the update operation, the field remains unchanged on Kii Cloud.

The fields are updated on Kii Cloud and in the KiiUser instance after the update method is successfully completed.

If you modify an email address or phone number while their verification is enabled, the corresponding verification flow will be launched. You can log in with the new email address and phone number after the verification is done. See Verifying the User's Email Address and Verifying the User's Phone Number for more details.

Getting predefined fields

The following example illustrates how to get the predefined fields.

  • // Get the currently logged-in user.
KiiUser user = KiiUser.getCurrentUser();

try {
  // Refresh the user to get the latest user info from Kii Cloud.
  user.refresh();

  // Get the user attributes.
  String userId = user.getID();
  String userName = user.getUsername();
  String emailAddress = user.getEmail();
  String phoneNumber = user.getPhone();
  String displayName = user.getDisplayname();
  String country = user.getCountry();
  LocaleContainer localeContainer = user.getLocale();
} catch (IOException e) {
  // Handle the error.
} catch (AppException e) {
  // Handle the error.
}
  • // Get the currently logged-in user.
KiiUser user = KiiUser.getCurrentUser();

// Refresh the user to get the latest user info from Kii Cloud.
user.refresh(new KiiUserCallBack() {
  @Override
  public void onRefreshCompleted(int token, Exception exception) {
    if (exception != null) {
      // Handle the error.
      return;
    }

    // Get the user attributes.
    String userId = user.getID();
    String userName = user.getUsername();
    String emailAddress = user.getEmail();
    String phoneNumber = user.getPhone();
    String displayName = user.getDisplayname();
    String country = user.getCountry();
    LocaleContainer localeContainer = user.getLocale();
  }
});