Android端人脸采集SDK4.0使用文档（4.6.0.5）

目录

1 简介	
  1.1 功能介绍	
  1.2 兼容性	
  1.3 开发包说明	
2 集成指南	
  2.1 Sample示例	
  2.2 准备工作	
    2.2.1 申请license
    2.2.2 下载SDK	
  2.3 运行示例工程	
    2.3.1 运行自动配置授权信息的示例工程	
    2.3.2 运行未配置授权信息的示例工程	
  2.4添加SDK到工程	
  2.5权限声明	
3 功能使用	
  3.1 活体识别	
  3.2人脸采集	
  3.3质量校验设置	
  3.4 界面定制说明	
    3.4.1 修改faceplatform_ui界面	
4 接口设计说明	
  4.1人脸功能管理器	
    4.1.1 创建实例	
    4.1.2人脸功能管理器初始化	
    4.1.3设置人脸功能控制参数	
    4.1.4取得人脸图像采集功能接口	
    4.1.5取得活体检测功能接口	
  4.2人脸图像采集器	
    4.2.1设置人脸图像采集功能参数	
    4.2.2人脸图像采集	
  4.3活体检测器	
    4.3.1设置人脸功能控制参数	
    4.3.2活体检测	
  4.4人脸图像采集界面
  4.5 活体检测界面
5 常见问题	

1、简介

百度Face SDK Android 版是一种面向 Android 移动设备人脸技术开发包，此版SDK包含人脸检测、动作活体识别等功能，以aar包+动态链接库的形式发布。 基于该方案，开发者可以轻松的构建包含人脸检测、采集和活体识别的应用。在您使用SDK之前，我们首先为您介绍以下SDK本身及相关人脸能力，以便您能更方便使用人脸服务。

1.1 功能介绍

此版SDK所包含的能力如下：

• 本地版活体检测：通过让用户做出指定人脸配合式的交互动作，识别当前操作者是否为活体。此功能为离线使用，可设定指定动作是否使用及应用顺序。动作包含：眨眼、张嘴、左摇头，右摇头，摇摇头、向上抬头，向下低头。可有效抵御高清图片、3D建模、视频等攻击。说明：用户完成指定动作即判断为活体，不返回相应分数。

  建议搭配线上的在线活体检测接口配合使用，在本地做动作活体检测，云端进行视频翻拍、模型攻击以及合成图攻击的二次校验

• 本地版人脸质量检测：判断视频流中的图片帧中，哪些图片质量较佳，即人脸图像特征清晰（满足角度、姿态、光照、模糊度等校验）。
• 本地版人脸图像采集：通过本地SDK能力，采集人脸图像，同时经过人脸质量检测，确保采集到的人脸图像符合各条件校验（角度、姿态、光照、模糊度等），为设备前端获取有效可分析人脸的主要功能。
• 离线授权：SDK的授权判断，授权介质也称为license，在SDK使用中，需要通过license向授权服务器发起请求，判断SDK的使用合法性及使用有效期。

此版SDK全部功能为离线版本，所有功能均本地化使用，主要用于在客户端（Android）获取人脸，实际业务使用中，可以按照业务需要，配合在线API完成全流程的业务集成。

1.2 兼容性

系统：支持 Android 4.0.3(API Level 15)及以上系统。需要开发者通过 minSdkVersion来保证支持系统的检测。

机型：手机，平板暂不支持

构架：支持 CPU架构平台【arm-v7，arm-64，x86】

网络：支持 WIFI 及移动网络,移动网络支持使用NET 网关及 WAP 网关(CMWAP、CTWAP、UNIWAP、3GWAP)。

1.3 开发包说明

2、集成指南

本章将进行 Step-By-Step的讲解,如何快速的集成 人脸Sdk到现有应用中。一个完整的Demo 请参考开发包中的示例程序 FacePlatform。方案架构参考下图：

2.1 准备工作

2.1.1 申请license

人脸SDK License：此license用于SDK离线功能使用，在您的申请人脸SDK的后台⻚面，全局->产品服 务->人脸识别->本地化部署->离线采集SDK申请

人脸控制台路径如下：

点击客户端SDK管理，弹出如下图：创建应用（这里创建应用是为了使用离线SDK，上面创建应用为了使用人脸在线接口，如注册、识别等）

