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 3:

  • // 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 3:

  • // 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;
    }];