Implementing the Title Screen

The screen elements that are related to the title screen are shown below.

The storyboard has the following settings:

The title screen is displayed as the first screen when the mobile app starts.
The segues set to the "Login" button and the "Register" button on the title screen open the login screen and the user registration screen, respectively.
Each screen is associated with the view controller class indicated in the figure.

Check the source code below.

Swift

Objective-C

Title screen

When the mobile app starts, the TitleViewController class is initialized. This class implements the title screen.

After the view is loaded, the viewDidLoad() method below is called.

override func viewDidLoad() {
  super.viewDidLoad()

  // If the user has been logged in, show the data listing screen.
  KiiUser.authenticate(storedCredentials: { (user :KiiUser?, error : Error?) -> Void in
    if error != nil {
      // Show the title screen.
      return;
    }

    // Show the data listing screen.
    let app = UIApplication.shared.delegate! as! AppDelegate
    app.showBalanceList()
  })
}

- (void)viewDidLoad {
  [super viewDidLoad];

  // If the user has been logged in, show the data listing screen.
  [KiiUser authenticateWithStoredCredentials:^(KiiUser *user, NSError *error) {
    if (error != nil) {
        // Show the title screen.
        return;
    }

    // Show the data listing screen.
    AppDelegate *app = (AppDelegate*)[[UIApplication sharedApplication] delegate];
    [app showBalanceList];
  }];
}

The viewDidLoad() method restores the user's login state and switches the screen according to the login state.

In order to restore the login credentials, the authenticate(storedCredentials:) method of the KiiUser class is called. You can restore such authentication information because the Kii Cloud SDK automatically saves the internal authentication information to the keychain when the user is successfully logged in or refreshed.

If the credentials are not restored, the Kii Cloud SDK cannot use the user information that was saved last time. The title screen remains open for re-authentication.
If the credentials are restored, the user has been logged in. The showBalanceList() method in the AppDelegate class is called to immediately open the data listing screen as the login action by the user can be skipped.

Note that the user argument in the callback for the authenticate(storedCredentials:) method does not contain some of the user information. When the login information is restored, the user argument is created from the minimum information saved in the keychain without accessing Kii Cloud. In order to access detailed information such as user attributes, you need to refresh the user. For more information, see the learn more section at the end of this topic.

Access token in the saved information

You can restore the user information that was valid for the last successful login from the keychain by using the authenticate(storedCredentials:) method.

The access token is important among other various pieces of data such as the user ID and username included in the saved information. It is a string that identifies an authenticated user.

The access token is one of the basic concepts of Kii Cloud and there are many opportunities to use it. Let us review the usage of the access token.

The mobile app accesses Kii Cloud via the Kii Cloud SDK. The SDK sends requests to Kii Cloud on the basis of the specification of the public REST API.

When the user logs in with the username and password, Kii Cloud issues an access token that enables access based on the user's privileges.

In the subsequent requests of the REST API, the access token is specified in the HTTPS header. The token identifies the requesting user and allows processing under the user's privileges.

In order to restore the login state including the access token, use the authenticate(storedCredentials:) method in your own mobile app as with Kii Balance. Additionally, a lower-level API supports login with an access token only. That is, in order to log in with the authenticate(withToken:andBlock:) method of the KiiUser class, you can save the access token as a string somewhere at a successful login.

Tapping the "Login" button or the "Register" button on the title screen displays the login screen or the user registration screen, respectively.

These screens are similarly implemented with the LoginViewController class and the RegisterViewController class. The difference is that those classes use different APIs of the Kii Cloud SDK for manipulating a KiiUser object.

The code to call the Kii Cloud SDK is the same as that for Hello Kii. That is, it calls the non-blocking API with the arguments of the username username and password password. For more information about calling the API, see Login Screen Implementation in the Hello Kii tutorial.

Login

@IBAction func loginClicked(_ sender: Any) {
  // Get a username and password.
  let username = self.usernameText.text!
  let password = self.passwordText.text!

  self.closeKeyboard()

  // Show the progress.
  let progress = KiiProgress.create(message:"Login...")
  self.present(progress, animated: false, completion: nil)

  // Log in the user.
  KiiUser.authenticate(username, withPassword: password) { (user, error) -> Void in
    if error != nil {
      progress.dismiss(animated: true, completion: {
        let description = (error! as NSError).userInfo["description"] as! String
        let alert = KiiAlert.create(title: "Error", message: description)
        self.present(alert, animated: true, completion: nil)
      })
      return
    }
    progress.dismiss(animated: false, completion: nil)
    let app = UIApplication.shared.delegate as! AppDelegate
    app.showBalanceList()
  }
}

