cordova

Android 3D Liveness Detection SDK (v3.4.1) User Guide(For Cordova)

Development Preparation

Overview

Minimum Android version：4.4 (API Level:19)
Compilation Android SDK version：API Level：34
Additional dependent third-party libraries: None
Supported CPU architectures：armeabi-v7a，arm64-v8a
SDK package size: 1.3MB model file + about 1MB per CPU architecture
Capture image size: default capture image resolution 600px*600px, size is about 300KB, support custom image size range: 300px~1000px
Supported languages：
- English
- Indonesian
- Vietnamese
- Chinese
- Hendi
- Thai
- Spanish

Use-permissions:

These are required permissions.


xxxxxxxxxx
<uses-feature android:name="android.hardware.camera" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />

Migration Guides

Starting from version 1.3.9, the SDK supports online repository dependencies. We recommend using the online dependency for better convenience and flexibility.
We have fixed some potential crashes on certain Android 12 devices in version 1.3.9.5. If your current version is lower than this, we recommend upgrading to this version to address the issue.
We have addressed some issues detected by the VirusTotal platform. If your promotion relies on the detection results from this platform, please upgrade your SDK version to
- 2.1.7 or above (for action liveness)
- 3.0.9 or above (for 3D liveness)
Starting from version 2.0.0, we have introduced ellipse dashed guidance during the preparation stage. Additionally, we have upgraded the network security policies and updated the SDK models.
From version 3.0.0, SDK Interaction Method Changed to Near-Far Range Detection Mode,motion detection has been removed, so the properties and methods related to motion detection will not have any effect.
We recommend you read the change logs to see what has been updated in the new version of the SDK.

Demo

Install CV-Demo.apk to your phone and log in with the test account.

Installation

Click to download LivenessDetectionPlugin

Unzip and add the LivenessDetectionPlugin plugin to your project


xxxxxxxxxx
ionic cordova plugin add LivenessDetectionPlugin

open/.../your-project-name/platforms/android/app/build.gradleadd these dependencies:


xxxxxxxxxx
repositories {
  maven {
    url 'https://public-n3.advai.net/repository/maven-releases/'
  }
}

dependencies {
    implementation fileTree(dir: 'libs', include: '*.aar')
    // SUB-PROJECT DEPENDENCIES START
    implementation(project(path: ":CordovaLib"))
    compile "com.android.support:support-annotations:27.+"
    // SUB-PROJECT DEPENDENCIES END
    ...
    // Add the following line of dependencies
    
    implementation 'ai.advance.mobile-sdk.android:liveness-detection-ui:3.4.1'
    implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.4.1'
}

SDK Version Updates

Usage

Initialization SDK.
Available values for Market: [Indonesia, India, Philippines, Philippines2, Vietnam, Malaysia, Thailand, BPS, CentralData, Mexico, Singapore, Aksata, Pakistan, Nigeria]
The last boolean value represents whether you are opening a Global service or not. If so, it is set to true, otherwise it is false.
```
xxxxxxxxxx
cordova.plugins.LivenessDetectionPlugin.initSDKByLicense('your market',false)
```

Check License

The license is obtained by your server calling our openAPI, you need to check license before starting the liveness detection activity.


xxxxxxxxxx
cordova.plugins.LivenessDetectionPlugin.setLicenseAndCheck('your license',success=>{
// start liveness 
},errorCode=>{
  alert(errorCode)
})

The returned values of checkResult:

APPLICATION_ID_NOT_MATCH: The package name is not within the authorized scope, please check your package name.

LICENSE_EXPIRE: The license has expired, please confirm that the user has calibrated the phone time.

ERROR_LICENSE(1): The license parsing succeeded, but necessary authentication information is missing, this case generally will not occur.

ERROR_LICENSE(2): The license parsing succeeded, but the internal format is incorrect, this case also generally will not occur.

ERROR_LICENSE(3): It is highly likely that an incompatible SDK license is being used, such as using an IQA license for liveness detection.

ERROR_LICENSE(4, 5): Parsing failed, please check if the license has issues like mismatched quotes, line breaks, etc.

Set detection timeout duration.


xxxxxxxxxx
// Settable input range: [10000,60000]，unit: milliseconds。Default  value is 50000
cordova.plugins.LivenessDetectionPlugin.set3DLivenessTimeoutMills(50000);

Video recording feature.

By enabling this feature, the SDK will activate video recording. After the completion of the liveness process, you can retrieve the video file using SDK methods. The video file format is .mp4. Please note that this video can only be obtained through the SDK and cannot be obtained from the backend. After using the video, it is up to you to decide whether to delete the local file.


xxxxxxxxxx
// The first parameter:The function open switch,default value is false
// The second parameter:The maximum recording duration, in seconds, valid range [2,60], default is 60 seconds.
cordova.plugins.LivenessDetectionPlugin.setVideoConfig(true,60);

Customize the size of the returned image


xxxxxxxxxx
cordova.plugins.LivenessDetectionPlugin.setResultPictureSize(600)

User binding (strongly recommended).

You can use this method to pass your user unique identifier to us, we will establish a mapping relationship based on the identifier.It is helpful for us to check the log when encountering problems.


