kmm

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

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

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

If you want to use the default UI style, add the dependency to your project's /shared/build.gradle.kts as follows:


xxxxxxxxxx
...
android {
  ...
  dependencies {
    api("ai.advance.mobile-sdk.android:liveness-detection:3.4.1")
    api("androidx.appcompat:appcompat:1.6.1")
    api("androidx.constraintlayout:constraintlayout:2.1.4")
    // The default UI library
    api(":ai.advance.mobile-sdk.android:liveness-detection-ui:3.4.1@aar")
  }
}

If you need to customize the UI, follow these steps:

Click this link to Download UI Module Source Code and unzip it
Copyliveness-kotlin/liveness/src/main/kotlin/aifolder to shared/src/androidMain/kotlin
Copyliveness-kotlin/liveness/src/main/resfolder toshared/src/androidMain/,If the res folder already exists in the androidMain folder, you need to manually merge the contents of the two res folders.
Copyliveness-kotlin/liveness/src/main/AndroidManifest.xmlfolder toshared/src/androidMain/,If the AndroidManifest.xml file already exists in the androidMain folder, open the existing file and register the LivenessActivity in the node.

Open the settings.gradle.kts file in the root directory and add the following maven repository configuration:


xxxxxxxxxx
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://public-n3.advai.net/repository/maven-releases/' }
    }
}

Open /shared/build.gradle.kts and add the following dependencies:


xxxxxxxxxx
...
android {
  ...
  dependencies {
    api("ai.advance.mobile-sdk.android:liveness-detection:3.4.0")
    api("androidx.appcompat:appcompat:1.6.1")
    api("androidx.constraintlayout:constraintlayout:2.1.4")
  }
}

SDK Version Updates

Usage

Initialization SDK.

The init method need to be called in your application class


xxxxxxxxxx
// The last boolean value represents whether the Global service is enabled or not, and is set to true if it is, or false if it is not. 
GuardianLivenessDetectionSDK.init(this,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
String license = "xxx"
String checkResult = GuardianLivenessDetectionSDK.setLicenseAndCheck(license)
if ("SUCCESS".equals(checkResult)) {
    // license valid
   startLivenessActivity()
} else {
  // license is not available, expired/wrong format/appId not filed
}

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 the background color of the livenessView(do not overlay a mask image on the LivenessView, if you have, please remove it)


xxxxxxxxxx
mLivenessView.setMaskColor(getResources().getColor(R.color.xxx);

Set the color of the oval frame in the livenessView:


xxxxxxxxxx
mLivenessView.setOvalColor(getResources().getColor(R.color.xxx));

Capture audit images.

When this feature is enabled, we will capture multiple images during the user's movement based on your configuration.


xxxxxxxxxx
GuardianLivenessDetectionSDK.setAuditImageConfig(new AuditImageConfig
                .AuditImageConfigBuilder()
                .setEnableCollectSwitch(true)// The function open switch,default value is false
                .setImageCaptureInterval(400)// Minimum interval time for capturing images,default interval is 400ms
                .setImageMaxNumber(10)// Maximum number of captured images,default number is 10
                .setImageWidth(400)// The image width,default width is 400px
                .setImageQuality(30)// The image compress quality,must in [30,100],the default value is 30
                .build())

Get audit images


xxxxxxxxxx
List<LivenessImageData> auditImageList = LivenessResult.getAuditImageList()

// data structure
public class LivenessImageData {
    public final String base64Image;// Base64 format image
    public final long timestamp;// Timestamp of image capture.
}

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
GuardianLivenessDetectionSDK.setRecordVideoSwitch(true)
GuardianLivenessDetectionSDK.setMaxRecordVideoSeconds(60)// Maximum recording duration, in seconds, valid range [2,60], default is 60 seconds.

Get video file


xxxxxxxxxx
File videoFile = LivenessResult.getVideoFile(this)

Set detection timeout duration.


xxxxxxxxxx
// Settable input range: [10000,60000]，unit: milliseconds,default value is 50000
GuardianLivenessDetectionSDK.set3DLivenessTimeoutMills(50000)

Customize the size of the returned image


xxxxxxxxxx
// Settable input range: [300,1000], unit: pixels
GuardianLivenessDetectionSDK.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
GuardianLivenessDetectionSDK.bindUser(String 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
GuardianLivenessDetectionSDK.isDetectOcclusion(true)

Start the liveness detection and obtain the 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
public class SomeActivity extends Activity{

    /**
     * requestCode
     */
    public static final int REQUEST_CODE_LIVENESS = xxxx;

    /**
     * start Liveness Activity
     */
    private void startLivenessActivity() {
      Intent intent = new Intent(this, LivenessActivity.class);
      // Set camera type, default is front camera
      GuardianLivenessDetectionSDK.setCameraType(CameraType.FRONT);// The back camera is CameraType.BACK
      startActivityForResult(intent, REQUEST_CODE_LIVENESS);
  }

  /**
   * get Liveness result
   */
  @Override
  protected void onActivityResult(int requestCode, int resultCode, Intent data) {
      super.onActivityResult(requestCode, resultCode, data);
      if (requestCode == REQUEST_CODE_LIVENESS) {
        // Please make sure to save eventId for contacting us for troubleshooting purposes
        String eventId = LivenessResult.getEventId();
        File videoFile = LivenessResult.getVideoFile(this);// The video file
        if (LivenessResult.isSuccess()) {// Success
          String livenessId = LivenessResult.getLivenessId();// livenessId
          boolean pay = LivenessResult.isPay();// pay status
          Bitmap livenessBitmap = LivenessResult.getLivenessBitmap();// picture(Far)
          Bitmap nearBitmap = LivenessResult.getNearBitmap();// picture(Near)
          List<LivenessImageData> auditImageList = LivenessResult.getAuditImageList();// Audit images
        } else {// Failure
          String errorCode = LivenessResult.getErrorCode();// error code
          String errorMsg = LivenessResult.getErrorMsg();// error message
            ...
        }
      }
    }
  }

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
```