- (IBAction)loginClicked:(id)sender {
  // Get a username and password.
  NSString *username = self.usernameText.text;
  NSString *password = self.passwordText.text;

  [self closeKeyboard];

  // Show the progress.
  UIAlertController *progress = [KiiProgress createWithMessage:@"Login..."];
  [self presentViewController:progress animated:NO completion:nil];

  // Log in the user.
  [KiiUser authenticate:username withPassword:password andBlock:^(KiiUser *user, NSError *error) {
    if (error != nil) {
      [progress dismissViewControllerAnimated:YES completion:^{
        UIAlertController *alert = [KiiAlert createWithTitle:@"Error" andMessage:error.description];
        [self presentViewController:alert animated:YES completion:nil];
      }];
      return;
    }
    [progress dismissViewControllerAnimated:YES completion:nil];
    AppDelegate *app = (AppDelegate*)[[UIApplication sharedApplication] delegate];
    [app showBalanceList];
  }];
}

User registration

@IBAction func registerClicked(_ sender: Any) {
  // Get a username and password.
  let username = self.usernameText.text!
  let password = self.passwordText.text!

  self.closeKeyboard()

  // Show the progress.
  let progress = KiiProgress.create(message:"Registering...")
  self.present(progress, animated: false, completion: nil)

  // Register the user.
  let user = KiiUser(username: username, andPassword: password)
  user.performRegistration { (user :KiiUser?, error : Error?) -> Void in
    if error != nil {
      progress.dismiss(animated: true, completion: {
        let description = (error! as NSError).userInfo["description"] as! String
        let alert = KiiAlert.create(title: "Error", message: description)
        self.present(alert, animated: true, completion: nil)
      })
      return
    }
    progress.dismiss(animated: false, completion: nil)
    let app = UIApplication.shared.delegate as! AppDelegate
    app.showBalanceList()
  }
}

- (IBAction)registerClicked:(id)sender {
  // Get a username and password.
  NSString *username = self.usernameText.text;
  NSString *password = self.passwordText.text;

  [self closeKeyboard];

  // Show the progress.
  UIAlertController *alert = [KiiProgress createWithMessage:@"Registering..."];
  [self presentViewController:alert animated:NO completion:nil];

  // Register the user.
  KiiUser *user = [KiiUser userWithUsername:username andPassword:password];
  [user performRegistrationWithBlock:^(KiiUser *user, NSError *error) {
    if (error != nil) {
      [alert dismissViewControllerAnimated:YES completion:^{
        UIAlertController *alert = [KiiAlert createWithTitle:@"Error" andMessage:error.description];
        [self presentViewController:alert animated:YES completion:nil];
      }];
      return;
    }
    [alert dismissViewControllerAnimated:YES completion:nil];
    AppDelegate *app = (AppDelegate*)[[UIApplication sharedApplication] delegate];
    [app showBalanceList];
  }];
}

If the processing is successful, the showBalanceList() method of the AppDelegate class is called to open the data listing screen.

If the processing fails, the current screen remains open so that the user can enter their credentials.

Kii Balance uses the KiiProgress class for indicating the progress of a task and the KiiAlert class for displaying an alert. Both classes use the UIAlertController class in the iOS SDK for displaying the user interface that is, therefore, shown and dismissed in accordance with standard usage of the iOS SDK. In order to display an error, a KiiAlert instance is initialized in the callback that notifies the completion of dismissing a KiiProgress instance.

While the Kii Cloud SDK for Android has APIs to validate the username and password, the Kii Cloud SDK for iOS does not have equivalent APIs. Implement your own validation step or directly execute the login or user registration API as shown in the above sample code.

What's next?

Let us review how to get data in the data listing screen.

Go to Getting the Data List.

If you want to learn more...

For more information about logging in with the saved information, see Login with the Auto-Saved Credentials.
For logging in with an access token, see Login by Manually Specifying an Access Token.

Implementing the Title Screen

Title screen

Access token in the saved information

Login and user registration screens

What's next?

If you want to learn more...