金融级实人认证服务提供Android客户端SDK,帮助您在业务应用(App)中实现刷脸认证功能。本文结合示例代码介绍Android客户端的接入流程。
使用限制
Android SDK使用限制如下:
不支持模拟器模式调试。
仅支持Android 4.4及以上系统版本的移动智能设备(手机或Pad)接入。
权限说明
Android SDK权限说明如下:
权限 | 是否必须 | 说明 |
android.permission.INTERNET | 是 | 联网权限。Android SDK需要联网才能使用。 |
android.permission.ACCESS_NETWORK_STATE | 是 | |
android.permission.CAMERA | 是 | 摄像头权限。该权限在Android 6.0及以上版本属于动态权限。 |
根据相关合规要求,获取用户设备敏感权限需要同步告知权限申请目的。您可以通过合规权限提醒完成相应配置。
依赖配置
下载Android SDK,该SDK为Android标准AAR包。
下载完毕之后解压,将Android SDK文件夹中的所有aar文件拷贝到主工程模块下的libs目录中(具体以工程实际配置为准),并在模块对应的build.gradle文件中添加如下依赖:
// 阿里云实人认证服务SDK AAR,fileTree 方式依赖指定目录
implementation(fileTree(dir: "libs", includes: ["*.aar"]))
// 阿里云实人认证服务三方依赖库,不能省略
implementation 'com.squareup.okhttp3:okhttp:3.11.0'
implementation 'com.squareup.okio:okio:1.14.0'
implementation 'com.alibaba:fastjson:1.2.83_noneautotype'
接口说明
Android SDK包含初始化SDK(install)、获取MetaInfos(getMetaInfos)和开始认证(verify)3个接口。
初始化SDK
描述:调用该函数完成SDK内部初始化。请务必做延迟初始化配置,确保在用户同意《隐私权政策》后,在人脸识别业务场景中初始化SDK。
函数原型:
public static void install(Context context);
IPv6网络初始化,示例代码如下:
public static int installIPv6(Context context)
参数说明:
名称
类型
说明
context
Context
当前Application的context。
返回值:无。
获取MetaInfos
描述:移动端环境信息发送至业务服务器端,业务服务器端将这些信息作为参数之一(MetaInfos)调用服务端初始化认证接口(InitFaceVerify),从而获取CertifyId,用于后续认证环节。
函数原型:
public static String getMetaInfos(Context context);
参数说明:
名称
类型
说明
context
Context
当前Application的context。
返回值:String类型,以JSON格式返回当前移动设备端的环境信息。返回值示例如下:
{ "apdidToken": "xxxx", "appName": "com.aliyun.facedemo", "appVersion": "1.2.8", "bioMetaInfo": "6.7.0:21478612992,0", "deviceModel": "Mi 10", "deviceType": "android", "osVersion": "12", "sdkVersion": "2.1.0", "securityVersion": "2", "voiceSdkVersion": "1.0.0", "zimVer": "1.0.0" }
开始认证
描述:调用该函数发起实人认证。
函数原型:
public void verify(final String certifyId, boolean useMsgBox, HashMap<String, String> extParams, ZIMCallback callback);
参数说明:
参数
类型
说明
certifyId
String
从服务端初始化认证接口(InitFaceVerify)获取的CertifyId。
说明每个CertifyId只能调用一次verify函数,每次调用verify函数之前务必重新获取CertifyId。
useMsgBox
boolean
当刷脸认证过程中出现异常情况,是否使用SDK内部的弹框提示。取值:
true:SDK先弹框提示,确定之后,返回错误code。
false:不弹提示框,直接返回错误code,客户业务应用App自行决定如何提示。
extParams
HashMap<String, String>
用户自定义参数,一般直接传NULL即可。目前支持的自定义字段,extParams取值,详情请参见extParams取值说明。
callback
ZIMCallback
认证结果的回调接口,定义如下:
public interface ZIMCallback { boolean response(ZIMResponse response); }
ZIMResponse类的定义,详情请参见下文认证结果及错误码。
表 1. extParams取值说明
取值
说明
示例值
ext_params_key_use_video
是否返回活体认证视频。取值:
true:可在response.videoFilePath或在服务端查询接口获取视频本地路径。
false:不返回活体认证视频(默认)。
false
ext_params_key_screen_orientation
认证界面UI朝向。取值:
ext_params_val_screen_port:竖屏(默认)。
ext_params_val_screen_land:横屏。
ext_params_val_screen_land
ext_params_key_face_progress_color
活体检测页面的进度条颜色。
#FF0000
ext_params_key_ocr_bottom_button_color
OCR识别结果确认页底部按钮颜色。
#FF0000
返回值:无。
认证结果及错误码
认证结果通过ZIMResponse类返回,定义如下:
public class ZIMResponse {
/**
* 返回结果编码
*/
public int code;
/**
* 返回结果原因信息
*/
public String reason;
// ......
}
错误码 | 是否计费 | 错误码文案 | 错误码描述 |
1000 | 是 | 刷脸成功 | 用户完成了刷脸过程,认证建议结果为通过。该结果仅供参考,可通过调用服务端DescribeFaceVerify接口获取最终认证结果。 |
1001 | 否 | 系统错误 | 表示系统错误。 |
1003 | 否 | 验证中断 | 表示验证中断。 |
2002 | 否 | 网络错误 | 表示网络错误。 |
2003 | 否 | 客户端设备时间错误 | 表示客户端设备时间错误。 |
2006 | 是 | 刷脸失败 | 用户完成了刷脸过程,认证建议结果为未通过。该结果仅供参考,可通过调用服务端DescribeFaceVerify接口获取最终认证结果以及未通过的详细原因。 |
更多错误码信息,请参见金融级Android客户端错误码详情。
接口混淆配置
为避免接口被混淆而造成功能异常,您需要在App工程的proguard-rules.pro文件中添加如下配置信息:
# 必须要依赖到应用混淆中
-keepclassmembers,allowobfuscation class * {
@com.alibaba.fastjson.annotation.JSONField <fields>;
}
-keep class net.security.device.api.** {*;}
-keep class face.security.device.api.** {*;}
-keep class com.alipay.deviceid.** { *; }
-keep class org.json.** { *;}
-keep class com.alibaba.fastjson.** {*;}
# SDK混淆配置
-keep class com.alipay.face.api.** {*;}
-keep class com.alipay.zoloz.toyger.**{*;}
-keep class com.dtf.face.api.** {*;}
-keep class com.dtf.face.ocr.verify.DTFOcrFacade { *; }
-keep class com.dtf.face.verify.** {*;}
-keep class com.dtf.face.network.model.** {*;}
-keep class com.dtf.face.network.APICallback {*;}
-keep class com.dtf.face.config.**{*;}
-keep class com.dtf.face.log.** {*;}
-keep class com.dtf.face.ui.overlay.** {*;}
-keep class com.dtf.face.ui.widget.ToygerWebView {*;}
-keep class com.dtf.face.utils.ClientConfigUtil{
boolean needUploadPreviewTrace*();
boolean needVideoExDegrade*();
boolean isCfgVideoExDevice*();
}
-keep class com.dtf.toyger.base.** {*;}
-keep class com.dtf.face.network.mpass.biz.model.** { *; }
-keep class com.dtf.face.utils.LogUtils { *; }
-keep class com.dtf.wish.api.** { *; }
-keep class com.dtf.wish.ui.** { *; }
-keep class com.dtf.wish.ui.WishFragment{*;}
-keep class com.dtf.voice.api.** { *; }
-keep class xnn.* { *; }
-keep class facadeverify.** { *; }
-keep class baseverify.** { *; }
-keep class faceverify.** { *; }
-keep class ocrverify.** { *; }
-keep class wishverify.** { *; }
# R8编译混淆配置
-keep class com.dtf.face.ui.toyger.FaceLoadingFragment{ *; }
-keep class com.dtf.face.ui.toyger.FaceShowFragment{*;}
-keep class com.dtf.face.ui.toyger.FaceShowElderlyFragment{*;}
-keepclassmembers class com.dtf.face.camera.ICameraCallback{
void onPreviewFrame*(*);
}
# NFC编译配置
-keep class com.dtf.face.nfc.verify.DTFNfcFacade { *; }
-keep class com.eidlink.**{*;}
-keep class net.sf.**{*;}
-keep class org.**{*;}
-keep class cn.**{*;}
-keep class com.froad.**{*;}
-keep class com.huawei.**{*;}
-keep class com.eidlink.**{*;}
-keep class org.ejbca.cvc.**{*;}
-keep class org.jmrtd.**{*;}
-keep public class com.netease.nis.sdkwrapper.Utils {public <methods>;}
-keep class net.sf.scuba.**{*;}
-keep class org.eid_bc.bouncycastle.jcajce.provider.symmetric.**{*;}
示例代码
public class MainActivity extends Activity {
private String certifyId = "xxx";
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
Context ctx = getApplicationContext();
// 初始化SDK
ZIMFacade.install(ctx);
// 获取MetaInfos
String metaInfos = ZIMFacade.getMetaInfos(ctx);
// 将MetaInfos发送到App服务器端,调用云端InitFaceVerify接口获取CertifyId。
// certifyId = getCertifyIdFromServer(metaInfo); // 需客户自己实现
HashMap<String, String> params = new HashMap<>();
// extParams取值示例
params.put("ext_params_key_use_video", "false");
// 开始验证
ZIMFacade zimFacade = ZIMFacadeBuilder.create(ctx);
zimFacade.verify(certifyId, true, params, new ZIMCallback() {
@Override
public boolean response(ZIMResponse response) {
switch (response.code) {
case 1000:
Log.d("AliyunFace", "认证成功");
break;
case 1001:
Log.e("AliyunFace", "系统错误");
break;
case 1003:
Log.e("AliyunFace", "验证中断");
break;
case 2002:
Log.e("AliyunFace", "网络错误");
break;
case 2003:
Log.e("AliyunFace", "客户端设备时间错误");
break;
case 2006:
Log.e("AliyunFace", "刷脸失败");
break;
default:
Log.e("AliyunFace", "未知错误");
break;
}
return true;
}
});
}
}
Demo代码包
您可以下载Android Demo代码包进行体验。
SDK包大小裁剪说明
更多说明,请参见SDK包裁剪说明。