Android-SDK-Liveness Detection API

宿嘉庆
2023-12-01

最近公司翻译英文文档,因为是技术文档,产品又不懂技术,刚好我没什么任务,所以我就接过来翻译一波。在印象笔记上边没找着预览功能,这边markdown有预览功能,所以就直接写这里边复制粘贴了。

The introduction of LIVENESS classes

For extension, the codes of Liveness Detection mainly were put in the LivenessFragment, and LivenessActivity only used for Attach.

Class NameFunction
LivenessActivityMain page of liveness detection
ResultActivityThe page of detection result
LivenessFragmentThe implementation of Liveness Detection
IMediaPlayerFor Audio play
ICameraThe function related with Camera
IDetectionThe implementation of Action Order
ScreenTo get Screen Parameter
SensorUtilTo monitor Phone’s Sensor

The introduction of SDK classes

Class NameFunction
GuardianLivenessDetectionSDKSDK’s initialization
DetectionFrameFrames of camera preview
DetectorImages process during detecting
ResultEntityThe entity class of Network Return

The introduction of Res Files

Res NameFunction
anim_frame_blinkThe frame animation of blinking
anim_frame_turn_headThe frame animation of shaking head
anim_frame_open_mouseThe frame animation of opening mouth
icon_liveness_failThe failure icon of Liveness Detection
icon_liveness_successThe success icon of Liveness Detection
liveness_ic_icon_md_arrow_backReturn button icon
liveness_ic_maskThe mask of liveness detection
liveness_shape_gradient_greenThe background of “try again” button
liveness_shape_right_timerThe count down timer background

The introduction of Layout Files

Layout NamePage
activity_livenessLivenessActivity
activity_resultResultActivity
fragment_livenessLivenessFragment

The introduction of multi-languages

Postscript: As below show, these languages were supported in the SDK, and they will adapt to the phones’ languages automatically. Also, it is available to remove any of their language files if you don’t need them.
*** represent resources , eg: raw

LanguageFile Definition
English***
Chinese***-zh
Indonesian***-in-rlD

The introduction of Audio Resources

Resource NameAction
action_blinkblinking
action_open_mouthopening mouth
action_turn_headshaking head
detection_failedfail to detect
detection_successsuccess in detecting

The introduction of Classes and Methods

  • GuardianLivenessDetectionSDK
Method nameExplanation
initThe initialization of SDK
isSdkAuthSuccessif SDK has authorized
setLogEnableif enable log printing function
isNetworkEnableif network available
  • LivenessFragment
