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

目录

11 简介	
2  1.1 功能介绍	
3  1.2 兼容性	
4  1.3 开发包说明	
52 集成指南	
6  2.1 Sample示例	
7  2.2 准备工作	
8    2.2.1 申请license
9    2.2.2 下载SDK	
10  2.3 运行示例工程	
11    2.3.1 运行自动配置授权信息的示例工程	
12    2.3.2 运行未配置授权信息的示例工程	
13  2.4添加SDK到工程	
14  2.5权限声明	
153 功能使用	
16  3.1 活体识别	
17  3.2人脸采集	
18  3.3质量校验设置	
19  3.4 界面定制说明	
20    3.4.1 修改faceplatform_ui界面	
214 接口设计说明	
22  4.1人脸功能管理器	
23    4.1.1 创建实例	
24    4.1.2人脸功能管理器初始化	
25    4.1.3设置人脸功能控制参数	
26    4.1.4取得人脸图像采集功能接口	
27    4.1.5取得活体检测功能接口	
28  4.2人脸图像采集器	
29    4.2.1设置人脸图像采集功能参数	
30    4.2.2人脸图像采集	
31  4.3活体检测器	
32    4.3.1设置人脸功能控制参数	
33    4.3.2活体检测	
34  4.4人脸图像采集界面
35  4.5 活体检测界面
365 常见问题	

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）初始化参数设置

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

1	     FaceConfig config = FaceSDKManager.getInstance()
2			.getFaceConfig();
3        // 设置可检测的最小人脸阈值
4        config.setMinFaceSize(FaceEnvironment.VALUE_MIN_FACE_SIZE);
5        // 设置可检测到人脸的阈值
6        config.setNotFaceValue(FaceEnvironment.VALUE_NOT_FACE_THRESHOLD);
7        // 设置模糊度阈值
8        config.setBlurnessValue(FaceEnvironment.VALUE_BLURNESS);
9        // 设置光照阈值（范围0-255）
10        config.setBrightnessValue(FaceEnvironment.VALUE_BRIGHTNESS);
11        // 设置遮挡阈值
12        config.setOcclusionValue(FaceEnvironment.VALUE_OCCLUSION);
13        // 设置人脸姿态角阈值
14        config.setHeadPitchValue(FaceEnvironment.VALUE_HEAD_PITCH);
15        config.setHeadYawValue(FaceEnvironment.VALUE_HEAD_YAW);
16        // 设置闭眼阈值
17        config.setEyeClosedValue(FaceEnvironment.VALUE_CLOSE_EYES);
18        // 设置图片缓存数量
19        config.setCacheImageNum(FaceEnvironment.VALUE_CACHE_IMAGE_NUM);
20        // 设置活体动作，通过设置list，LivenessTypeEunm.Eye, LivenessTypeEunm.Mouth,
21        // LivenessTypeEunm.HeadUp, LivenessTypeEunm.HeadDown, LivenessTypeEunm.HeadLeft,
22        // LivenessTypeEunm.HeadRight, LivenessTypeEunm.HeadLeftOrRight
23        config.setLivenessTypeList(ExampleApplication.livenessList);
24        // 设置动作活体是否随机
25        config.setLivenessRandom(ExampleApplication.isLivenessRandom);
26        // 设置开启提示音
27        config.setSound(ExampleApplication.isOpenSound);
28        // 原图缩放系数
29        config.setScale(FaceEnvironment.VALUE_SCALE);
30        // 抠图高的设定，为了保证好的抠图效果，我们要求高宽比是4：3，所以会在内部进行计算，只需要传入高即可
31        config.setCropHeight(FaceEnvironment.VALUE_CROP_HEIGHT);
32        // 加密类型，0：Base64加密，上传时image_sec传false；1：百度加密文件加密，上传时image_sec传true
33        config.setSecType(FaceEnvironment.VALUE_SEC_TYPE);
34        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创建实例

• 方法

  Plain Text 复制

  1FaceSDKManager getInstance()

• 参数

  无

• 返回

  人脸功能管理器

• 说明

  创建人脸功能管理器

4.1.2 人脸功能管理器初始化

• 方法

  Plain Text 复制

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

• 参数

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

• 返回

  无

• 说明

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

4.1.3 设置人脸功能控制参数

• 方法

  Plain Text 复制

  1void setFaceConfig(FaceConfig config)   

• 参数

  config 人脸功能控制参数对象

• 返回

  无

• 说明

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

  FaceConfig对象参数：

  光照阈值

  图像模糊阈值

  人脸遮挡阈值

  头部姿态角度

  最小人脸检测阈值

  人脸检测精度阈值

  截取人脸图片大小

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

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

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

• 方法

  Plain Text 复制

  1 IDetectStrategy getDetectStrategyModule()

• 参数

  无

• 返回

  人脸图像采集功能接口

• 说明

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

4.1.5 取得活体检测功能接口

• 方法
• Plain Text 复制

  1ILivenessStrategy getLivenessStrategyModule()

• 参数

  无

• 返回

  活体检测功能接口

• 说明

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

4.1.6 内存释放接口

• 方法

  Plain Text 复制

  1void release()

• 参数

  无

• 返回

  无

• 说明

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

4.2 人脸图像采集器

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

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

• 方法

  Plain Text 复制

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

• 参数

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

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

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

• 返回

  无

• 说明

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

4.2.2 人脸图像采集

• 方法

  Plain Text 复制

  1void detectStrategy(byte[] imageData)

• 参数

  imageData 图片信息

• 返回 无

• 说明

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

4.3 活体检测器

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

4.3.1 设置人脸功能控制参数

• 方法

  Plain Text 复制

  1voidsetLivenessStrategyConfig(
  2
  3     List<LivenessTypeEnum> livenessList, 
  4
  5     Rect previewRect, 
  6
  7     Rect detectRect, 
  8
  9     ILivenessStrategyCallback callback);

• 参数

  livenessList 活体动作列表

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

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

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

• 返回

  无

• 说明

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

4.3.2 活体检测

• 方法

  Plain Text 复制

  1void 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文件申请时候有期限，如过期会导致校验失效，需要在后台申请延期。