Android

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

ItemsDescription
Supported System VersionsSupport mainstream models, Android 4.4 and above systems
System library dependencyarmeabi-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.3.1.3'
    // captcha
    implementation 'com.trustdecision.android:captcha:2.2.1'
 }

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.3.1.3'){
    	// 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_COARSE_LOCATION"/>
   <uses-permission android:name="android.permission.READ_PHONE_STATE" />

</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_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 ***************************/

// init Mob-Risk SDK
if(User agrees with the privacy agreement){
   TDRisk.initWithOptions(getApplicationContext(), builder);
}

// fingerprint init
TDRisk.getBlackBox(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);
  }
});


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

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 KeyDefinitionDescriptionScenarioSample Code
languagelanguage typeOptions: 1-Simplified Chinese, 2-Traditional Chinese, 3-English, 4-Japanese, 5-Korean, 6-Malay, 7-Thai, 8-Indonesian, 9-Russian Default: 1-Simplified ChineseYou can set the language type according to your needs, Chinese mainland support 1-5, overseas support 1-9builder.language(1)
tapToCloseClick on the blank space to close the Captcha windowOptional: true, false Default: falseAfter opening, click on the blank area of the interface to close the Captcha window, which is more convenient to close the pop-up windowbuilder.tapToClose(true)
needSeqidWhether to carry the seqid in the failure callback messageOptional: true, false Default: trueWhen 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 failurebuilder.needSeqId(true)
hideLoadHudWhether to skip the loading animationOptions: true, false Default: falseWhen enabled, the loading animation will not be displayed when the Captcha window pops up, shortening the verification timebuilder.hideLoadHud(true)
hideWebCloseButtonWhether to hide the close button of the webviewOptions: true, false Default: falseScenarios that need to be forced to complete the Captchabuilder.hideWebCloseButton(true)
openLogWhether to open the logOptions: true, false Default: falseWhen enabled, the console will output more log information during debugging, which is convenient for troubleshootingbuilder.openLog(true)
skipCaptchaWhether to skip the TrustDecision Captcha verificationOptional: true, false Default: falseWhen 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 verificationbuilder.skipCaptcha(true)
mfaIdMFA IDOptional: string Default:nullIf 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 CodeError MessageProcessing Method
1001The Captcha window is closedAfter the Captcha window popup, the user manually cancels the Captcha,no processing is required
2001The request parameter is abnormal, please check the parameterPlease check the appName and partnerCode parameters
2100The request parameter is abnormal, please check the parameterPlease check the passed parameter
2101The request parameter is abnormal, please check the parameterThere is an error in the request process, please contact the operator
2102The request parameter is abnormal, please check the parameterThe parameter is missing, please check the parameter
2111Authentication page network errorTry again later, or please contact the operator
2112Verification page operation is too frequentTry again later
2113Unknown errorUnknown error, please contact the operator
2114Closed the Captcha windowClicked the Captcha close button, no need to process
2115Authentication page network errorFailed to load network resources
2116Authentication page network errorFailed to load network resources
2202Verification succeededThe verification result is successful and no processing is required
2301Did not purchase this servicePlease contact the operator
2302Traffic has been disabledPlease contact the operator
2303Insufficient trafficPlease contact the operator
2304Service has expiredPlease contact the operator
2305Daily traffic has been cappedPlease contact the operator
2600The system is busy, please try again laterThe system is busy, please try again later
2601Authentication failed, try again laterAuthentication failed, please try again later
2602Authentication failed, try again laterAuthentication failed, please try again later
2603Authentication failed, try again laterAuthentication failed, please try again later
2604Authentication failed, try again laterRefresh frequently, please try again later
2605Verification failed, try again laterFailed to obtain Captcha information
2702Authentication failed, try again laterParsing error, please try again later
3001SSL certificate verification failedPlease close the network proxy tool
3002Error loading verification pageRefresh the network and try again
3003Authentication page load timed outCheck network and try again
4000Validation logic skippingDevelopers manually handle validation skipping logic
9000The device fingerprint is not mountedTo integrate the Captcha, you need to integrate the device fingerprint first
9001No networkPlease check network connection
9002Request timed outCheck network, try again later
9003Return result is abnormalServer error, return result is abnormal, contact technical support
9004Global loading timed outCheck 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.