# Integrated Requirement
# Compliance Explanation
Please note that when integrating SDK products provided by the TrustDecision in the APP of your company:
1.1 According to the user's information protection regulations, before your users start the App for the first time and start collecting information, your company should fully inform the user of the purpose, method, and scope of collecting, using, and sharing the user's personal information with a third party through an interactive interface or design (such as a pop-up window of the privacy policy), and obtain the express consent of the end user.
1.2 To provide business security and risk control services to your company, the TrustDecision SDK will collect, process, and use the identification information（IMEI/IDFA）, AndroidID, IMSI, MEID, MAC address, SIM card serial number, device type, device model, system type, geographical location, login IP address, application list, running process, sensor information(light sensor, gravity sensor, magnetic field sensor, acceleration sensor, gyroscope sensor) and other device information of the user's device. To ensure compliance with your use of related services, the aforementioned privacy policy should cover the authorization of TrustDecision SDK to provide services and collect, process, and use relevant information. The following terms are for your reference. The specific expression can be determined by your company according to the overall framework and content of your privacy agreement:
| TrustDecision SDK: For business security and risk control, our company uses the TrustDecision SDK. The SDK needs to obtain the information of your devices, such as （IMEI/IDFA）, AndroidID, IMSI, MAC address, SIM card serial number, device type, device model, system type, geographic location, login IP address, application list, running process, sensor information(light sensor, gravity sensor, magnetic field sensor, acceleration sensor, gyroscope sensor) and other related device information, for fraud risk identification. |
Privacy Protocol: https://www.trustdecision.com/legal/privacy-policy
# Environment
| Items | Description |
|---|---|
| Supported System Versions | Support mainstream models, Android 4.4 and above systems |
| System library dependency | armeabi-v7a, arm64-v8a, x86 |
# Integrate Steps
# Integrate SDK
Note: For customers who have integrated SDK in project libs, please delete the old version SDK first when upgrading the new version SDK, and if there are so libraries integrated with the old version, they also need to be deleted at the same time.
SDK access sample code : https://github.com/trustdecision/mobrisk-android-sample
# add warehouse
First, please add the maven library configuration to build.gradle in the project root directory
allprojects {
repositories {
...
mavenCentral()
}
}
If your Gradle version is 7 or higher, add these lines to your settings.gradle
repositories {
...
mavenCentral()
}
# add dependencies
Add dependencies to app/build.gradle of the project, as shown in the figure:
dependencies {
// fingerprint
implementation 'com.trustdecision.android:mobrisk:4.2.4.2'
// captcha
implementation 'com.trustdecision.android:captcha:2.2.0'
}
If compliance issues are encountered, we can also exclude the collection of related modules during the dependency phase, as follows:
dependencies {
// fingerprint
implementation('com.trustdecision.android:mobrisk:4.2.4.2'){
// after removal, sdk does not get the list of installation packages
exclude group: 'com.trustdecision.android', module: 'packagelist'
// after removal, sdk will not collect READ_PHONE_STATE related information
exclude group: 'com.trustdecision.android', module: 'readphone'
}
}
# ABI type
The SDK currently supports three ABI types: armeabi-v7a, arm64-v8a, and x86. It is recommended that the accessor party add an abiFilters configuration to select the required architecture type in the app/build.gradle file. Example
defaultConfig {
........
ndk {
abiFilters 'armeabi-v7a', 'arm64-v8a'
}
}
For the specific architecture, please refer to the architecture you need to support!
# Configuration AndroidManifest.xml
Declare the following permissions in the AndroidManifest.xml file under the application module
<manifest>
<!--Compulsory permissions-->
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
<!--The following permissions are optional. If this part of the authority is not declared, the acquisition of some device information will be abandoned, which will have a certain effect on data analysis and the accuracy of the fingerprint of the device fingerprint-->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<!-- This permission is required for Android 11 and above to obtain the installation package list. Collecting the installation package list involves risk and compliance. Whether this permission is required is optional for the business party
select -->
<uses-permission android:name="android.permission.QUERY_ALL_PACKAGES"
tools:ignore="QueryAllPackagesPermission" />
</manifest>
Dynamic application permissions: Android 6.0 or above requires dynamic application permissions. Dynamic application permissions code must be placed before the initial SDK. The code example is as follows:
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
requestPermissions(new String[]{
Manifest.permission.ACCESS_FINE_LOCATION,
Manifest.permission.ACCESS_COARSE_LOCATION,
Manifest.permission.READ_PHONE_STATE
}, 100);
}
# How to use the SDK
Precautions
Ensure that the SDK is initialized after the user agrees to the privacy agreement, so as to avoid the occurrence of SDK initialization and collection without the user's consent to the privacy agreement, which may cause compliance risks.
SDK configuration
The Trustdecision SDK uses the TDRisk.Builder method to configure and set the SDK initial parameters, and provides the setting results as initialization parameters to the SDK initialization method initWithOptions().
TDRisk.Builder must be configured with parameters as follows
| Key | Definition | Description | Sample code |
|---|---|---|---|
| partner | Partner code | Partner, please contact TrustDecision to obtain | builder.partnerCode("partner") |
| appKey | App key | Configure AppKey with TrustDecision, please contact TrustDecision Operations to get it The appkey creation requires the user to provide the application package name and a lowercase sha256 signature. ⚠️ Do not use the same value for package name signatures of different applications | builder.appKey("appKey") |
| appName | App name | AppName, please contact TrustDecision to obtain | builder.appName("appName") |
| country | Country code | TDRisk.COUNTRY_US means North America TDRisk.COUNTRY_FRA means Europe TDRisk.COUNTRY_SG means Singapore TDRisk.COUNTRY_CN means China | builder.country(TDRisk.COUNTRY_CN) |
We also provide optional parameter configuration, see the attached table for details (list of optional parameters for initial configuration)
SDK Sample Code When the application starts, for example, the following method is called in the application class of the Application (Android 6.0 and above to ensure that you have applied).
# Method 1 (recommended method): Obtain blackbox through getBlackBox() method
// SDK init option
TDRisk.Builder builder = new TDRisk.Builder()
/*************************** Must ***************************/
.partnerCode("demo") // Partner code,such as demo,please fill in your partner, get from trustDecision
.appName("appName") // app Name,such as appName,please fill in your app Name
.appKey("appKey") // configure AppKey, please contact TrustDecision Operations to obtain it
.country(TDRisk.COUNTRY_CN); // Country parameter，E.g: cn、sg、us、fra
/*************************** Must ***************************/
// init Mob-Risk SDK
if(User agrees with the privacy agreement){
TDRisk.initWithOptions(getApplicationContext(), builder);
}
⚠️Precautions: You must ensure that getBlackBox is called after initWithOptions.
Get blackbox when your business needs it
String blackbox = TDRisk.getBlackBox();
# Method 2: Obtain the blackbox in onEvent through the callback method callback
// SDK init option
TDRisk.Builder builder = new TDRisk.Builder()
/*************************** Must ***************************/
.partnerCode("demo") // Partner code, such as demo, please fill in your partner, get from trustDecision
.appName("appName") // app Name,such as appName, please fill in your app Name
.appKey("appKey") // configure AppKey, please contact TrustDecision Operations to obtain it
.country(TDRisk.COUNTRY_CN) // Country parameter，E.g: cn、sg、us、fra
/*************************** Must ***************************/
// fingerprint init
.callback(new TDRiskCallback() {
@Override
public void onEvent(String blackbox) {
// The callback here is in the thread thread
// In the case of normal, the results will return within 200-300ms.
// In the case of abnormality, it will return after the timeout (the longest 15S default).
Log.i("TDRiskDemo", "blackbox: " + blackbox);
}
});
// init Mob-Risk SDK
if(User agrees with the privacy agreement){
TDRisk.initWithOptions(getApplicationContext(), builder);
}
# The difference between the two ways
- The first method is to obtain the blackbox synchronously. The advantage is that the blackbox can be guaranteed to be obtained (in some cases, it is a downgraded blackbox). If you call getBlackBox on the main thread, you need to pay attention to the time-consuming problem.
- The second method is to obtain blackbox asynchronously. The advantage is that the process will not be blocked and there is no time-consuming problem. The disadvantage is that the initialization has not been completed when calling the getBlackBox method, and the blackbox cannot be obtained. It should be noted that the callback result is not in the main thread, and it is forbidden to operate the UI in the callback.
After the SDK reports the data successfully, under normal circumstances, the length of the result returned by getBlackbox() is a 26-bit string. For example: rWPGX1678775227I9NCwcuVJCb
Under abnormal circumstances, the length is about 5000 characters. For details, please check Overview (opens new window)
After executing initWithOptions initialization successfully, the following log will be printed in logcat:
TD_JAVA: tongdun sdk load success
TD_JAVA: tongdun sdk init success
# Get SDK Version
Sample Code
// Get SDK Version
TDRisk.getSDKVersion()
# Other Instructions
Confuse packaging. If the developer needs to use Proguard for confusion, please add the following code to the proguard configuration file:
#TrustDecision
-keep class cn.tongdun.**{*;}
# Captcha Module
# Initial configuration optional parameter list
| Configuration Key | Definition | Description | Scenario | Sample Code |
|---|---|---|---|---|
| language | language type | Options: 1-Simplified Chinese, 2-Traditional Chinese, 3-English, 4-Japanese, 5-Korean, 6-Malay, 7-Thai, 8-Indonesian, 9-Russian Default: 1-Simplified Chinese | You can set the language type according to your needs, Chinese mainland support 1-5, overseas support 1-9 | builder.language(1) |
| tapToClose | Click on the blank space to close the Captcha window | Optional: true, false Default: false | After opening, click on the blank area of the interface to close the Captcha window, which is more convenient to close the pop-up window | builder.tapToClose(true) |
| needSeqid | Whether to carry the seqid in the failure callback message | Optional: true, false Default: true | When enabled, the seqid serial number will be carried in the failure message, and the seqid will be provided to TrustDecision for easy troubleshooting Reason for failure | builder.needSeqId(true) |
| hideLoadHud | Whether to skip the loading animation | Options: true, false Default: false | When enabled, the loading animation will not be displayed when the Captcha window pops up, shortening the verification time | builder.hideLoadHud(true) |
| hideWebCloseButton | Whether to hide the close button of the webview | Options: true, false Default: false | Scenarios that need to be forced to complete the Captcha | builder.hideWebCloseButton(true) |
| openLog | Whether to open the log | Options: true, false Default: false | When enabled, the console will output more log information during debugging, which is convenient for troubleshooting | builder.openLog(true) |
| skipCaptcha | Whether to skip the TrustDecision Captcha verification | Optional: true, false Default: false | When enabled, the Captcha will not be verified, and a 4000 error code will be returned at the same time, which is used for dynamic settings Whether to use TrustDecision Captcha SDK verification | builder.skipCaptcha(true) |
| mfaId | MFA ID | Optional: string Default:null | If you have connected to the MFA product (the description can be ignored if the MFA is not connected), please set the mfaId which is obtained from the MFA process to the configuration parameter. | builder.mfaId("mfaId") |
# Popup Captcha Window
showCaptcha method
The showCaptcha method is used to display the Captcha window, and its interface is defined as follows
TDRisk.showCaptcha(activity, new TDCaptchaCallBack(){
// The verification code is loaded and prepared to pop up the verification code
public void Ready() {}
// This interface is called only when the verification code is successfully verified or the background system considers the device to be trusted
// return a token of type String
public void Success(String token) {}
// All the error information appearing during the verification process will adjust this interface
public void Failed(int errorCode, String errorMsg) {}
}
The verification code showcaptcha operation, please be sure to put it on the main thread for execution
Example Code
...
public void loginClick() {
TDRisk.showCaptcha(activity, new TDRiskCaptchaCallback() {
@Override
public void onReady() {
Log.d("TD","Captcha window popup is successful, waiting to be verified!!!");
}
@Override
public void onSuccess(String token) {
Log.d("TD","Obtain TrustDecision Captcha successfully!!!,validateToken:" + token);
}
@Override
public void onFailed(int errorCode, String errorMsg) {
Log.d("TD","TrustDecision Captcha failed!!!, errorCode:"+ errorCode + ", errorMsg:" + errorMsg);
}
});
}
# Error Code
The error code of the captcha function module will be output through TDRisk.showCaptcha method
| Error Code | Error Message | Processing Method |
|---|---|---|
| 1001 | The Captcha window is closed | After the Captcha window popup, the user manually cancels the Captcha,no processing is required |
| 2001 | The request parameter is abnormal, please check the parameter | Please check the appName and partnerCode parameters |
| 2100 | The request parameter is abnormal, please check the parameter | Please check the passed parameter |
| 2101 | The request parameter is abnormal, please check the parameter | There is an error in the request process, please contact the operator |
| 2102 | The request parameter is abnormal, please check the parameter | The parameter is missing, please check the parameter |
| 2111 | Authentication page network error | Try again later, or please contact the operator |
| 2112 | Verification page operation is too frequent | Try again later |
| 2113 | Unknown error | Unknown error, please contact the operator |
| 2114 | Closed the Captcha window | Clicked the Captcha close button, no need to process |
| 2115 | Authentication page network error | Failed to load network resources |
| 2116 | Authentication page network error | Failed to load network resources |
| 2202 | Verification succeeded | The verification result is successful and no processing is required |
| 2301 | Did not purchase this service | Please contact the operator |
| 2302 | Traffic has been disabled | Please contact the operator |
| 2303 | Insufficient traffic | Please contact the operator |
| 2304 | Service has expired | Please contact the operator |
| 2305 | Daily traffic has been capped | Please contact the operator |
| 2600 | The system is busy, please try again later | The system is busy, please try again later |
| 2601 | Authentication failed, try again later | Authentication failed, please try again later |
| 2602 | Authentication failed, try again later | Authentication failed, please try again later |
| 2603 | Authentication failed, try again later | Authentication failed, please try again later |
| 2604 | Authentication failed, try again later | Refresh frequently, please try again later |
| 2605 | Verification failed, try again later | Failed to obtain Captcha information |
| 2702 | Authentication failed, try again later | Parsing error, please try again later |
| 3001 | SSL certificate verification failed | Please close the network proxy tool |
| 3002 | Error loading verification page | Refresh the network and try again |
| 3003 | Authentication page load timed out | Check network and try again |
| 4000 | Validation logic skipping | Developers manually handle validation skipping logic |
| 9000 | The device fingerprint is not mounted | To integrate the Captcha, you need to integrate the device fingerprint first |
| 9001 | No network | Please check network connection |
| 9002 | Request timed out | Check network, try again later |
| 9003 | Return result is abnormal | Server error, return result is abnormal, contact technical support |
| 9004 | Global loading timed out | Check network, try again later |
# FAQ
Q1: When using an agent, the user loads the verification code abnormality
QA: SDK is not allowed to capture the bag inside. When an error appears in the certificate, the verification code cannot be loaded.