在弹出的框中输入授权标识，选择应用类型，应用系统，以及包名、MD5签名，详情请查看输入框右边提示

2.1.2 下载SDK

下载SDK分为自动配置授权信息（创建license后就可以选择为该应用，下载后SDK自动帮您配置授权，不用下载license拷贝到工程中，初始化参数licenseID,包名也帮您配置好了）和未配置授权信息两种方式：

2.2 运行示例工程

2.3.1 运行自动配置授权信息的示例工程

该下载的示例工程，已经帮你改好了license和包名

• Android Studio导入下载的示例工程
• 配置打包签名文件，由于SDK运行时会校验签名文件的MD5是否和申请时填入一样。为了便于debug能正常使用SDK，需要配置打包签名文件。
• 运行示例工程

2.3.2 运行未配置授权信息的示例工程

（1）Android Studio导入下载的示例工程

（2）下载license拷贝到工程的assets目录

（3）修改Config类

（4）修改app.gradle和AndroidManifest里面的包名为申请license填入的包名，如上图安卓包名。

（5）配置打包签名文件，由于SDK运行时会校验签名文件的MD5是否和申请时填入一样。为了便于debug能正常使用SDK，需要配置打包签名文件。

（6）运行示例工程。如果无法正常体验，请查看logcat日志。是否有 FaceSDK-License LICENSE_INFO_CHECK_ERROR日志。如果有说明授权没有成功，可以查看本文档最后的常见问题进行解决。

2.4 添加SDK到工程

FaceSdk以androidstudio开发方式提供，以下介绍在android studio开发工具导入FaceSdk

（1）将开发包中的faceplatform-release库Copy 到工程根目录。

（2）将开发包中的faceplatform-ui库Copy 到工程根目录。

（3）SDK提供的了开源的faceplatform-ui库，把活体检测和人脸图像采集功能等功能进行了封装，适配了主流机型机型。如果需要使用，请添加faceplatform-ui模块到的工程中。faceplatform-ui目录结构如下图

（4）在build.gradle使用compile project引人faceplatform-ui库工程。

（5）Setting.gradle中include faceplatfrom-ui和facepaltfrom-release

（6）从官网下载授权文件license，复制到app/src/main/assets目录下。

（7）申请的license已经和打包签名key进行了绑定（申请时用到了签名的md5，为了便于debug模式也能调用SDK的功能，需要把debug的key改成申请license的key。

• 把key拷贝到项目根目录下
• 主appbuild.gradle android 下面添加(修改)signingConfigs相关的配置。如下图。

2.5 权限声明

3、功能使用

3.1 人脸采集（包含动作活体）

（1）初始化SDK 调用FaceSDKManager.getIntance().initialize(Context context, String licenseID, String licenseFileName, IInitCallback callback); Demo中此段代码在HomeActivity中。

（2）初始化参数设置

        FaceConfig config = FaceSDKManager.getInstance()
	        .getFaceConfig();
        // 设置可检测的最小人脸阈值
        config.setMinFaceSize(FaceEnvironment.VALUE_MIN_FACE_SIZE);
        // 设置可检测到人脸的阈值
        config.setNotFaceValue(FaceEnvironment.VALUE_NOT_FACE_THRESHOLD);
        // 设置模糊度阈值
        config.setBlurnessValue(FaceEnvironment.VALUE_BLURNESS);
        // 设置光照阈值（范围0-255）
        config.setBrightnessValue(FaceEnvironment.VALUE_BRIGHTNESS);
        // 设置遮挡阈值
        config.setOcclusionValue(FaceEnvironment.VALUE_OCCLUSION);
        // 设置人脸姿态角阈值
        config.setHeadPitchValue(FaceEnvironment.VALUE_HEAD_PITCH);
        config.setHeadYawValue(FaceEnvironment.VALUE_HEAD_YAW);
        // 设置闭眼阈值
        config.setEyeClosedValue(FaceEnvironment.VALUE_CLOSE_EYES);
        // 设置图片缓存数量
        config.setCacheImageNum(FaceEnvironment.VALUE_CACHE_IMAGE_NUM);
        // 设置活体动作，通过设置list，LivenessTypeEunm.Eye, LivenessTypeEunm.Mouth,
        // LivenessTypeEunm.HeadUp, LivenessTypeEunm.HeadDown, LivenessTypeEunm.HeadLeft,
        // LivenessTypeEunm.HeadRight, LivenessTypeEunm.HeadLeftOrRight
        config.setLivenessTypeList(ExampleApplication.livenessList);
        // 设置动作活体是否随机
        config.setLivenessRandom(ExampleApplication.isLivenessRandom);
        // 设置开启提示音
        config.setSound(ExampleApplication.isOpenSound);
	// 原图缩放系数
        config.setScale(FaceEnvironment.VALUE_SCALE);
        // 抠图高的设定，为了保证好的抠图效果，我们要求高宽比是4：3，所以会在内部进行计算，只需要传入高即可
        config.setCropHeight(FaceEnvironment.VALUE_CROP_HEIGHT);
        // 加密类型，0：Base64加密，上传时image_sec传false；1：百度加密文件加密，上传时image_sec传true
        config.setSecType(FaceEnvironment.VALUE_SEC_TYPE);
        FaceSDKManager.getInstance().setFaceConfig(config);

