Android-方案集成指南

本文档介绍了金融级APP实名认证方案Android端APP集成开发流程。

一、运行示例工程

1、Demo运行

从控制台下载示例工程包之后，先将AndroidManifest.xml中的com.baidu.idl.face.demo.liantian.ac.provider修改为您的包名，build.gradle中的applicaitonId.liantian.ac.provider。然后在build.gradle中配置好包名和签名。

android {
    defaultConfig {
        ...
        applicationId "申请时的包名"
        ...
    }
    signingConfigs {
        def password = "替换为签名密码"
        def alias = "替换为签名别名"
        def filePath = "替换为签名文件路径"
        keyAlias alias
        keyPassword password
        storeFile file(filePath)
        storePassword(password)
    }
    release {
        keyAlias alias
        keyPassword password
        storeFile file(filePath)
        storePassword(password)
    }
}

2、SDK集成

首先在app工程中导入demo工程中的faceplatform-ui 模块、lib-liantian模块，ocr_ui模块（如果需要使用OCR身份证识别能力，则需要导入，不需要则不导入）。

在app工程的build.gradle中添加依赖，引入faceplatform-ui和ocr_ui依赖，然后sync。

dependencies {
   compile project(': faceplatform-ui)
   compile project(': ocr_ui)
}

3、授权文件、加密文件

请将创建App方案时获取的人脸授权文件(idl-license.face-android)、加密文件（idl-key.face-android）放置于Assets目录下。如果使用OCR身份证识别功能，请将OCR身份证识别授权文件（aip.license）也放置于Assets目录下。

二、安全人脸SDK接口

1、隐私协议接口

用户同意隐私协议之后调用此接口，在同意隐私协议前，所有人脸能力的调用均会失败，直到同意了隐私协议。

void LH.setAgreePolicy(Context context, boolean agree)

-参数说明

agree：用户是否同意了隐私协议，true为同意，false为不同意。

2、安全能力初始化接口

在开始采集人脸的流程前，调用安全能力初始化接口。请保证在调用此方法之前请确认setAgreePolicy方法已经调用，并且agress为true，否则采集流程将无法启动。

void LH.init(Context context, String licenseId);

-参数说明

licenseId：Face为App分配的许可Id，在AI开放平台创建App时获取。

3、人脸能力初始化接口

在开始采集人脸的流程前，调用人脸能力初始化接口。请保证在调用此方法之前LH.init方法已经调用。

FaceSDKManager.getInstance().initialize(mContext, Config.licenseID,
        Config.licenseFileName, new IInitCallback() {
            @Override
            public void initSuccess() {}

            @Override
            public void initFailure(final int errCode, final String errMsg) {
                runOnUiThread(new Runnable() {});
            }
        });

-参数说明：

licenseId：Face为App分配的许可Id，在AI开放平台创建App时获取。

licenseFileName：Face为App分配的授权文件名称，默认名称为idl-license.face-android。

new IInitCallback()：见“初始化IInitCallback回调接口”。

4、初始化IInitCallback回调接口

人脸能力初始化接口回调，错误码和错误信息如下表。

5、人脸配置

设置配置参数，如不设置，将使用默认值。

人脸配置通过console平台下发，可以参考demo工程assets目录下的console_config.json文件，相关配置代码参考demo的app模块。

FaceConfig config = FaceSDKManager.getInstance().getFaceConfig();
FaceSDKManager.getInstance().setFaceConfig(config);

6、人脸采集流程（SurfaceView实现）

该方法是异步方法，调用后执行炫彩活体采集流程，该流程需要一个在界面显示的SurfaceView实现。可以参考demo的faceplatform-ui模块。

boolean LH.startFaceSurfaceLiveness(Activity activity,SurfaceHolder previewSurfaceHolder, FaceProcessCallback callback, int deviceCheckTimeout)

-参数说明：

activity：执行人脸采集的Activity。

previewSurfaceHolder：用于展示摄像头预览的SurfaceView的Holder。

processCallback：流程回调，见“FaceProcessCallback接口”。

deviceCheckTimeout：安全检测超时时间，此处需要传0，开启后台检测，传-1则跳过检测。

-返回值说明：

若本方法返回false，则流程启动失败，此时传入的callback对象的onEnd方法会回调失败原因。

7、人脸采集流程（TextureView实现）

该方法是异步方法，调用后执行炫彩活体采集流程，该流程需要一个在界面显示的TextureView实现。可以参考demo的faceplatform-ui模块。

boolean LH. startFaceTextureLiveness(Activity activity,                                               TextureView previewTextureView, FaceProcessCallback callback, int deviceCheckTimeout, IFaceProcessInfo info, boolean record)

-参数说明：

activity：执行人脸采集的Activity。

TextureView：用于展示摄像头预览的TextureView。

processCallback：流程回调，见“采集回调FaceProcessCallback接口”。

deviceCheckTimeout：安全检测超时时间，此处需要传0，开启后台检测，传-1则跳过检测。

record：是否进行视频录制，若否，则onEnd返回的RequestInfo中path为null，若是，该path字段为加密视频文件的路径。注意，本SDK不负责删除该文件，请在使用后删除该加密视频文件，以免硬盘被过度占用。

-返回值说明：

若本方法返回false，则流程启动失败，此时传入的callback对象的onEnd方法会回调失败原因。

8、采集回调FaceProcessCallback接口

回调类，回调方法顺序随人脸采集流程自上向下：

（1）onDeviceCheckResult (int status)

回调设备风险检测结果。无风险或未知风险会进入人脸采集流程，若有风险，则不会进行人脸采集流程。此回调方法return后，会直接回调onEnd方法。

status：1代表无风险，-1代表有风险。

（2）回调人脸采集过程的阶段性结果，供APP刷新界面。

status：按FaceStatusNewEnum的枚举值返回的当前状态。

message：需要在界面展示的提示。

livenessScore：活体检测分数。

onCollectCompletion(FaceStatusNewEnum status, String message,                         HashMap<String, ImageInfo> base64ImageCropMap, HashMap<String, ImageInfo> base64ImageSrcMap,int currentLivenessCount，float livenessScore);

（3）onEnd (int status，RequestInfo info)

必有，包括被Cancel的情况，回调流程结束事件。

status：1代表正常结束， <0的值均表示未正常结束。

info：只有在正常结束时有值，其他情况为null。本对象包含sKey，xDeviceId，data和path共4个字段。其中，sKey， xDeviceId为校验用，data为安全相关数据（该数据包含采集的最终图像，以及解密视频文件的必要信息），path为最终加密后的视频文件（仅在Texture实现的活体采集流程，开启录像功能时有值）。请按需使用这些数据。

onEnd的部分status值列举如下：

9、取消正在进行的流程

取消正在进行的人脸采集流程。调用此接口后，取消整个流程。请在Activity的onPause中调用此方法，保证界面离开顶端时流程被取消。下次进入界面应当重新开始人脸验证过程，可以参考demo的faceplatform-ui模块。

void LH.cancelFaceProcess()

10、采集过程中设置语音开关

设置是否开启人脸采集过程的语音提示。只有采集过程中可以通过此方法开启或关闭语音提示。采集前调用此方法不会生效。可以参考demo的faceplatform-ui模块。

void LH.setSoundEnable (boolean enable)

11、OCR身份证初始化

如果需要使用OCR身份证能力，需要对OCR能力进行初始化。可以参考demo的app模块。

OCR.getInstance(this).initAccessToken(new OnResultListener<AccessToken>() {
    @Override
    public void onResult(final AccessToken result) {
    }

    @Override
    public void onError(final OCRError error) {
    }
}, getApplicationContext());

12、OCR身份证在线识别

调用recognizeIDCard进行身份证在线识别，可参考demo的ocr_ui模块。

OCR.getInstance(this).recognizeIDCard(param, new OnResultListener<IDCardResult>() {
    @Override
    public void onResult(final IDCardResult result) {}
    
    @Override
    public void onError(final OCRError error) {}
});

三、采集流程

1、正常采集流程

调用startFaceSurfaceLiveness或startFaceTextureLiveness -> onBegin被回调 -> 设备环境扫描 -> onDeviceCheckResult被回调-> onBeginCollectFaceInfo被回调 -> 开启摄像头（需要保证SurfaceView或TextureView为可见状态） -> onConfigCamera被回调，用户配置摄像头 -> 开始预览 -> onCollectCompletion被回调（多次，需要更新界面，最后一次回调status为OK或DetectRemindCodeTimeout）-> onBeginBuildData 被回调 -> onEnd被回调。

2、异常采集流程

onEnd可能在onBegin后的任何时间被回调，其他中间步骤可能会缺失。此种情况下，onEnd会回调错误码。

四、代码混淆

-keep class com.baidu.idl.* { ; }

-dontwarn com.baidu.vis.**

-keep class com.baidu.vis.* { ; }

-dontwarn com.baidu.liantian.**

-keep class com.baidu.sofire.* { ; }

-dontwarn com.baidu.baidusec.**

-keep class com.baidu.baidusec.* { ; }

-dontwarn com.baidu.ocr.**

-keep class com.baidu.ocr.* { ; }

五、注意事项

1、如果之前接入过百度人证核验SDK，如何升级？

删除faceplatform模块和faceplatform-ui模块，然后重新导入demo工程中的faceplatform-ui模块、lib-liantian模块，ocr_ui模块（如果需要使用OCR身份证识别能力，则需要导入），可以参考新版本demo。

2、demo配置完签名和包名之后，运行报错

Manifest merger failed : Attribute provider#com.baidu.liantian.LiantianProvider@authorities value=(com.baidu.idl.face.demo.liantian.ac.provider) from AndroidManifest.xml

将com.baidu.idl.face.demo.liantian.ac.provider修改为您的包名(build.gradle中的applicaitonId).liantian.ac.provider

3、人脸能力初始化的时候，报错初始化失败 = 13 -->local auth failed:6

请确认是否使用了AI开放平台控制台配置的包名、以及签名文件。

4、采集回调FaceProcessCallback接口onEnd方法返回-15，如何处理？

可以在进入人脸界面之前，通过FH.isInitSuc(1)来判断安全模块是否下载成功，如果没有下载成功，建议用户切换网络后尝试。

5、不使用视频录制，如何操作？

视频录制会将活体动作视频的留存在本地，如果使用此视频需要上传到服务端解密。如果不使用直接跳转到不到视频录制的界面即可。

6、如果不想使用OCR身份证识别能力，怎么操作？

不使用OCR身份证识别能力，不需要导入ocr_ui模块，也不需要对OCR能力进行初始化，不需要向工程中放置OCR识别的授权文件。

7、OCR身份证识别初始化的时候，报错初始化失败 = [283502] App identifier unmatch

请确认是否使用了控制台创建应用时配置的文字识别包名、以及签名文件。

8、通过客户端demo如何进行人脸对比/人证核验/在线活体？

因为客户端demo需要配合服务端demo使用，app客户端通过人脸SDK采集人脸数据后，上传app服务端，app服务端通过ak、sk请求百度服务器，返回结果。人脸对比/人证核验/在线活体接口请前往方案集成前准备下载服务端示例工程及文档。