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 KiiIdentityData and KiiUserFields 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.

Swift:

// Set the username, email address, and phone number.
let builder = KiiIdentityDataBuilder()
builder.userName = "My_New_Name"
builder.email = "myNewEmail@example.com"
builder.phoneNumber = "+15555555555"
let identityData : KiiIdentityData
do{
  identityData = try builder.buildWithError()

  // Set the display name, country, and locale.
  let userFields = KiiUserFields()
  userFields.displayName = "My_New_Name"
  userFields.country = "JP"
  userFields.locale = LocaleContainer()

  // Get the currently logged-in user.
  let user = KiiUser.current()!

  // Update the user attributes.
  try user.update(withIdentityDataSynchronous: identityData, userFields: userFields)
}catch (let retError as NSError){
  // Handle the error.
  return
}

// Set the username, email address, and phone number.
let builder = KiiIdentityDataBuilder()
builder.userName = "My_New_Name"
builder.email = "myNewEmail@example.com"
builder.phoneNumber = "+15555555555"
let identityData : KiiIdentityData
do{
  identityData = try builder.buildWithError()
}catch (let retError as NSError){
  // Handle the error.
  return
}

// Set the display name, country, and locale.
let userFields = KiiUserFields()
userFields.displayName = "My_New_Name"
userFields.country = "JP"
userFields.locale = LocaleContainer()

// Get the currently logged-in user.
let user = KiiUser.current()!

// Update the user attributes.
user.update(with: identityData, userFields: userFields) { (retUser :KiiUser?, error : Error?) -> Void in
  if error != nil {
    // Handle the error.
    return
  }
}

Objective-C:

// Set the username, email address, and phone number.
KiiIdentityDataBuilder *builder = [[KiiIdentityDataBuilder alloc] init];
builder.userName = @"My_New_Name";
builder.email = @"myNewEmail@example.com";
builder.phoneNumber = @"+15555555555";
NSError *error = nil;
KiiIdentityData *identityData = [builder buildWithError:&error];
if (error != nil) {
  // Handle the error.
  return;
}

// Set the display name, country, and locale.
KiiUserFields *userFields = [[KiiUserFields alloc] init];
[userFields setDisplayName:@"My_New_Name"];
[userFields setCountry:@"JP"];
[userFields setLocale: [[LocaleContainer alloc] init]];

// Get the currently logged-in user.
KiiUser *user = [KiiUser currentUser];

// Update the user attributes.
[user updateWithIdentityDataSynchronous:identityData userFields:userFields error:&error];
if (error != nil) {
  // Handle the error.
  return;
}

// Set the username, email address, and phone number.
KiiIdentityDataBuilder *builder = [[KiiIdentityDataBuilder alloc] init];
builder.userName = @"My_New_Name";
builder.email = @"myNewEmail@example.com";
builder.phoneNumber = @"+15555555555";
NSError *error = nil;
KiiIdentityData *identityData = [builder buildWithError:&error];
if (error != nil) {
  // Handle the error.
  return;
}

// Set the display name, country, and locale.
KiiUserFields *userFields = [[KiiUserFields alloc] init];
[userFields setDisplayName:@"My_New_Name"];
[userFields setCountry:@"JP"];
[userFields setLocale: [[LocaleContainer alloc] init]];

// Get the currently logged-in user.
KiiUser *user = [KiiUser currentUser];

// Update the user attributes.
[user updateWithIdentityData:identityData userFields:userFields block:^(KiiUser *user, NSError *error) {
  if (error != nil) {
    // 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 updateWithUserFields:block: 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.

Swift:

// Get the currently logged-in user.
let user = KiiUser.current()!

do {
  // Refresh the user to get the latest user info from Kii Cloud.
  try user.refreshSynchronous()
} catch let error as NSError {
  // Handle the error.
  return
}

// Get the user attributes.
let userName = user.username
let emailAddress = user.email
let phoneNumber = user.phoneNumber
let displayName = user.displayName
let country = user.country
let locale = user.locale

// Get the currently logged-in user.
let user = KiiUser.current()!

// Refresh the user to get the latest user info from Kii Cloud.
user.refresh { (user :KiiUser?, error : Error?) -> Void in
  if error != nil {
    // Handle the error.
    return
  }

  // Get the user attributes.
  let userName = user!.username
  let emailAddress = user!.email
  let phoneNumber = user!.phoneNumber
  let displayName = user!.displayName
  let country = user!.country
  let locale = user!.locale
}

Objective-C:

// Get the currently logged-in user.
KiiUser *user = [KiiUser currentUser];

NSError *error = nil;

// Refresh the user to get the latest user info from Kii Cloud.
[user refreshSynchronous:&error];
if (error != nil) {
  // Handle the error.
  return;
}

// Get the user attributes.
NSString *userId = user.userID;
NSString *userName = user.username;
NSString *emailAddress = user.email;
NSString *phoneNumber = user.phoneNumber;
NSString *displayName = user.displayName;
NSString *country = user.country;
LocaleContainer *locale = user.locale;

// Get the currently logged-in user.
KiiUser *user = [KiiUser currentUser];

// Refresh the user to get the latest user info from Kii Cloud.
[user refreshWithBlock:^(KiiUser *user, NSError *error) {
  if (error != nil) {
    // Handle the error.
    return;
  }

  // Get the user attributes.
  NSString *userId = user.userID;
  NSString *userName = user.username;
  NSString *emailAddress = user.email;
  NSString *phoneNumber = user.phoneNumber;
  NSString *displayName = user.displayName;
  NSString *country = user.country;
  LocaleContainer *locale = user.locale;
}];