# Getting started with the BBAE Android SDK
To get you started more quickly, we've provided a demo project that contains all the necessary resources to start using the BBAE SDK.
## Import and install dependencies
### 1. Import the BBAE SDK Android Archieve (AAR) files
The AAR files are located under `app/libs` in the demo project.
You may import the AAR files by adding the following configuration in your `build.gradle` file:
```
repositories {
flatDir {
dirs 'libs'
}
}
```
```
implementation name:'bbaesdk-pro-release',ext:'aar'
implementation name:'hybrid-1.0.18',ext:'aar'
implementation name:'liberation-1.0.13',ext:'aar'
implementation name:'login-pro-1.0.0',ext:'aar'
implementation name:'logger-1.0.9',ext:'aar'
implementation name:'market-pro-1.0.1',ext:'aar'
implementation name:'MPChartLib-1.0.12',ext:'aar'
implementation name:'open-pro-1.0.0',ext:'aar'
implementation name:'securepreferences-1.0.11',ext:'aar'
implementation name:'smart-pro-1.0.0',ext:'aar'
implementation name:'trade-pro-1.0.0',ext:'aar'
implementation name:'transfer-pro-1.0.0',ext:'aar'
implementation name:'useraccount-pro-1.0.2',ext:'aar'
implementation name:'weight-1.0.14',ext:'aar'
implementation name:'commonlib-pro-1.0.6',ext:'aar'
implementation name:'hyplugin-1.0.4',ext:'aar'
implementation name:'security-1.0.0',ext:'aar'
```
### 2. Import external dependencies required by the BBAE SDK
Note: if your project also uses the same dependencies, try to use a matching version with the BBAE SDK. If there is any problem regarding version conflicts, please contact BBAE developers.
```
implementation "com.google.code.gson:gson:2.8.5"
implementation "com.jakewharton:butterknife:10.2.1"
implementation "com.jakewharton.rxbinding3:rxbinding:3.1.0"
implementation "io.reactivex.rxjava2:rxandroid:2.1.1"
implementation "io.reactivex.rxjava2:rxjava:2.2.17"
implementation "com.squareup.retrofit2:retrofit:2.5.0"
implementation "com.squareup.retrofit2:converter-gson:2.5.0"
implementation "com.squareup.retrofit2:adapter-rxjava2:2.5.0"
implementation "com.squareup.okhttp3:logging-interceptor:3.12.0"
implementation "com.github.bumptech.glide:glide:4.7.1"
implementation "me.grantland:autofittextview:0.2.1"
implementation 'com.contrarywind:Android-PickerView:3.2.5'
implementation "com.belerweb:pinyin4j:2.5.0"
implementation 'com.google.zxing:core:3.3.3'
implementation 'androidx.multidex:multidex:2.0.0'
implementation 'androidx.legacy:legacy-support-v4:1.0.0'
implementation 'androidx.viewpager:viewpager:1.0.0'
implementation 'androidx.appcompat:appcompat:1.2.0'
implementation 'androidx.recyclerview:recyclerview:1.1.0'
implementation 'androidx.swiperefreshlayout:swiperefreshlayout:1.1.0'
implementation 'com.google.android.material:material:1.2.1'
implementation 'androidx.constraintlayout:constraintlayout:2.0.4'
implementation "androidx.gridlayout:gridlayout:1.0.0"
implementation "ru.noties.markwon:core:3.1.0"
implementation 'org.jsoup:jsoup:1.10.2'
implementation 'com.google.guava:guava:30.1.1-android'
implementation 'androidx.core:core:1.6.0-alpha01'
implementation "com.google.protobuf:protobuf-java:3.19.1"
implementation "com.google.protobuf:protobuf-java-util:3.19.1"
implementation "com.google.protobuf:protoc:3.19.1"
```
You need to use the repository to download the SDK package. include it as follows:
```
allprojects {
repositories {
google()
jcenter()
maven { url 'https://jitpack.io' }
}
}
```
### 3. Add configure to `gradle.properties`
```
android.enableJetifier=true
```
### 4. Add permissions to Android manifest
Open `AndroidManifest.xml` and add the following permissions:
```
// For accessing the BBAE API server
<uses-permission android:name="android.permission.INTERNET" />
// For checking whether device is connected to the internet
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
// For checking WIFI connection state
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
// For accessing stored application data and images
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
// For storing application data
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
// For accessing camera, which is used during account application process for uploading identity document
<uses-permission android:name="android.permission.CAMERA" />
```
### 5. Add tools:replace="android:theme" to Android manifest
Suggestion: add 'tools:replace="android:theme"' to <application> element at `AndroidManifest.xml`
```
tools:replace="android:theme"
```
### 6. Add provider to Android manifest
Open `AndroidManifest.xml` and add the following provider. Replace `PackageName` with the Java-style package name of your Android app.
```
<provider
android:name="androidx.core.content.FileProvider"
android:authorities="${PackageName}.internalfileprovider"
android:exported="false"
android:grantUriPermissions="true">
<meta-data
android:name="android.support.FILE_PROVIDER_PATHS"
android:resource="@xml/bbae_provider_paths" />
</provider>
```
## 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 the `Application.onCreate()` method.
Example:
```
/**
* Initialize the BBAE SDK and register application key
*/
BBAE.getIns().init(
new BBAEConfiguration.Builder(this)
.registerAppKey("fakeapplicationkey")
.build());
/**
* Configuration options:
* 1. (debug mode only) log level
* 2. (debug mode only) configure SDK API URLs
* 3. Set app theme
*/
BBAE.getIns().setLoadConfig(
new BBAELoadConfig.Builder()
.setLogLevel(BBAELoadConfig.LOG_LEVEL_NO)
.setDebugBaseUrl(SDK_BASE_URL)
.setDefaultTheme(BBAELoadConfig.THEME_WHITE)
.build());
/**
* Set sessionId, which is used to identify a user
*/
BBAE.getIns().setSessionId("sessionIdString");
```
#### 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.
```
/**
* onSessionExpired() 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().
*/
BBAE.getIns().setSessionIdExpiredCallBack(new BBAE.SessionIdExpiredCallBack() {
@Override
public String onSessionExpired(BBAEErrorCode errorCode) {
// Should return a currently valid session
return "newSessionIdString";
}
});
/**
* 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.
*/
BBAE.getIns().addSessionErrorCallBack(new BBAE.SessionErrorCallBack() {
@Override
public void onSessionError(Exception e) {
// The SDK is in a frozen state since session authentication failed too many times.
// Call setSessionId() again to kickstart the authentication process again.
}
});
/**
* Set sessionId and trigger user authentication process
*/
BBAE.getIns().setSessionId("sessionIdString");
/**
* Log out the current session and close existing activities
*/
BBAE.getIns().logOut();
```
#### 2.2. Setting customer service
```
/**
* Set customer service
*/
BBAE.getIns().setCustomerService(new CustomerService() {
@Override
public List<PhoneModel> getPhoneList() {
return null;
}
@Override
public boolean hasOnlineCustomerService() {
return false;
}
@Override
public void startOnlineCustomerService(Activity activity) {
}
@Override
public int getUnreadMsgCount() {
return 0;
}
@Override
public String getUSACustomer() {
return null;
}
});
```
#### 2.3. Setting share module
```
List<ShareType> shareTypeList=new ArrayList<ShareType>();
shareTypeList.add(new ShareType() {
@Override
public String getShareId() {
// Return the share channel id , not important but should be unique
return "";
}
@Override
public void onShare(ShareContent shareModel) {
// This function will be fired when user clicks the share channel.
}
@Override
public Drawable getShareDrawable(Context context) {
// Return the share channel image for displaying
return null;
}
@Override
public String getShareName(Context context) {
// Return the share channel name for displaying
return null;
}
});
/**
* Set share type
*/
BBAE.getIns().setDefaultShareType(shareTypeList);
```
### 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:
```
BBAE.getIns().startOpenAccount()
```
The BBAE SDK also provides some views as Fragments. Some modules are not available as Fragments because they consist more complex UI transitions that depend on business logic.
Following is the complete list of entry points
```
// 1. Show open account page
BBAE.getIns().startOpenAccount();
// 2 .Show fund withdrawal page
BBAE.getIns().startWithdraw();
// 3 .Show fund deposit page
BBAE.getIns().startDeposit();
// 4 .Show positions page
BBAE.getIns().startPosition();
BBAE.getIns().getPositionFragment();
// 5 .Show trade history page
BBAE.getIns().startTradeHistory();
BBAE.getIns().getTradeHistoryFragment();
// 6 .Show asset details page
BBAE.getIns().startAssetDetails();
BBAE.getIns().getAssetDetailsFragment();
// 7. Show fund transactions page
BBAE.getIns().startFundTransactions();
BBAE.getIns().getFundTransactionsFragment();
// 8. Show documents page (eg. trade confirmations, tax documents, etc)
BBAE.getIns().startDocument();
BBAE.getIns().getDocumentFragment();
// 9. Show message center page
BBAE.getIns().startMessageCenter();
BBAE.getIns().getMessageCenterFragment();
// 10. Show self-direct main page
BBAE.getIns().startSelfDirect();
BBAE.getIns().getSelfDirectFragment();
// 11. Show margin account upgrade page
BBAE.getIns().startMarginAccountUpgrade();
// 12. Show transfer account page
BBAE.getIns().startTransferAccount();
// 13. Show mailing address page
BBAE.getIns().startMailingAddress();
// 14. Show personal profile page
BBAE.getIns().startPersonalProfile();
// 15. Show identity document page
BBAE.getIns().startIdentityDocument();
// 16. Show risk control page
BBAE.getIns().startRiskControl();
BBAE.getIns().getRiskControlFragment();
// 17. Show day trading details page
BBAE.getIns().startDayTrading();
BBAE.getIns().getDayTradeFragment();
// 18. Show GFV record page
BBAE.getIns().startGFV();
BBAE.getIns().getGFVFragment();
// 19. Show margin call list page
BBAE.getIns().startMarginCallList();
BBAE.getIns().getMarginCallListFragment();
// 20. Show "My Account" page
BBAE.getIns().startMyAccount();
BBAE.getIns().getAccountFragment();
```
#### 3.1. More on using Fragments
When using Fragments, you need to set the parent of the activity theme as `BBAEStyle` or copy items in `BBAEStyle` to the activity theme.
```
<style name="StyleDemo" parent="BBAEStyle">
<item name="android:windowNoTitle">true</item>
</style>
```
### 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.
```
// Start an Activity via URL scheme
BBAE.getIns().openURLScheme('position');
```
## Other configurations
### Using the SDK with ProGuard
The demo project provides `app/proguard-rules.pro`, you may add that to your own project.
### Changing text content within the BBAE SDK pages
You may override a piece of text by adding an entry to `res/values/strings.xml` in your project, and use the same key name.
- For text in Simplified Chinese, add to `res/values/string.xml`.
- For text in English, add to `res/values-en/string.xml`.
Please ask the BBAE developers for the name of the specific text you wish to change.
### Changing color theme
The BBAE SDK pages are designed with a predefined set of colors, named from `C1` to `CXX`. This means that you may customize the colors by overriding the C color codes.
To override color codes, add to `res/values/color.xml`:
```
<color name="C1">#8E9BFF</color>
<color name="C19">#0e1820</color>
```
If you wish to customize the color theme, feel free to contact BBAE developers, and we will let you know which color codes to modify.
## Android system compatibility
The BBAE SDK supports Android 4.2 and above.