| Please note that this repo will be archived in the near future. Please do not submit any new changes as they are no longer being accepted. Please contact Broadcom support https://support.broadcom.com/ to report any defects or make a request for an update. Broadcom is continuing support for the SDK but will no longer maintain the public GitHub community. |
|---|
MASUI is the core UI framework of the iOS Mobile SDK, which is part of CA Mobile API Gateway. It provides resources to implement a user login dialog, Social Login, One-Time Password, and Proximity Login (QR code and BLE) saving developers the time of building those UI as well as providing them with a fast way for prototyping apps.
The MASUI framework comes with the following features:
- Default log-in dialog
- Built-in QR Code registration/authentication
- Built-in BLE registration/authentication
- Built-in social network (Google, Facebook, Salesforce, and LinkedIn) registration/authentication
- One-Time Password dialogs
- Channel selection (i.e. email, sms)
- OTP challenger
- Session lock
- Check out our documentation for sample code, video tutorials, and more.
- Download MASUI
- Have general questions or need help?, use Stack Overflow. (Tag 'massdk')
- Find a bug?, open an issue with the steps to reproduce it.
- Request a feature or have an idea?, open an issue.
Contributions are welcome and much appreciated. To learn more, see the Contribution Guidelines.
MASUI supports multiple methods for installing the library in a project.
To integrate MASUI into your Xcode project using CocoaPods, specify it in your Podfile:
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '14.0'
pod 'MASUI'
Then, run the following command using the command prompt from the folder of your project:
$ pod install
For manual install, you add the Mobile SDK to your Xcode project. Note that you must add the MASFoundation library. For complete MAS functionality, install all of the MAS libraries as shown.
- Open your project in Xcode.
- Drag the SDK library files, and drop them into your project in the left navigator panel in Xcode. Select the option,
Copy items if needed. - Select
File->Add files to 'project name'and add the msso_config.json file from your project folder. - In Xcode "Build Setting” of your Project Target, add
-ObjCforOther Linker Flags. - Import the following Mobile SDK library header file to the classes or to the .pch file if your project has one.
#import <MASFoundation/MASFoundation.h>
#import <MASProximity/MASProximity.h>
#import <MASUI/MASUI.h>
The MASUI library contains graphic and xib files to speed up development time. The library provides the following UI components:
- User Login Dialog
- Social Login
- One Time Password
- Session Lock
To use the user login dialog, drag and drop MASUI.framework and MASUIResources.bundle into your project. After the MASUI library is added to the project, MASFoundation automatically detects the presence of the MASUI library and processes the user login as needed.
MASUI provides the following method to enable or disable the login dialog. If MASUI is disabled to handle the authentication, MASUserLoginBlock is invoked to retrieve the username and password.
/**
* Set the handling state of the authentication UI by this library.
*
* @param handle YES if you want the library to enable it, NO if not.
* YES is the default.
*/
+ (void)setWillHandleAuthentication:(BOOL)handle;
The user login dialog prompts whenever MASFoundation realizes that user authentication is required or you call the following method to present the login screen.
//
// Display the login screen
//
[[MASUser currentUser] presentLoginViewControllerWithCompletion:^(BOOL completed, NSError *error){
}];
To customize the user login dialog, you need the MASUI library and create your own login view controller, which inherits MASBaseLoginViewController. After creating your own user login dialog, you simply set the default user login screen in MASUI library, so that the custom login screen prompts whenever the user authentication is required.
::: alert danger
Important! Do not modify properties of MASBaseLoginViewController for any reason. These properties are used internally to process the authentication. Changing them can result in several types of app failures.
:::
Before implementing the custom login dialog, implement the following methods and also invoke the parent's method.
- (void)viewWillReload;
This method is invoked before the user login screen prompt. This method prepares the data source of the UI and other logic with the latest authentication information.
- (void)viewWillReload
{
[super viewWillReload];
//
// Prepare for data source and other logic
//
}
- (void)viewDidReload;
This method is invoked after the user login screen prompt. This method reloads all UI elements and other logic.
- (void)viewDidReload
{
[super viewDidReload];
//
// Reload all UI elements and logic
//
}
- (void)loginWithUsername:(NSString *)username password:(NSString *)password completion:(MASCompletionErrorBlock)completion;
This method can be invoked with the given user credentials to perform user authentication. Note that successful authentication of this method does not dismiss the user login screen; it must be dismissed explicitly by calling the dismiss method.
//
// On your custom IBAction, or other places to perform authentication
//
- (IBAction)onLoginButtonSelected:(id)sender
{
[self loginWithUsername:@"username" password:@"password" completion:^(BOOL completed, NSError *error){
//
// handle the result
//
}];
}
- (void)loginWithAuthorizationCode:(NSString *)authorizationCode completion:(MASCompletionErrorBlock)completion;
This method can be invoked with the given authorization code to perform user authentication. Note that successful authentication of this method does not dismiss the user login screen; it must be dismissed explicitly by calling the dismiss method.
//
// On your custom IBAction or other places to perform authentication
//
- (IBAction)onLoginButtonSelected:(id)sender
{
[self loginWithAuthorizationCode:@"auth_code" completion:^(BOOL completed, NSError *error){
//
// handle the result
//
}];
}
- (void)cancel;
This method can be invoked when users want to cancel the authentication process or close the user login screen. By invoking this method, the user login screen is dismissed.
- (void)cancel
{
[super cancel];
//
// Do what you have to do upon cancel
//
}
- (void)dismissLoginViewControllerAnimated:(BOOL)animated completion: (void (^)(void))completion;
This method can be invoked to dismiss the user login screen upon successful authentication, or other times that you want to dismiss the login screen.
//
// Dismiss the view controller
//
[self dismissLoginViewControllerAnimated:YES completion:nil];
After creating the custom login screen, you must create a view controller object and set it as the default login screen in the MASUI library with the following method.
::: alert danger
Important: Note that the user login dialog view controller object is reusedfor multiple user logins. It is important to properly organize the lifecycle of the UI elements before and after the user authentication with the provided methods.
:::
/**
Set the custom login view controller for handling by MASUI library
@param viewController view controller object that inherited MASBaseLoginViewController
*/
+ (void)setLoginViewController:(MASBaseLoginViewController *)viewController;
The social login feature is included in the user login dialog (described in the previous section). No configuration is required to set up the social login.
Session lock screen is provided by simply dropping the MASUI.framework and MASUIResource.bundle into your project. MASFoundation detects the presence of the MASUI library and presents the session lock screen upon the API call.
/**
Display currently set lock screen view controller in MASUI for locked session
@param completion MASCompletionErrorBlock to notify the result of the displaying lock screen.
*/
+ (void)presentSessionLockScreenViewController:(MASCompletionErrorBlock)completion;
You can customize the session lock screen with custom logic for locking and unlocking the session, and for branding. The session lock screen must inherit from the MASViewController (MASUI library). For more information about fingerprint session lock APIs in the MASFoundation library, see Fingerprint Sessions Lock section.
After creating your own screen, simply set the default session lock screen in the MASUI library; your own screen then prompts when you call to present the session lock screen.
/**
Set custom lock screen view controller that inherits MASViewController
@param viewController MASViewController of the lock screen
*/
+ (void)setLockScreenViewController:(MASViewController *)viewController
To use the One Time Password dialogs, drag and drop the MASUI.framework and MASUIResources.bundle into your project. The MASFoundation detects the presence of the MASUI library and processes the One Time Password.
MASUI provides the following method to enable or disable the OTP Delivery Channel dialog.
/**
* Set the handling state of the OTP authentication UI by this framework.
*
* @param handle YES if you want the framework to enable it, NO if not.
* YES is the default.
*/
+ (void)setWillHandleOTPAuthentication:(BOOL)handle;
If MASUI is disabled to handle the OTP authentication, MASOTPChannelSelectionBlock is invoked to retrieve the OTP delivery channels.
MASUI provides the following method to enable or disable the One Time Password dialog.
/**
* Set the handling state of the OTP authentication UI by this framework.
*
* @param handle YES if you want the framework to enable it, NO if not.
* YES is the default.
*/
+ (void)setWillHandleOTPAuthentication:(BOOL)handle;
If MASUI is disabled to handle the OTP authentication, MASOTPCredentialsBlock is invoked to retrieve the one time password.
Copyright (c) 2019 Broadcom. All Rights Reserved. The term "Broadcom" refers to Broadcom Inc. and/or its subsidiaries.
This software may be modified and distributed under the terms of the MIT license. See the LICENSE file for details.