2 User Guide

2.1 Sample project

A sample project for testing is provided under Android Studio. Please refer to the following steps to import.

• Click File > New > Import Project and select Sample to import into Android Studio

• Enter the account information: API_KEY and API_SECRET

Before using the SDK, you need to configure your API_KEY and API_SECRET. Please refer to the code in SilentLivenessActivity:

 private  static  final String API_KEY = "Please input API_KEY";
 private static final String API_SECRET = "Please input API_Secret";

• Rename the license file and place it in the specified directory (please refer to License introduction)

2.2 Integration in Android Studio

2.2.1 Method 1: Quick integration with module dependency

• From File > New > Import Module ... select ../Sample/common-silent. Import common-silent into the project as an import module and add dependencies to build.gradle in app project:

implementation project(':common-silent')

Ensure that the model file (.model) and the license file (.lic) in the assets directory in common-silent are loaded successfully.

• Create repositories under project (same level as your app project) and copy liveness-silent-online-cn-release.aar to this directory. Change build.gradle in the root directory, and then add configuration to repositories as follows:

allprojects {
   repositories {
       google()
       jcenter()
       flatDir {
          dirs '../repositories'
       }
   }
}

• Add permission statement in AndroidManifest.xml as the following example:

<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

• Add Activity statement in the AndroidManifest.xml file as the following example:

<activity android:name="com.sensetime.liveness.silent.SilentLivenessActivity"
android:screenOrientation="portrait"
android:launchMode="singleTop"
android:theme="@android:style/Theme.NoTitleBar"/>

• Static liveness detection can be used by calling SilentLivenessActivity. For details, please refer to startDetectionActivity() method of StartPageFragment in Sample.

2.2.2 Method 2: Deep integration using the libs method; customized development using SDK instead of common-silent

Create a new libs folder under the corresponding app module (not required if libs folder already exists) and copy liveness-silent-online-cn-release.aar to libs. Add the following configuration to build.gradle which is under the app module:

dependencies {
  ...
  implementation fileTree(dir: 'libs', include: ['*.aar'])
 }

Then, the SDK can be called directly for development.

2.3 Resolve code obfuscation

Since crashes may occur after code obfuscation, it is recommended to solve the code obfuscation issue first by the obfuscation configuration.

Specifically, the following code is added to the proguard file to resolve this issue:

-keep class com.sensetime.** { *; }

2.4 Interface call flow

2.4.1 Initialization

The license file and model file needs to be copied to the device in advance.

Call FileUtil.copyAssetsToFile or use other methods to refer to Sample. Then call the init method in SilentLivenessApi.

public static void init(@NonNull final Context context, @NonNull final String licenseFilePath, @NonNull final String detectionModelFilePath, @NonNull final String alignmentModelFilePath, @NonNull final String qualityModelFilePath, @NonNull final String frameSelectorModelFilePath, @NonNull final String antiSpoofingModelFilePath, @NonNull final OnLivenessListener listener)

When the minimum detection duration and the minimum number of detection frames that can pass the silent liveness detection need to be set, they can be set by calling the setPassCondition method after adjusting the init method. For the method description, refer to 2 Optional condition settings for silent liveness detection.

For more information, please refer to OnLivenessListener liveness detection status listener.

Set quality detection

SilentLivenessApi.setBlurryFilterEnable(true, 1.4F);
SilentLivenessApi.setIlluminationFilterEnable(true, 1.899F, 4.997F);
SilentLivenessApi.setEyeOpenThreshold(0.47F);

2.4.2 Optional condition setting for silent liveness detection

Call the following method in SilentLivenessApi to set.

• Set the conditions for liveness detection pass：setPassCondition(final int minDuration, final int minFrames)

• Set the timeout time, in seconds. The default timeout time is 10s：setDetectTimeout(int timeout)

• Set the judgment condition for the face distance. When the parameter value is not in the range or closeRate is not 0 and farRate is greater than closeRate, STID_E_FARCLOSE_INVALID error is reported：setFaceDistanceRate(float farRate, float closeRate)

• Set whether eyebrow occlusion function is needed. The default value is false：setBrowOcclusionEnable(final boolean enable)

• Set whether occlusion function is needed. The default value is false：setOcclusionEnable(final boolean enable)

• Set the threshold of liveness detection：setThreshold(final float threshold)

• Set the threshold of eye status：setEyeOpenThreshold(final float threshold)

• Set whether blurriness detection is needed and the threshold of it：setBlurryFilterEnable(final boolean enable, final float threshold)

• Set whether brightness detection is needed and the threshold of it：setIlluminationFilterEnable(final boolean enable, final float lowLightThreshold, final float brightThreshold)

2.4.3 Ready to start testing

Prepare to start the test by calling SilentLivenessApi start() method.

public static void start()

Method description: Prepare to start testing.

2.4.4 Input data and start detection

Call SilentLivenessApi inputData method to input image data and other parameters for detection.

public static void inputData(byte[] image, PixelFormat format, Size previewSize, Rect containerRect,
            boolean frontCameraOrNot, int cameraOrientation);

Method description: Input for image detection.

2.4.5 Get test results

Implement the method in OnLivenessListener to get the detection result.

void onInitialized();

Method description: Complete initialization.

void onFaceStatusChanged(int facePosition, final FaceOcclusion faceOcclusion, int faceDistance)

Method description: Update alignment status.

void onFailure(ResultCode errorCode, byte[] protobufData, List images, List faceRects, final String requestId, final int statusCode);

Method description: Failed Fiveness detection.

void onSuccess(byte[] protobufData, List images, List faceRects, final String requestId, final int statusCode);

Successful liveness detection

For more information, please refer to OnLivenessListener liveness detection status listener.

2.4.6 Stop the current detection and reset the detection status

Call the SilentLivenessApi stop method.

public static void stop()

Method description: Stop the current detection, and reset the detection status. This method is used to retry after failure. It should be called after the init successes and before the release is called. After it is called, start can be used to restart detection.silentlivenessapi.md)

2.4.7 Cancel detection and release resources

Call the SilentLivenessApi release method.

public static void release();

Method description: Cancel detection and release resources.

2.5 Call private cloud interface for face comparison

After successful liveness detection, the SDK will return the corresponding face image and an encrypted binary file. The returned value can be used as a parameter of the public cloud interface for face comparison.

For the specific description of the private cloud interface, please refer to the SenseID private cloud API manual.