关于抠图内部实现方案如下图所示：

（3） startActivity(new Intent(this, FaceLivenessExpActivity.class))，开启预览。

（4）调用FaceSDKManager.getInstance().getLivenessStrategyModule()获得ILivenessStrategy对象。(该方法每次调用都会返回一个新对象).

（6）调用ILivenessStrategy.setPreviewDegree();设置预览图片的旋转角度。调用setDetectStrategySoundEnable设置是否开启语音。调用setDetectStrategyConfig设置，预览图的大小，人脸检测框的坐标和回调。

（7）多次调用livenessStrategy进行人脸图片采集，人脸跟踪、质量检测、动作活体检测。

（8）实现ILivenessStrategyCallback的onLivenessCompletion并处理结果。其中base64ImageCropMap为存放最佳人脸抠图图片，base64ImageSrcMap为存放最佳人脸原图图片可以查看起父类FaceLivenessActivity的saveImage和base64ToImage方法，获取对于的bitamap。

（9）Demo中针对最优抠图或者最优原图，都会调用SecRequest类下的sendMessage(Context, String secBase64);方法将加密后的base64发送到服务端。

3.2 人脸采集（不包含动作活体）

（1）调用FaceSDKManager.getIntance().initialize(context,Config.licenseID, Config.licenseFileName, IInitCallback callback);初始化SDK.。

（2）初始化SDK参数

	     FaceConfig config = FaceSDKManager.getInstance()
			.getFaceConfig();
        // 设置可检测的最小人脸阈值
        config.setMinFaceSize(FaceEnvironment.VALUE_MIN_FACE_SIZE);
        // 设置可检测到人脸的阈值
        config.setNotFaceValue(FaceEnvironment.VALUE_NOT_FACE_THRESHOLD);
        // 设置模糊度阈值
        config.setBlurnessValue(FaceEnvironment.VALUE_BLURNESS);
        // 设置光照阈值（范围0-255）
        config.setBrightnessValue(FaceEnvironment.VALUE_BRIGHTNESS);
        // 设置遮挡阈值
        config.setOcclusionValue(FaceEnvironment.VALUE_OCCLUSION);
        // 设置人脸姿态角阈值
        config.setHeadPitchValue(FaceEnvironment.VALUE_HEAD_PITCH);
        config.setHeadYawValue(FaceEnvironment.VALUE_HEAD_YAW);
        // 设置闭眼阈值
        config.setEyeClosedValue(FaceEnvironment.VALUE_CLOSE_EYES);
        // 设置图片缓存数量
        config.setCacheImageNum(FaceEnvironment.VALUE_CACHE_IMAGE_NUM);
        // 设置活体动作，通过设置list，LivenessTypeEunm.Eye, LivenessTypeEunm.Mouth,
        // LivenessTypeEunm.HeadUp, LivenessTypeEunm.HeadDown, LivenessTypeEunm.HeadLeft,
        // LivenessTypeEunm.HeadRight, LivenessTypeEunm.HeadLeftOrRight
        config.setLivenessTypeList(ExampleApplication.livenessList);
        // 设置动作活体是否随机
        config.setLivenessRandom(ExampleApplication.isLivenessRandom);
        // 设置开启提示音
        config.setSound(ExampleApplication.isOpenSound);
        // 原图缩放系数
        config.setScale(FaceEnvironment.VALUE_SCALE);
        // 抠图高的设定，为了保证好的抠图效果，我们要求高宽比是4：3，所以会在内部进行计算，只需要传入高即可
        config.setCropHeight(FaceEnvironment.VALUE_CROP_HEIGHT);
        // 加密类型，0：Base64加密，上传时image_sec传false；1：百度加密文件加密，上传时image_sec传true
        config.setSecType(FaceEnvironment.VALUE_SEC_TYPE);
        FaceSDKManager.getInstance().setFaceConfig(config);

