# Getting started with the BBAE iOS SDK
## Import and install dependencies
### 1. Import the BBAE SDK files
The BBAE SDK consists of the following files:
- BBAESDK.framework
- BBAESDKResource.bundle
### 3. Add application permissions
Open `info.plist` and add the following permissions.
```
// For accessing camera, which is used during account application process for uploading identity document
<key>NSCameraUsageDescription</key>
<string>Description text</string>
// For accessing photo library, which is used during account application process for uploading identity document
<key>NSPhotoLibraryUsageDescription</key>
<string>Description text</string>
// For saving photos taken by camera
<key>NSPhotoLibraryAddUsageDescription</key>
<string>Description text</string>
```
### 4. Configure build setting
- Set Build Setting -> Other Link Flags to -ObjC
## Start using the BBAE SDK
### 1. Obtain an application key
The BBAE SDK will require a valid application key in order to run.
For development use, please contact BBAE developers for a test-environment key.
For production use, BBAE will issue an application key when you sign up for integration.
### 2. Initialize BBAE SDK in your application
You may initialize the BBAE SDK in `application:didFinishLaunchingWithOptions` or anywhere before running the SDK.
Example:
```
/**
* Initialize the BBAE SDK and register application key
*/
[[BBAESDK sharedInstance] registerAppKey:@"fakeappkey" options:nil];
/**
* setDelegate is used to handle events, such as session expired.
*/
[[BBAESDK sharedInstance] setDelegate:self]; // self implements BBAESDKDelegate
/**
* Configuration options:
* 1. debug mode
* 2. (debug mode only) log level
* 3. (debug mode only) configure SDK API URLs
*/
[[BBAESDK sharedInstance]
debugModel:YES
logLevel: BBAESDKLOGLEVEL_NONE
baseURl:@"base-url.bbaecache.com"
];
/**
* Set sessionId, which is used to identify a user
*/
[[BBAESDK sharedInstance] setSessionId:@"sessionIdString"];
/**
* Change theme at runtime
* options:
* 1. theme color
*/
[[BBAESDK sharedInstance] setAppTheme:BBAESDKTheme_Black];
/**
* Change language at runtime
* options:
* 1. application language
*/
[[BBAESDK sharedInstance] setAppLanguage:BBAESDKLanguage_English];
/**
* Return the status of the SDK
* returns:
* 1. BBAE_SESSION_NONE
* 2. BBAE_SESSION_VALIDATING
* 3. BBAE_SESSION_OK
*/
[BBAESDK sharedInstance].status;
/**
* Weather enable online customer service.
* options:
* 1. BOOL YES or NO
*/
[[BBAESDK sharedInstance] enableOnlineCustomerService:YES];
/**
* Set BBAESDKCustomerServiceDelegate is used to config customer service, such as returnOnlineCustomerServiceViweController.
*/
[[BBAESDK sharedInstance] setBBAESDKCustomerServiceDelegate:self]; // self implements BBAESDKCustomerServiceDelegate
/**
* Set customerPhoneService, which is used to identify phone service list.
* options:
* 1. NSArray<PhoneModel *>
* PhoneModel contains two property : showName realNumber
*/
[[BBAESDK sharedInstance] setCustomerServicePhones:@[PhoneModel,PhoneModel]];
/**
* Return the notificationCenter of the SDK
* returns:
* NSNotificationCenter
*/
[BBAESDK sharedInstance].notificationCenter;
```
#### 2.1. Managing user session
The BBAE SDK takes a defensive measure on managing user sessions in order to protect user data and privacy. This means that it will actively confirm and validate a session as it's being used. It also provides methods that application developers should utilize in order to properly manage sessions.
```
/**
* BBAESDKDelegate methods
*/
/**
* onSessionExpired() method is called whenever the BBAE SDK tries to validate the current session.
* It should return the current valid sessionId, and the BBAE SDK will proceed the authentation process with the returned sessionId.
*
* If the same sessionId fails authentication twice, the BBAE SDK will enter a frozen state and call onSessionError().
*/
-(NSString *)onSessionExpired {
// Should return a currently valid session
}
/**
* onSessionError() is called when a sessionId provided to the BBAE SDK fails two consecutive times.
*
* The BBAE SDK is now in a frozen state until setSessionId() is called again to resume authentication process.
*/
-(void)onSessionError {
// The SDK is in a frozen state since session authentication failed too many times.
// Call setSessionId() again to kickstart the authentication process again.
}
/**
* onSessionSuccess() is called when the session id is validated. optional.
*
*/
-(void)onSessionSuccess {
// It will be triggered when you set a valid sessionId each time.
}
/**
* onSessionEnd() is called when user clicks log out. optional.
*
* Notice: calling `logout` or SessionError won't trigger this function.
*
*/
-(void)onSessionEnd {
}
/**
* Set sessionId and trigger user authentication process
*/
[[BBAESDK sharedInstance] setSessionId:@"sessionIdString"];
/**
* Log out the current session and close existing views
*/
[[BBAESDK sharedInstance] logout];
```
#### 2.2. Setting customer service
The BBAE SDK provide methods for user to customized service center. The default customer service is off.
```
/**
* enable or disable online customer service.
*/
[[BBAESDK sharedInstance] enableOnlineCustomerService:Yes];
[[BBAESDK sharedInstance] setCustomerServiceDelegate:self];
/**
* BBAESDKCustomerServiceDelegate methods
*/
@optional
/**
* getUnreadMessageCount() will be called when show message tips.
*/
- (int)getUnreadMessageCount {
// Should return current unread message count.
}
/**
* getCustomerServicePhones() will be called when needing to display.
*/
-(NSArray<id<BBAEPhoneModel>> * )getCustomerServicePhones:(BBAEEnv *)env {
// Should return phone models
}
- (UIViewController *)createOnlineCustomerServiceViewController:(BBAEEnv *)env {
// Should return online customer service view controller
}
```
#### 2.3. Setting Share Module
```
/**
* BBAEShareTypeDelegate methods
*/
// Return the share channel id , not important but should be unique
- (NSString *)getShareId:(BBAEEnv *)env;
// Return the share channel name for displaying
- (NSString *)getShareName:(BBAEEnv *)env;
// Return the share channel image for displaying
- (UIImage *)getShareImage:(BBAEEnv *)env;
// This function will be fired when user clicks the share channel.
- (void)onShare:(ShareModel *shareModel);
/**
* Add the share channels
*/
[[BBAESDK sharedInstance] setDefaultShareTypes:[shareType1],[shareType2]...];
```
### 3. Display BBAE SDK feature modules
The BBAE SDK has various "entry points" that you can bring up and show to users. Each entry point is essentially an initial view/page of a specific feature module.
For instance, if you would like to redirect user to start opening an account:
```
[[BBAESDK sharedInstance] createOpenAccountViewController];
```
You may also provide options to each ViewController to control some UI elements. For instance:
```
NSSDictionary *options = @{
// Controls the left button item in Navigation bar
BBAEFirstViewNavBarButtonItemTypeKey: @(BBAEFirstViewNavBarButtonItemDismiss)
};
[[BBAESDK sharedInstance] createOpenAccountViewControllerWithOptions: options];
```
Following is the complete list of entry points
```
// 0. Show main page
[[BBAESDK sharedInstance] createMainViewController]
[[BBAESDK sharedInstance] createMainViewControllerWithOptions: @{/*view options*/}]
// 1. Show open account page
[[BBAESDK sharedInstance] createOpenAccountViewController]
[[BBAESDK sharedInstance] createOpenAccountViewControllerWithOptions: @{/*view options*/}]
// 2. Show fund withdrawal page
[[BBAESDK sharedInstance] createWithdrawViewController]
[[BBAESDK sharedInstance] createWithdrawViewControllerWithOptions: @{/*view options*/}]
// 3. Show fund deposit page
[[BBAESDK sharedInstance] createDepositViewController]
[[BBAESDK sharedInstance] createDepositViewControllerWithOptions: @{/*view options*/}]
// 4. Show positions page
[[BBAESDK sharedInstance] createMyPositionsViewController]
[[BBAESDK sharedInstance] createMyPositionsViewControllerWithOptions: @{/*view options*/}]
// 5. Show trade history page
[[BBAESDK sharedInstance] createTradeHistoryViewController]
[[BBAESDK sharedInstance] createTradeHistoryViewControllerWithOptions: @{/*view options*/}]
// 6. Show asset details page
[[BBAESDK sharedInstance] createAssetDetailsViewController]
[[BBAESDK sharedInstance] createAssetDetailsViewControllerWithOptions: @{/*view options*/}]
// 7. Show fund transactions page
[[BBAESDK sharedInstance] createFundTransactionsViewController]
[[BBAESDK sharedInstance] createFundTransactionsViewControllerWithOptions: @{/*view options*/}]
// 8. Show documents page (eg. trade confirmations, tax documents, etc)
[[BBAESDK sharedInstance] createDocumentsViewController]
[[BBAESDK sharedInstance] createDocumentsViewControllerWithOptions: @{/*view options*/}]
// 9. Show message center page
[[BBAESDK sharedInstance] createMessageCenterViewController]
[[BBAESDK sharedInstance] createMessageCenterViewControllerWithOptions: @{/*view options*/}]
// 10. Show self-direct main page
[[BBAESDK sharedInstance] createSelfDirectViewController]
[[BBAESDK sharedInstance] createSelfDirectViewControllerWithOptions: @{/*view options*/}]
// 11. Show margin account upgrade page
[[BBAESDK sharedInstance] createMarginAccountUpgradeViewController]
[[BBAESDK sharedInstance] createMarginAccountUpgradeViewControllerWithOptions: @{/*view options*/}]
// 12. Show transfer account page
[[BBAESDK sharedInstance] createTransferAccountViewController]
[[BBAESDK sharedInstance] createTransferAccountViewControllerWithOptions: @{/*view options*/}]
// 13. Show market list page
[[BBAESDK sharedInstance] createMarketViewController]
[[BBAESDK sharedInstance] createMarketViewControllerWithOptions: @{/*view options*/}]
// 14. Show mailing address page
[[BBAESDK sharedInstance] createMailingAddressViewController]
[[BBAESDK sharedInstance] createMailingAddressViewControllerWithOptions: @{/*view options*/}]
// 15. Show personal profile page
[[BBAESDK sharedInstance] createPersonalProfileViewController]
[[BBAESDK sharedInstance] createPersonalProfileViewControllerWithOptions: @{/*view options*/}]
// 16. Show identity document page
[[BBAESDK sharedInstance] createIdentityDocumentViewController]
[[BBAESDK sharedInstance] createIdentityDocumentViewControllerWithOptions: @{/*view options*/}]
// 17. Show risk control page
[[BBAESDK sharedInstance] createRiskControlViewController]
[[BBAESDK sharedInstance] createRiskControlViewControllerWithOptions: @{/*view options*/}]
// 18. Show day trading details page
[[BBAESDK sharedInstance] createDayTradingViewController]
[[BBAESDK sharedInstance] createDayTradingViewControllerWithOptions: @{/*view options*/}]
// 19. Show GFV record page
[[BBAESDK sharedInstance] createGFVViewController]
[[BBAESDK sharedInstance] createGFVViewControllerWithOptions: @{/*view options*/}]
// 20. Show margin call list page
[[BBAESDK sharedInstance] createMarginCallListViewController]
[[BBAESDK sharedInstance] createMarginCallListViewControllerWithOptions: @{/*view options*/}]
// 21. Show "My Account" page
[[BBAESDK sharedInstance] createMyAccountViewController]
[[BBAESDK sharedInstance] createMyAccountViewControllerWithOptions: @{/*view options*/}]
```
### 4. Push notification and URL scheme
BBAE provides notification service that will help enhance user experience. BBAE will send notifications on important events such as account status change.
However, BBAE *does not* control push notification for partners.
The BBAE server will send notification data to your server, and your server will be responsible for pushing the notification to your users. Please contact the BBAE developer if you wish to receive BBAE notifications.
A BBAE notification may contain a URL scheme, which can be use to bring up a corresponding page in the BBAE SDK. This will allow you to redirect the user upon clicking a notification.
```
// Bring up a view via URL scheme
[[BBAESDK sharedInstance] openURLScheme: @"position"]
```
## Other configurations
You may customize texts and colors via BBAESDKResource.bundle
## iOS system compatibility
The BBAE SDK supports iOS 11 and above.