Android

Integration 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 versionsSupported mainstream models, Android 5.0 and above systems
System library dependencyarmeabi-v7a, arm64-v8a

Integration Steps

SDK Integration

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 below:

dependencies {
    // Device Fingerprint
    implementation 'com.trustdecision.android:mobrisk:4.3.1.10'
    // Liveness Detection
    implementation 'com.trustdecision.android:liveness:2.1.1'
 }

If you encounter compliance issues, you can exclude the collection of relevant modules during the dependency phase, as follows:

dependencies {
    // Device Fingerprint
    implementation('com.trustdecision.android:mobrisk:4.3.1.10'){
    	// 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 two ABI types: armeabi-v7a, arm64-v8a. It is recommended that the accessor party add an abiFilters configuration to select the required architecture type in the app/build.gradle file. For Example:

defaultConfig {
    ........
    ndk {
        abiFilters 'armeabi-v7a', 'arm64-v8a'
    }
}

For the specific architecture, please refer to the architecture you need to support!

Configure AndroidManifest.xml

Declare the following permissions in the AndroidManifest.xml file under the application module

<manifest>
   <!--Compulsory permissions-->
   <!--Internet connection-->
   <uses-permission android:name="android.permission.INTERNET"/>
   <!--Access network state-->
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
   <!--Access Wifi 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.ACCESS_FINE_LOCATION"/>
   <uses-permission android:name="android.permission.READ_PHONE_STATE" />
</manifest>
   <!-- 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 Permission Request: For Android 6.0 and above, dynamic permission requests are required. The code for dynamic permission requests must be placed before initializing the SDK. Example code is as follows:

//The following permissions are not mandatory. You can selectively apply for permissions based on business requirements.
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 required parameters

KeyDefinitionDescriptionSample Code
partnerCodePartner codePartner code, please contact TrustDecision to obtainbuilder.partnerCode("partner")
partnerKeyPartner keyPartner key, please contact TrustDecision to obtainbuilder.partnerKey("partnerKey")
appKeyApp keyConfigure 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")
countryCountry codeTDRisk.COUNTRY_US means North America
TDRisk.COUNTRY_FRA means Europe
TDRisk.COUNTRY_SG means Singapore
TDRisk.COUNTRY_IDNA means Indonesia
builder.country(TDRisk.COUNTRY_SG)

initWithOptions method Optional Parameter, 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): Obtain the blackbox in onEvent through the callback method callback

// SDK init option
TDRisk.Builder builder = new TDRisk.Builder()
/*************************** Mandatory ***************************/
.partnerCode("demo")        // Partner code, such as demo, please fill in your partner, get from trustDecision
.appKey("appKey")           // configure AppKey, please contact TrustDecision Operations to obtain it 		 
.partnerKey("partnerKey")   // configure partnerKey, please contact TrustDecision Operations to obtain it 
.country(TDRisk.COUNTRY_SG); // Country parameter,E.g: sg、us、fra
/*************************** Mandatory ***************************/

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

// get blackbox async
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 1-2s.
    // In the case of abnormality, it will return after the timeout (the longest 15S default).
    // Please configure your processing logic for the blackbox below
    Log.i("TDRiskDemo", "blackbox: " + blackbox);
  }
});

Usage Scenario Description
Advantages: Under normal circumstances, the network returns a non-degraded blackBox, which will reduce the amount of data uploaded by the subsequent query interface, and the data size is about 26 bytes;
Disadvantages: Not returned immediately, according to the network It usually takes about 1-2s to return;
Applicable scenario: Need to get the latest and non-degraded blackBox scenario;

Method 2: Obtain blackbox through getBlackBox() method

// SDK init option
TDRisk.Builder builder = new TDRisk.Builder()
/*************************** Mandatory ***************************/
.partnerCode("demo")        // Partner code, such as demo, please fill in your partner, get from trustDecision
.appKey("appKey")           // configure AppKey, please contact TrustDecision Operations to obtain it 		 
.partnerKey("partnerKey")   // configure partnerKey, please contact TrustDecision Operations to obtain it 
.country(TDRisk.COUNTRY_SG); // Country parameter,E.g: sg、us、fra
/*************************** Mandatory ***************************/

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

Get blackbox when your business needs it.

String blackbox = TDRisk.getBlackBox();

Usage Scenario Description
Advantages: The blackBox will be returned immediately, not affected by the network status;
Disadvantages: After the device fingerprint SDK is integrated, if the non-degraded blackBox has not been obtained before, it will return to the degraded blackBox will increase the amount of data uploaded by the subsequent query interface, and the data size is about 5000 bytes;
Applicable scenarios: Scenes where blackBox needs to be obtained immediately;

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

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

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 com.trustdecision.**{*;}
-keep class cn.tongdun.**{*;}

Liveness Detection Module

Initial configuration optional parameter list

KeyDefinitionDecriptionSample Code
livenessHttpTimeOutSDK timeout interval configuration(unit: millisecond)Default is 10 * 1000ms.builder.livenessHttpTimeOut(10000)
languageLanguage typeDefault is English
TDRisk.LANG_ES Spanish
TDRisk.LANG_EN English
builder.language(TDRisk.LANG_ES)
showReadyPageWhen starting liveness detection, a preparation page will pop upWhether to display the preparation page, default is true.builder.showReadyPage(true)
faceMissingIntervalTimeout duration when no face is detectedIn milliseconds, default is 1000ms.builder.faceMissingInterval(1000)
prepareStageTimeoutTimeout duration for the preparation stageIn seconds. Default is 0 second, which means never timeout.builder.prepareStageTimeout(0)
actionStageTimeoutTimeout duration for the action stageIn seconds. Default is 8 seconds.builder.actionStageTimeout(8)

Start liveness detection

TDRisk.showLiveness to start liveness detection

TDShowLivenessCallback is the callback interface for the retrieval of liveness detection results and the sample codes as follows:

...
public void loginClick() {
  TDRisk.showLiveness(new TDRiskLivenessCallback() {
      @Override
      public void onSuccess(String result) {
        Log.d("TD","Verification succeeded" + result);
      }

      @Override
      public void onError(String errorCode, String errorMsg) {
        Log.d("TD","Verification failed!, Error code:"+ errorCode + ", Error message:" + errorMsg);
      }
  });
}

Result Response Parameters

ParameterTypeDescriptionNotes
resultStringLiveness detection resultsEnumeration values: success, fail
success: passed the liveness detection;
fail: failed the liveness detection
imageStringLiveness detection face picturesThe best face picture captured during the liveness detection process, in base64 format
scoreDoubleLiveness detection confidence scoreReserved field. Currently, only the results of the result field are needed to determine whether the living body test has been passed.

Result Sample

{
  "code": "00000000",
  "message": "success",
  "result": success,
  "sequence_id": "1679299854228726325924",
  "image": "\/9j\/4AAQSkZJRgABAQAAAQABAAD\/2wBDAAMCA",
  "score": 0.98958
}

API Code

CodeMessageCharged
0000000successYES
20700No face detectedNO
20702Person change detectedNO
20703Detection timeoutNO
20705Screen lock or background exit during detectionNO
20710No camera permissionNO
20711User actively cancels detection on the preparation pageNO
20712User actively cancels detection on the detection pageNO
12202Identified as a blink attackYES
12203Identified as a mouth movement attackYES
12204Identified as a partial face attackYES
12205Identified as a video replay attackYES
12206Identified as a black and white imageYES
12207Identified as a paper-based attackYES
12208Identified as a frame (including paper or phone frame)YES
12209Identified as a moire pattern attackYES
12210Identified as a face superiority attackYES
12211Identified as a paper-based attack (optical flow)YES
12212Identified as a mask attackYES
12213Identified as an ID card attackYES
12214Identified as a 3D mask attackYES
12215Identified as a synthetic image attackYES
12216Identified as a black-market software attackYES
12217Identified as a T-type mask attackYES
12218Identified as a blurry imageYES
12219Suspected deepfake image attackYES
12220Suspected high-resolution screen attackYES
12222Injection attackYES
12250Verification errorYES
11350Internal errorNO