（3）startActivity(new Intent(this, FaceDetectExpActivity.class))，开启预览。

（4）调用FaceSDKManager.getInstance().getDetectStrategyModule()获得IDetectStrategy对象。(该方法每次调用都会返回一个新对象).

（5）调用IDetectStrategy.setPreviewDegree();设置预览图片的旋转角度。调用setDetectStrategySoundEnable设置是否开启语音。调用setDetectStrategyConfig设置，预览图的大小，人脸检测框的坐标和回调。

（6） 多次调用detectStrategy进行人脸图片采集。（不带动作活体中支持口罩检测，当口罩分值大于0.7时便认为戴口罩，这时将不会进行遮挡检测）

（7） 实现IDetectStrategyCallback的onDetectCompletion并处理结果。其中base64ImageCropMap为存放最佳抠图人脸，base64ImageSrcMap为存放最佳原图人脸。可以查看起父类FaceDetectActivity的saveImage和base64ToImage方法，获取对于的bitmap。

（8）Demo中针对最优抠图或者最优原图，都会调用SecRequest类下的sendMessage(Context, String secBase64);方法将加密后的base64发送到服务端。

3.3 质量校验设置

com.baidu.idl.face.platform.FaceConfig类用于人脸检测参数设置。

3.4 界面定制说明

3.4.1 修改faceplatform_ui界面

（1）如果SDK自带的UI和您的APP不统一，您可以自行修改FaceDetectRoundView。

（2）修改提示语音音频文件，有两种方式。

a、直接替换FaceUI工程raw下的mp3文件和string.xml。

b、FaceEnvironment 提供了setSoundId(FaceStatusNewEnum status, int soundId); 设置提示音资源。 FaceStatusNewEnum为不同的状态。soundId为资源文件所对应的resource id。

4、接口设计说明#

4.1 人脸功能管理器

4.1.1创建实例

• 方法

  FaceSDKManager getInstance()

• 参数

  无

• 返回

  人脸功能管理器

• 说明

  创建人脸功能管理器

4.1.2 人脸功能管理器初始化

• 方法

  public void initialize(final Context context, String licenseID, StringlicenseFileName, IInitCallback callback)

• 参数

  context 上下文环境，licenseID 传入申请License时获取的应用名称+_face_android后缀，licenseFileName 鉴权文件名称， callback 鉴权成功与否回调

• 返回

  无

• 说明

  初始化人脸检测功能。进行人脸检测功能License鉴权验证。

4.1.3 设置人脸功能控制参数

• 方法

  void setFaceConfig(FaceConfig config)   

• 参数

  config 人脸功能控制参数对象

• 返回

  无

• 说明

  设置人脸功能控制参数对象。

  FaceConfig对象参数：

  光照阈值

  图像模糊阈值

  人脸遮挡阈值

  头部姿态角度

  最小人脸检测阈值

  人脸检测精度阈值

  截取人脸图片大小

  进行活体检测的动作类型列表

  是否进行人脸图片质量检测

4.1.4 取得人脸图像采集功能接口

• 方法

   IDetectStrategy getDetectStrategyModule()

• 参数

  无

• 返回

  人脸图像采集功能接口

• 说明

  取得人脸图像采集功能接口。人脸图像采集接口完成，解析图片人脸信息，返回检测结果。

4.1.5 取得活体检测功能接口

• 方法

• ILivenessStrategy getLivenessStrategyModule()

• 参数

  无

• 返回

  活体检测功能接口

• 说明

  取得活体检测功能接口。活体检测功能接口完成，解析图片人脸信息，返回活体检测结果。

4.1.6 内存释放接口

• 方法

  void release()

• 参数

  无

• 返回

  无

• 说明

  主要针对模型的释放，以减少内存