Method nameExplanation
initCameraParamsInitialize camera’s parameters
onSurfaceTextureAvailabletexture’s callback
onPreviewFrameCamera preview callback, every frame of image information will be returned
onDetectionSuccessLiveness Detection’s single action success’s callback. It may transfer to SDK next action or end the detection
onDetectionFailedThe callback of Liveness Detection’s failure
onFrameDetectedThe result of SDK deal with frames
onDetectionTimeoutThe callback of SDK detect time
getLivenessDataGet all detect results after Liveness Detection finished all actions
showActionTipUIViewAfter action changed, the UI changed to the matched one
playSoundTo play hint audio
toResultActivityTo the page of Liveness Detection’s result
updateTipUIViewUpdate hint text /image
changeTypeAfter action was changed, UI changed correspondingly
onDetectorInitStartThe callback of the Detector Class start its initialization
onDetectorInitCompleteThe callback of the Detector Class finished its initialization
onFaceReadyPreparations done, the callback of start to Liveness Detection
  • ICamera

       /**
        * Open camera front-camera
        * @param activity current page
        * @return Camere Object
        */
      public Camera openCamera(Activity activity);
        
        /**
         *  start to detect face
         *
         * @param callback preview callback
         */
       public void actionDetect(Camera.PreviewCallback callback);
          
        /**
         * start to preview
         *
         * @param surfaceTexture    attached textureView
         */
      public void startPreview(SurfaceTexture surfaceTexture);
          
        /**
         * close camera and release related resources
         */
      public void closeCamera(); 
    
  • IDetection

       /**
        * To change detection type 
        *
        * @param detectiontype  Action Type
        */	
      public void changeType(final Detector.DetectionType detectiontype);
            
         /**
      	* Get hint image or animation according to detection type
      	*
      	* @param detectionType 
      	* @return image or animation hint type
      	*/
      public AnimationDrawable getDrawRes(Detector.DetectionType detectionType);
      
         /**
      	* Get hint text by detection type
      	*
      	* @param detectionType 
      	* @return hint text
      	*/
      public String getDrawRes(Detector.DetectionType detectionType);
      
        /**
         * The initialized action order, default random. You can define the action order by yourself.
         */ 
      public void detectionTypeInit()  
    
  • IMediaPlayer

       /**
        * For media play
        * @param rawId  resources id
        */
     public void doPlay(int rawId);
       /**
        * Get audio resources' id by detection type
        *
        * @param detectionType 
        * @return resources id
        */
     public static int getSoundRes(Detector.DetectionType detectionType) 
    
  • DetectionFrame

       /**
        * current frame's byte data and it's yuv format.
        * @return
        */
      public byte[] getYUVData()     	     
       /**
        * if current frame has face
        * @return
        */
      public byte[] hasFace()
       /**
        * current frame in bitmap
        * @return
        */
      public Bitmap getBitmap()	     
       /**
        * current frame's width in bitmap
        * @return
        */
      public int getWidth()
       /**
        * current frame's height in bitmap
        * @return
        */
      public int getHeight()	    		                
    
  • Detector

        /**
         * constructor,default parameters are adapted. 
         */
       public Detector();
       
        /**
         * @param detectionConfig Liveness detection parameter config 
         */
       public Detector(DetectionConfig detectionConfig)
                
        /**
         * @param detectionListener setCallback of Liveness Detection 
         */
       public setDetectionListener(DetectionListener detectionListener)
        /**
         * Initialization 
         * @param firstDetectionType First detecting action
         * @return the result of initialization
         */
       public synchronized InitCode init(DetectionType firstDetectionType)
        /**
         * Initialization
         * @param firstDetectionType First detecting action
         * @param callback the callback of initialization 
         * @return the result of initialization
         */
       public synchronized InitCode init(DetectionType firstDetectionType, DetectorInitCallback callback)
        /**
         * Image analysis
         *
         * @param data          every frame's data
         * @param previewWidth  width of camera preview
         * @param previewHeight height of camera preview
         * @param angle         camera angle
         * @return
         */
       public boolean doDetection(byte[] data, int previewWidth, int previewHeight)
        /**
         * Get detection result
         * @return model of detection result
         */
       public ResultEntity getFaceMetaData()
    
  • ResultEntity

      /**
       * success or failure code
       */
      public String code;
      /**
       * if request success
       */
      public boolean success;
      /**
       * information details
       */
      public String data;
      /**
       * return the object when exception occurred 
       */
      public Exception exception;
      /**
       * return message 
       */
      public String message;
      /**
       * return extra
       */
      public String extra; 
    

    ResultEntity code explanation

    ValueExplanation
    SUCCESSsuccess
    ERRORserver error
    PARAMETER_ERRORlack of parameter
    IAM_FAILEDfail to authorize
    SSO_AUTH_FAILEDSSO authorization is failure
    TOKEN_EXPIREDtoken expired
    RATE_LIMIT_EXCEEDEDAPI limited
    ACCOUNT_NOT_EXISTEDaccount not existed
    ACCOUNT_DISABLEaccount is unavailable
    ACCOUNT_EXPIREDaccount expired

Enum Type Explanation

  • Detector.DetectionFailedType: Action type

    Enumexplanation
    NONEno action
    BLINKblinking
    MOUTHopen mouth
    POS_YAWshaking head left and right
    DONEliveness detection ended
    AIMLESSno aim
  • Detector.DetectionFailedType: the reason of failure

    EnumExplanation
    TIMEOUTtime out
    FACENOTCONTINUOUSaction is not continuous
    UNAUTHORIZEDfail to authorize
    WEAKLIGHTlight is too dark
    STRONGLIGHTlight is too strong
  • Detector.WarnCode:action preparation

    Enumexplanation
    FACEMISSINGNot find people’s face
    FACELARGEdistance is too close
    FACESMALLdistance is too far
    FACENOTCENTERface is not in center
    FACENOTFRONTALface is not right against the screen
    FACENOTSTILLaction range is too large
    FACECAPTUREplease keep face still
    FACEINACTIONaction is
  • Detector.InitCode:the result of initialization

    EnumExplanation
    SUCCESSsuccess
    MODEL_ERRORmodel’s error
    EXPIREDexpired
    UNAUTHORIZEDunauthorized
    NATIVE_INIT_FAILEDnative is fail to initialize
    ALREADY_INITalready initialized
    ON_AUTH_CHECKauthorized is checking

About custom UI

You could open the file colors_theme.xml in the directory res-values. In the files liveness_accent and liveness_accent_reverse could be modified to change the color. Two type of theme -black and white- were provided.

		<?xml version="1.0" encoding="utf-8"?>
		<resources>
		    <!--black-->
		    <color name="liveness_color_dark">#000000</color>
		    <!--white-->
		    <color name="liveness_color_light">#ffffff</color>
		    <!--The color value will change the background color-->
		    <color name="liveness_accent">@color/liveness_color_light</color>
		    <!--This color value will change text color-->
		    <color name="liveness_accent_reverse">@color/liveness_color_dark</color>
		</resources>

In the drawable dirctory, all image resources could be replaced with custom images. Also, two type of theme were provided. The theme files could find in zips.

 类似资料: