Android-SDK-Liveness Detection API

最近公司翻译英文文档，因为是技术文档，产品又不懂技术，刚好我没什么任务，所以我就接过来翻译一波。在印象笔记上边没找着预览功能，这边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 Name	Function
LivenessActivity	Main page of liveness detection
ResultActivity	The page of detection result
LivenessFragment	The implementation of Liveness Detection
IMediaPlayer	For Audio play
ICamera	The function related with Camera
IDetection	The implementation of Action Order
Screen	To get Screen Parameter
SensorUtil	To monitor Phone’s Sensor

The introduction of SDK classes

Class Name	Function
GuardianLivenessDetectionSDK	SDK’s initialization
DetectionFrame	Frames of camera preview
Detector	Images process during detecting
ResultEntity	The entity class of Network Return

The introduction of Res Files

Res Name	Function
anim_frame_blink	The frame animation of blinking
anim_frame_turn_head	The frame animation of shaking head
anim_frame_open_mouse	The frame animation of opening mouth
icon_liveness_fail	The failure icon of Liveness Detection
icon_liveness_success	The success icon of Liveness Detection
liveness_ic_icon_md_arrow_back	Return button icon
liveness_ic_mask	The mask of liveness detection
liveness_shape_gradient_green	The background of “try again” button
liveness_shape_right_timer	The count down timer background

The introduction of Layout Files

Layout Name	Page
activity_liveness	LivenessActivity
activity_result	ResultActivity
fragment_liveness	LivenessFragment

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

Language	File Definition
English	***
Chinese	***-zh
Indonesian	***-in-rlD

The introduction of Audio Resources

Resource Name	Action
action_blink	blinking
action_open_mouth	opening mouth
action_turn_head	shaking head
detection_failed	fail to detect
detection_success	success in detecting

---

The introduction of Classes and Methods

• GuardianLivenessDetectionSDK

Method name	Explanation
init	The initialization of SDK
isSdkAuthSuccess	if SDK has authorized
setLogEnable	if enable log printing function
isNetworkEnable	if network available

• LivenessFragment

Method name	Explanation
initCameraParams	Initialize camera’s parameters
onSurfaceTextureAvailable	texture’s callback
onPreviewFrame	Camera preview callback, every frame of image information will be returned
onDetectionSuccess	Liveness Detection’s single action success’s callback. It may transfer to SDK next action or end the detection
onDetectionFailed	The callback of Liveness Detection’s failure
onFrameDetected	The result of SDK deal with frames
onDetectionTimeout	The callback of SDK detect time
getLivenessData	Get all detect results after Liveness Detection finished all actions
showActionTipUIView	After action changed, the UI changed to the matched one
playSound	To play hint audio
toResultActivity	To the page of Liveness Detection’s result
updateTipUIView	Update hint text /image
changeType	After action was changed, UI changed correspondingly
onDetectorInitStart	The callback of the Detector Class start its initialization
onDetectorInitComplete	The callback of the Detector Class finished its initialization
onFaceReady	Preparations 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

  Value	Explanation
  SUCCESS	success
  ERROR	server error
  PARAMETER_ERROR	lack of parameter
  IAM_FAILED	fail to authorize
  SSO_AUTH_FAILED	SSO authorization is failure
  TOKEN_EXPIRED	token expired
  RATE_LIMIT_EXCEEDED	API limited
  ACCOUNT_NOT_EXISTED	account not existed
  ACCOUNT_DISABLE	account is unavailable
  ACCOUNT_EXPIRED	account expired

Enum Type Explanation

• Detector.DetectionFailedType: Action type

  Enum	explanation
  NONE	no action
  BLINK	blinking
  MOUTH	open mouth
  POS_YAW	shaking head left and right
  DONE	liveness detection ended
  AIMLESS	no aim

• Detector.DetectionFailedType: the reason of failure

  Enum	Explanation
  TIMEOUT	time out
  FACENOTCONTINUOUS	action is not continuous
  UNAUTHORIZED	fail to authorize
  WEAKLIGHT	light is too dark
  STRONGLIGHT	light is too strong

• Detector.WarnCode:action preparation

  Enum	explanation
  FACEMISSING	Not find people’s face
  FACELARGE	distance is too close
  FACESMALL	distance is too far
  FACENOTCENTER	face is not in center
  FACENOTFRONTAL	face is not right against the screen
  FACENOTSTILL	action range is too large
  FACECAPTURE	please keep face still
  FACEINACTION	action is

• Detector.InitCode:the result of initialization

  Enum	Explanation
  SUCCESS	success
  MODEL_ERROR	model’s error
  EXPIRED	expired
  UNAUTHORIZED	unauthorized
  NATIVE_INIT_FAILED	native is fail to initialize
  ALREADY_INIT	already initialized
  ON_AUTH_CHECK	authorized 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.