react-native

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

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: 4.0MB+
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

Starting from version 0.60.0, React Native migrated to AndroidX(https://reactnative.dev/blog/2019/07/03/version-60#androidx-support), which is not compatible with previous versions. We provide two versions below, and you can choose which one to use based on the React Native version you depend on,download the corresponding SDK, unzip it and copy the liveness folder to the android directory, same level as the app folder.
- If you are using React Native version 0.59.x or earlier, click to download the non-AndroidX version.
- If you are using React Native version 0.60.0 or later, click to download the AndroidX version.

Modify the build.gradle file found in the liveness folder so that the dependency for liveness-detection-rn is set to version 3.4.1.


xxxxxxxxxx
...
dependencies {
    ...
    api 'ai.advance.mobile-sdk.android:liveness-detection-rn:3.4.1'
}

Modify the android/settings.gradle file as follows to add a reference to the liveness module


xxxxxxxxxx
...
include ':app', ':liveness'

If your project's com.facebook.react:react-native library version number is greater than or equal to 0.60.0, you need to add the following configuration to your android/gradle.properties file
```
xxxxxxxxxx
android.enableJetifier=true
```

Modify the android/app/build.gradle file to add library dependencies, and then synchronize gradle to complete the SDK dependency configuration


xxxxxxxxxx
...
android {
  ...
}
dependencies {
  ...
  // Add the following dependencies
  api project(':liveness')
}

If pulling aar fails, we recommend trying the following：

If your gradle version is less than 7.0, add the maven repository to the project's root build.gradle:


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

If your project's gradle version is greater than 7.0, add a maven repository to the project's root directory settings.gradle:


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

If the above still does not pull the aar, you can download the aar from the following link and manually depend on it for your project:
The links below are for lib 3.1.0 and core 5.5. Modify the version number in the link to download the corresponding version.

SDK Version Updates

View Version History

View version update notes

liveness/build.gradle has the version that the SDK depends on,update the SDK by modifying the version number.


xxxxxxxxxx
dependencies {
    implementation 'com.android.support:appcompat-v7:28.0.0'
    api 'ai.advance.mobile-sdk.android:liveness-detection-rn:3.4.1'
    implementation 'com.android.support.constraint:constraint-layout:2.0.4'
}

Usage

Add LivenessReactPackage.

In the android/app directory, find the class that implements ReactApplication with the default name MainApplication, add LivenessReactPackage


xxxxxxxxxx
import ai.advance.liveness.sdk.rn.LivenessReactPackage;

public class MainApplication extends Application implements ReactApplication {
    
  private final ReactNativeHost mReactNativeHost = new ReactNativeHost(this) {
      
   @Override
      protected List<ReactPackage> getPackages() {
          return Arrays.<ReactPackage>asList(
                  new MainReactPackage(), new LivenessReactPackage()
          );
      }
      ...
  }
  ...
}

Initialize the SDK.

Available values for Market: [Indonesia, India, Philippines, Philippines2, Vietnam, Malaysia, Thailand, BPS, CentralData, Mexico, Singapore, Aksata, Pakistan, Nigeria]


xxxxxxxxxx
// 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.
NativeModules.LivenessModule.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
NativeModules.LivenessModule.setLicenseAndCheck("your license",(successCode)=>{
  // license check success,you can start liveness detection.
},(errorCode)=>{
  // 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 detection timeout duration.


xxxxxxxxxx
// Settable input range: [10000,60000]，unit: milliseconds.Default  value is 50000
NativeModules.LivenessModule.set3DLivenessTimeoutMills(50000);

Capture audit images.

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


xxxxxxxxxx
// The first parameter:The function open switch,default value is false
// The second parameter:Minimum interval time for capturing images,default interval is 400ms
// The third parameter:Maximum number of captured images,default number is 10
// The fourth parameter:The image width,default width is 400px
// The fifth parameter:The image compress quality,must in [30,100],the default value is 30
NativeModules.LivenessModule.setAuditImageConfig(true,400,10,400,30)

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.
NativeModules.LivenessModule.setVideoRecorderConfig(true,60)

Customize the size of the returned image


xxxxxxxxxx
// Settable input range: [300,1000], unit: pixels
NativeModules.LivenessModule.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
NativeModules.LivenessModule.bindUser("your user id") 
```

Turn on occlusion detection

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


xxxxxxxxxx
NativeModules.LivenessModule.isDetectOcclusion(true)

Start the liveness detection and obtain the test 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
NativeModules.LivenessModule.startLiveness(
        (successJsonData)=>{
        // This callback indicates Liveness Detection success
        },
        (failedJsonData)=>{
         // This callback indicates that the Liveness Detection failed or the user canceled the detection
        }
      )
    }}

successJsonData sample


xxxxxxxxxx
{
    "livenessId":"8ad94d7d-fbcb-40f5-9567-21cce6986f7d",// The picture id
    "eventId":"a1c16a7d-bdcc-12g5-1697-11dda0191d9a",// The event id
    "livenessBase64Str":"/9j/4AAQSk.....",// The images collected in base64 format(Far)
    "nearImageBase64Str":"/1d/a4adKs.....",// The images collected in base64 format(Near)
    "auditImages":[
      {
        "base64Image":"/6e/aDDmQSk.....",
        "timestamp":1705981496161
      },
      {
        "base64Image":"/e4/A1DmsMa.....",
        "timestamp":1705981497313
      }
    ],// The audit image list
    "videoFilePath":"/data/user/0/ai.advance.liveness.demo/files/aai_liveness_1705981830603.mp4",// The video file path
    "transactionId":"1384b4d0cbb6adae",// The transaction id
    "isPay":true // Whether this call is charged
  }

failedJsonData sample


xxxxxxxxxx
{
    "eventId":"a1c16a7d-bdcc-12g5-1697-11dda0191d9a",// The event id
    "errorMessage":"xxx",// Failed message,maybe null
    "errorCode":"xxx",// Failed code
    "videoFilePath":"/data/user/0/ai.advance.liveness.demo/files/aai_liveness_1705981830603.mp4",// The video file path
    "transactionId":"1384b4d0cbb6adae"// The transaction id,maybe null
  }

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 android/app/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

NoSuchMethodError
If you encounter a java.lang.NoSuchMethodError: No virtual method putArray(Ljava/lang/String;Lcom/facebook/react/bridge/WritableArray;)V in class Lcom/facebook/react/bridge/WritableNativeMap; or its super classes (declaration of 'com.facebook.react.bridge.WritableNativeMap' during the compilation process, Please switch to the following integrated approach.
```
xxxxxxxxxx
ai.advance.mobile-sdk.android:liveness-detection-rn-74:3.4.1
```
The error stems from the SDK being compiled for an outdated RN SDK version, incompatible with higher RN environments. To resolve this, we've rebuilt the SDK for RN 0.74, which necessitates JDK 17 for Android builds as per official guidelines. Ensure you're using JDK 17 post-upgrade to avoid compilation issues and maintain app functionality.