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

Integration Steps

There are 3 steps to integrate Liveness Detection SDK:

  1. Use the "Retrieve license API" to get a license within the effective timeframe.
  2. Integrate the SDK for both Android and iOS platforms, initializing liveness detection process with the license generated in Step 1.
  3. Use the "Retrieve result API" with the "liveness_id" generated in Step 2 to obtain a selfie if the liveness detection is successful, or receive detailed results in case of failure.

1. Retrive license API

Base URL

API

URLRequest MethodsContent TypeOutput FormatCharacter Set
api-base-url?partner_code=xxx&partner_key=xxxPOSTapplication/jsonJSONUTF-8

Authentication

ParameterTypeDescriptionRequired/OptionalNotes
partner_codeStringPartner CodeRequiredAssigned by TD
partner_keyStringPartner KeyRequiredAssigned by TD

Request

ParameterTypeDescriptionRequired/OptionalNotes
session_durationIntegerDuration of the license's effective timeframeOptionalThe default duration is 600 seconds, with a maximum of 86,400 seconds. The unit is seconds.

Response Parameters

ParameterTypeDescriptionNotes
codeIntegerAPI status codePlease refer to below API Code list
messageStringStatus InformationDetailed reasons will be provided about API status
sequence_idStringUnique response codeA unique ID used to track each request
licenseStringLiveness detection initialization licenseThe license is used to initiate the liveness detection process in SDK subsequently.
expiry_timestampIntegerLicense expiration timestampThe timestamp when the license expires, e.g., 1715667188.

Response Example

  • Request

    {
       "session_duration": 600  //optional
    }
    
  • Success

{
    "code": 200,
    "message": "success",
    "sequence_id": "17119500882*****29",
    "license": "a41701e49******3",
    "expiry_timestamp": 1715667188
}
  • Failed
{
    "code": 11350,
    "sequence_id": "69b57131b6fb********61ccba118b60",
    "message": "Internal error"
}

2. SDK Integration methods

Environment

ItemsDescription
Supported system versionsSupported mainstream models, Android 5.0 and above systems
System library dependencyarmeabi-v7a, arm64-v8a

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.5.2'
    // Liveness Detection
    implementation 'com.trustdecision.android:liveness:2.3.2'
 }

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.5.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'
				// after removal, sdk will not collect location information
        exclude group: 'com.trustdecision.android', module: 'location'
				// after removal, sdk will not collect sensor information
        exclude group: 'com.trustdecision.android', module: 'sensor'
				// after removal, sdk will not collect wifi information
        exclude group: 'com.trustdecision.android', module: 'wifiinfo'
    }
 }

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!

AndroidManifest.xml

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

XML

<manifest>
   <!-- required -->
   <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"/>
  <!-- Outside the Chinese Mainland -->
  <uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

   <!--optional, If not declared, some device information will be abandoned -->
   <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" />
   <!-- required for Android 11 and above to obtain the installed packages -->
   <uses-permission android:name="android.permission.QUERY_ALL_PACKAGES"
        tools:ignore="QueryAllPackagesPermission" />
</manifest>

Permissions

NameDescription
INTERNET(required)Allows the app to access the network connection and send requests to communicate with the server.
ACCESS_NETWORK_STATE(required)Collect network connection status information.
ACCESS_WIFI_STATE(required)Collect the current WiFi access status and WLAN hotspot information.
AD_ID(required)Collect the Google advertising ID, required outside the Chinese Mainland.
ACCESS_COARSE_LOCATIONGet location information, with an accuracy of approximately 30 to 1500 meters.
ACCESS_FINE_LOCATIONGet location information, with positioning accuracy within 10 meters.
READ_PHONE_STATECollect information on SIM card
QUERY_ALL_PACKAGESCollect installed package

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")
appKeyApp keyApplication identification, please refer tohow to get appKeybuilder.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)

Best Practices

  1. Call initialization in the onCreate method of the application, and obtain blackBox asynchronously
// onCreate of APPlication
TDRisk.Builder builder = new TDRisk.Builder()
/*************************** required  ***************************/
.partnerCode("demo")        // get from our customer platform
.appKey("appKey")           // get from our customer platform		 
.country(TDRisk.COUNTRY_SG);

if(agrees to the privacy){
  TDRisk.initWithOptions(getApplicationContext(), builder);
  TDRisk.getBlackBox(new TDRiskCallback() {
  	@Override
  	public void onEvent(String blackbox) {
    	// here is in a new thread
    	Log.i("TD", "init & get success");
  }
});
}
  1. Obtain blackBox in actual business scenarios
public void register() {
  ...
  String blackBox = TDRisk.getBlackBox();
  ...
}

Status Check

  1. Log will be printed in logcat while initialization successfully
TD_JAVA: Tongdun sdk load success
TD_JAVA: Tongdun sdk init success
  1. getBlackBox() will return a 26-bit string while initialization successfully: rGPGX1678775227I9NCwcuVJCb

  2. getBlackBox() will return a string of around 5000 bits while initialization Failed, please refer to overview-definition

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 typeThe default is the phone system language
Options:
en English
zh-Hans Simplified Chinese
zh-Hant Traditional Chinese
es Spanish
id Indonesian
ar Arabic
fil Filipino
ko Korean
pt Portuguese
ru Russian
th Thai
tr Turkish
vi Vietnamese
builder.language("en")
playAudioWhether to play audioThe default is true, no audio will be playedbuilder.playAudio(true)
livenessDetectionThresholdLiveness detection thresholddefault medium
Options
"medium","low","high"
builder.livenessDetectionThreshold("low")
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

License field should be filled with the license obtained in Step 1 by requesting the TD backend API.

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

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

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

Result Response Parameters

You can retrieve the image directly using the methods provided by the SDK, but it is strongly recommended to store the liveness_id on your server first, and the server should then call the "Retrieve Result API" to obtain the actual result and selfie image for this liveness detection transaction.

ParameterTypeDescriptionNotes
codeIntegerAPI status codePlease refer to below API Code list
messageStringStatus InformationDetailed reasons will be provided about API status
sequence_idStringUnique response codeA unique ID used to track each request
liveness_idStringLiveness detection IDRepresenting unique liveness detection process
imageStringLiveness detection face picturesThe best face picture captured during the liveness detection process, in base64 format
scoreDoubleLiveness detection confidence scoreReserved field. Currently, only the code=200 indicates that the liveness test has been passed.

The front-end failures are listed here below. For back-end failures, please refer to the "API Code" in the next section.

CodeMessage
200success (live person)
20700No face detected
20702Person change detected
20703Detection timeout
20705Screen lock or background exit during detection
20710No camera permission
20711User actively cancels detection on the preparation page
20712User actively cancels detection on the detection page
20749Inconsistent action, tilt head down
60001Network issue, failed to retrieve session
60002Network issue, failed to call anti-hack
11350Internal error

3. Retrive result API

Base URL

API

URLRequest MethodsContent TypeOutput FormatCharacter Set
api-base-url?partner_code=xxx&partner_key=xxxPOSTapplication/jsonJSONUTF-8

Authentication

ParameterTypeDescriptionRequired/OptionalNotes
partner_codeStringPartner CodeRequiredAssigned by TD
partner_keyStringPartner KeyRequiredAssigned by TD

Request

ParameterTypeDescriptionRequired/OptionalNotes
liveness_idStringLiveness detection IDRequiredLiveness detection ID generated in the above SDK output of Step 2, representing unique liveness detection process

Response Parameters

ParameterTypeDescriptionNotes
codeIntegerAPI status codePlease refer to below API Code list
messageStringStatus InformationDetailed reasons will be provided about API status
sequence_idStringUnique response codeA unique ID used to track each request
imageStringLiveness detection face picturesThe best face picture captured during the liveness detection process, in base64 format
scoreDoubleLiveness detection confidence scoreReserved field. Currently, only the code=200 indicates that the liveness test has been passed.

Response Example

  • Request

    {
    	"liveness_id": 1234567
    }
    
  • Success

{
  "code": "200",
  "message": "success",
  "sequence_id": "1679299854228726325924",
  "image": "\/9j\/4AAQSkZJRgABAQAAAQABAAD\/2wBDAAMCA",
  "score": 0.98958
}
  • Failed
{
    "code": 11350,
    "sequence_id": "69b57131b6fb********61ccba118b60",
    "message": "Internal error"
}

API Code

CodeMessageCharged
200success (live person)YES
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