4.2 人脸图像采集器

人脸图像采集器IDetectStrategy，检测图片中人脸信息，返回人脸检测状态，完成人脸图像采集。

4.2.1 设置人脸图像采集功能参数

• 方法

  void setDetectStrategyConfig(Rect previewRect, Rect detectRect,IDetectStrategyCallback callback)

• 参数

  previewRect 人脸图片大小，类型：Rect

  detectRect 人脸检测区域大小，类型：Rect

  callback 人脸图像采集功能状态监听器

• 返回

  无

• 说明

  设置人脸功能控制参数对象。

4.2.2 人脸图像采集

• 方法

  void detectStrategy(byte[] imageData)

• 参数

  imageData 图片信息

• 返回 无

• 说明

  检测图片中的人脸信息，完成人脸图像采集，返回检测状态和结果。

4.3 活体检测器

活体检测器LivenessStrategy，检测图片人脸信息，活体检测结果状态。

4.3.1 设置人脸功能控制参数

• 方法

  voidsetLivenessStrategyConfig(
  
       List<LivenessTypeEnum> livenessList, 
  
       Rect previewRect, 
  
       Rect detectRect, 
  
       ILivenessStrategyCallback callback);

• 参数

  livenessList 活体动作列表

  previewRect 人脸图片大小，类型：Rect

  detectRect 人脸检测区域大小，类型：Rect

  callback 人脸图像采集功能状态监听器

• 返回

  无

• 说明

  设置活体检测功能参数对象。

4.3.2 活体检测

• 方法

  void livenessStrategy(byte[] imageData);

• 参数

  imageData 图片信息

• 返回

  无

• 说明

  检测图片中的人脸信息，完成人脸图像采集和人脸活体检测，返回检测状态和结果。

4.4 人脸图像采集界面

人脸图像采集器界面FaceDetectActivity，包括UI界面，系统相机控制，使用人脸图像采集器IDetectStrategy处理相机采集到的图像。

4.5 活体检测界面

活体检测界面FaceLivenessActivity，包括UI界面，系统相机控制，使用活体检测器ILivenessStrategy处理相机采集到的图像，完成活体检测功能。

4.6 图片加密请求类

图片加密请求类SecRequest，里面的sendMessage方法是为了测试图片加密之后secBase64是否可以通过云端解密的一个示例代码

5、常见问题

（1）license文件有什么用，该放在什么地方？

license文件需要申请，目的是作为sdk校验开发者的使用合法性，license文件放置位置不对或未放置license文件会导致没法使用sdk，一般应先申请license文件，并把申请得到的license文件，放置在assets目录下面。

（2）FaceSDK-LicenseLICENSE_INFO_CHECK_ERROR =license id

licenseID为您申请时填appname+“_face_android”。如下图demo-turnstile-face-android为license里面的licenseID, demo-turnstile-face-android1为app运行时Config.licenseID，两者必须一致

（3）FaceSDK-LicenseLICENSE_INFO_CHECK_ERROR =signature md5

md5不一致错误，签名的为license里面的md5，后面的为app运行时获取的签名文件的md5，这两个md5必须一致且区分大小写。

（4）FaceSDK-License LICENSE_INFO_CHECK_ERROR =package name

PackageName不一致错误。License里面的packagename为申请license时填的，需要保证和app里面的packagename一致。

（5）活体检测常见有那些动作？是否可配置？

常见有7个动作，眨眼、张嘴、左摇头，右摇头，摇摇头、向上抬头，向下低头。 sdk提供FaceConfig参数设置类，如活体检测角度、光线，检测动作，检测动作数量等设置。

（6）使用sdk一般会用到活体检测拍照等功能，有什么需要注意？

Android 6.0+，需要注意相机拍摄权限问题。如没申请权限，可能导致没法调起相机。

（7）在有些机型上出现特别卡或出现无响应？

SDK在armeabi上性能非常差，建议删掉其他so只留下armeabi-v7a，包括使用的其他第三方so。因为如果其他so有armeabi，根据android系统查找so的逻辑，在armeabi的机型上只会去该目录下查找so，而人脸SDK没有，就会出现找不到so。

（8）license 文件失效了，不能用了怎么办？

license文件申请时候有期限，如过期会导致校验失效，需要在后台申请延期。