xxxxxxxxxx
cordova.plugins.LivenessDetectionPlugin.bindUser('your unique userId')

Turn on occlusion detection

If you want to enable occlusion detection, please call the following method after initializing the SDK to set it


xxxxxxxxxx
cordova.plugins.LivenessDetectionPlugin.isDetectOcclusion(true)

Start the liveness detection check and obtain the check result.

Each time the liveness detection is successful, a unique livenessId and a clear photo of 600*600 pixels for this detection will be returned.

You need to give the livenessId to your server, and the server will call openAPI to get the score of this detection.
You can get the image directly through the methods provided by the SDK, or you can call the openAPI from the server.

Important: After each liveness session, please make sure to save the eventId. If users have any questions or issues during the usage, please provide us with the eventId for troubleshooting. Without the eventId, it will be difficult to investigate the problem.


xxxxxxxxxx
cordova.plugins.LivenessDetectionPlugin.startLivenessDetection(result=>{
  log(result)
})

A success result sample


xxxxxxxxxx
{
  "image":"/9j/4AAQSk.....",
  "nearImage":"/1d/a4adKs.....",
  "eventId":"a1c16a7d-bdcc-12g5-1697-11dda0191d9a",
  "videoFilePath":"/data/user/0/ai.advance.liveness.demo/files/aai_liveness_1705981830603.mp4",// The video file path
  "code":null,
  "isPay":true,
  "success":true,
  "errorMessage":"SUCCESS",
  "livenessId":"8ad94d7d-fbcb-40f5-9567-21cce6986f7d",
  "transactionId":"1384b4d0cbb6adae"
}

A failed result sample


xxxxxxxxxx
{
  "image":null,
  "nearImage":null,
  "eventId":"a1c16a7d-bdcc-12g5-1697-11dda0191d9a",
  "code":null,
  "isPay":false,
  "success":false,
  "errorMessage":"xxx",
  "livenessId":null,
  "transactionId":"1384b4d0cbb6adae"
}

Error code

errorCode	raw native sdk code	Description
PREPARE_TIMEOUT	fail_reason_prepare_timeout	Timeout during the preparation stage
ACTION_TIMEOUT	fail_reason_timeout	Timeout during the motion stage
MULTIPLE_FACE	fail_reason_muti_face	Multiple faces detected during the motion stage
FACE_MISSING	fail_reason_facemiss_blink_mouth	Face is missing during the motion stage(blink or open mouth)
FACE_MISSING	fail_reason_facemiss_pos_yaw	Face is missing during the motion stage(pos yaw)
MUCH_ACTION	fail_reason_much_action	Multiple motions detected during the motion stage
USER_GIVE_UP	user_give_up	The user clicked the top left back button during the detection process
NO_RESPONSE		Network request failed
DEVICE_NOT_SUPPORT	device_not_support	The front camera of this device cannot be opened
UNDEFINED		Other undefined errors
AUTH_PARAMETER_ERROR		Authentication Error: Please ensure that the license has been initialized successfully.
AUTH_IAM_FAILED		Authentication Error: Please ensure that the license has been initialized successfully.
WEAK_LIGHT	liveness_weak_light	The light is too weak
STRONG_LIGHT	liveness_too_light	The light is too strong
AUTH_BAD_NETWORK		Failed to authorize network
CHECKING_BAD_NETWORK		Network failed to upload image
MODEL_ERROR		Model error
ALREADY_INIT		Repeated loading
NO_UPLOAD_IMAGE		Failed to capture the best uploaded image
AUTH_TICKET_DISABLE		Ticket is expired
AUTH_ACCOUNT_ACCESS_DENIED		Access for this account is denied
...(Other server side error codes)

Customizable UI

The SDK provides access to the source code of the UI module, allowing you to customize the UI according to the following conditions.

Keep the LivenessView as a square.
Do not overlay any obstructions/masks on top of the LivenessView.

FAQ

Multilingual
Currently SDK supports these languages/voice: English, Indonesian, Chinese,Vietnamese,Hendi,Thai.Automatically switch according to the current language of the mobile phone, no code setting is required.
- The default language for the SDK is English. If it is not consistent with the default language of your app, please manually find the resource in "liveness/res" that corresponds to your app's default language and replace the default resource with it.
- If the SDK does not automatically switch with the system language, please check your cellphone language settings and make sure that both [Region] and [Language] are switched to the corresponding language.
- If it still have problems with multiple languages and the app only supports one language, you can filter out the unwanted languages by adding the following configuration to build.gradle
```
xxxxxxxxxx
android {
    defaultConfig {
      ...
      resConfigs("in-rID") // For example, only Indonesian is supported
    }
} 
```

Code proguard configuration

Please add the following code to your app's proguard file:


xxxxxxxxxx
-keep class aai.liveness.Liveness3DMaskView

About androidx
Considering the mutually exclusive nature of AndroidX and android.support.* packages, all the .aar of this SDK are android.support.* packages. If your project is an AndroidX package and you encounter a android.support.* package conflict error when compiling, please add the following configuration to the gradle.properties file in the root directory of your project and recompile the project and you will be able to：
```
xxxxxxxxxx
android.enableJetifier=true
```