Integration Documentation(CustomView Mode)

This document introduces how to integrate the SDK without depending on the UI module.

Installation

1. Add the repository

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

2. Add the dependencies in your project's gradle：

   implementation 'ai.advance.mobile-sdk.android:liveness-detection:4.1.1'
   

3. If your application has package size constraints or you need to reduce the app bundle size, you can optimize by excluding the model file module from the dependencies in step 2. This modification reduces the SDK package size by approximately 1.4MB. The model files will be downloaded automatically when users first launch the SDK. Please be aware that network connectivity issues may cause download failures.

   implementation ('ai.advance.mobile-sdk.android:liveness-detection:4.1.1'){
       exclude group: 'ai.advance.mobile-sdk.android', module: 'liveness-detection-model'
   }
   

Migration Guides

If you are upgrading from an older version of the Liveness SDK, please refer to this document to understand the changes.

Usage

1. Initialization SDK.

   The init method need to be called in your application class

   GuardianLivenessDetectionSDK.init(new SDKLicenseAuthModeConfig.Builder()
                                     .setMarket(Market market)
                                     .setIsGlobalService(boolean isGlobalService)
                                     .build(), this);
   

2. Check License

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

   ​x
   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.
   

3. Create LivenessView in XML. Below is the suggested syntax.

   The LivenessView must remain square, with a maximum width of 1.3 times the screen width.

   <aai.liveness.LivenessView
       android:id="@+id/liveness_view"
       android:layout_width="0dp"
       android:layout_height="0dp"
       app:layout_constraintDimensionRatio="H,1:1"
       app:layout_constraintWidth_percent="0.8"/>
   

4. Create launch configuration.

   Before starting live detection, you need to create a launch configuration object. Below is a demonstration along with an introduction to the method.

   LivenessConfig configs = new LivenessConfig.Builder()
                   .setCameraType(CameraType.FRONT)// FRONT or BACK camera
                   .setQueryId(queryId)// In ticket authentication mode, you need to pass the queryId,other authentication modes do not require it.
                   .setTicket(ticket)// In ticket authentication mode, you need to pass the ticket,other authentication modes do not require it.
                   .setDetectOcclusion(false)// Set whether to enable occlusion detection. It is false by default.
                   .setAuditImageConfig(new AuditImageConfig // Audit image configs
                           .AuditImageConfigBuilder()
                           .setEnableCollectSwitch(true) // Set whether to enable audit image collection. It is false by default.
                           .setImageWidth(400)// The width of audit images
                           .setImageMaxNumber(5)// The the max count of image
                           .setImageQuality(30)// The quality of audit images,must in [30,100].It is 30 by default.
                           .setRelativeSecondsCaptureAfterCameraLaunched(3f)// If you want to collect images relative to the camera's open time, you can set the relative time here (unit: seconds).
                           .build())
                   .setLivenessType("your liveness type")// Set the liveness type
                   .setSignatureId("your signature id")// Set the signatureId
                   .setMaskColor(Color.GREEN))// Set the LivenessView mask color
                   .setOvalColor(Color.GREEN)// Set the oval light color
                   .setOvalNormalColor(Color.GRAY)// Set the oval normal color
                   .setDistantNearTimeout(50_000) // Set the timeout limit of Distant-Near liveness stage
                   .setSilentTimeout(50_000)// Set the timeout limit of Silent liveness stage
                   .setActionTimeout(10_000)// Set the timeout limit for each action.
                   .setPrepareMillSeconds(0)// Set the waiting time before starting liveness detection (during this stage, the client can perform UI interactions to prompt the user to get ready).
                   .setResultPictureSize(600)// Customize the size of the returned image,Settable input range: [300,1000], unit: pixels.It is 600 by default.
                   .setMaxRecordVideoSeconds(600)// Set the maximum duration for video recording in seconds,unit:seconds,If set to 0, it means no video will be recorded.
                   .setUserId("your unique user id")// 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.
                   .build();
   

5. Start detection.

   Set the configs created in the previous step to livenessView as the launch configuration

   // All callback methods in the LivenessCallback are executed on the main thread.
   mLivenessView.startDetection(livenessConfigs, new LivenessCallback() {
                   @Override
                   public void onDetectorInitStart() {
                       // Detector init is starting. You need to have a loading screen here because the initialization is time-consuming and requires network requests to obtain configuration parameters.
                   }
   
                   @Override
                   public void onDetectorInitComplete(boolean isValid, String errorCode, String message) {
   // Detector init is complete. You can hide the loading screen from the onDetectorInitStart function. Here, check the isValid to determine if the initialization was successful. If it’s not successful, you need to handle it based on the different codes.
                   }
   
                   @Override
                   public void onLivenessStageChanged(LivenessStage livenessStage) {
   // Triggered when the liveness stage changes. You can make changes to the prompt message or other effects here.
                   }
   
                   @Override
                   public void onDetectionFrameStateChanged(LivenessStage livenessStage, WarnCode warnCode) {
   // Code callbacks during the detection process. You need to provide prompt messages based on different warnCode values. For specifics, you can refer to the UI source code prompts.
                   }
   
                   @Override
                   public void onActionRemainingTimeChanged(long remainingTimeMills) {
   // Called by Remaining time changed of current stage,is necessary to update countdown timer view.The unit of remainingTimeMills is milliseconds.
                   }
   
                   @Override
                   public void onDetectionFailed(DetectionFailedType failedType, LivenessStage detectionType) {
   // Callback for when liveness detection failed; this detection session has ended.
                   }
   
                   @Override
                   public void onUploadFaceDataStart() {
   // The mobile detection is complete, and you are preparing to upload the image to the server. You need to display a loading message here to inform the user that data is being uploaded.
                   }
   
                   @Override
                   public void onUploadFaceDataComplete() {
   // Data upload is complete. You can hide the loading screen and retrieve the results from LivenessResult.
                   }
               });
   

6. Get liveness results.

   LivenessResult is static, meaning you can access the liveness results from any page.

   // 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
       ...
    }
   

7. Destroy the LivenessView.

   In the finish method of the activity, you need to manually end the detection to free up resources.

   @Override
   public void finish() {
     mLivenessView.stopDetection();
     super.finish();
   }