ID Verification提供Android客户端SDK,帮助您在业务应用(App)中实现eKYC远程身份验证功能。您可通过服务端认证初始化接口,获取唯一标识transactionId,并使用transactionId唤起客户端SDK。本文结合示例代码介绍Android客户端的接入流程。
使用限制
仅支持Android 4.3及以上系统版本的移动智能设备(手机或iPad)接入。不支持x86架构。
权限说明
为提升安全效果,当前SDK需要以下权限:
权限 | 是否必须 | 说明 |
android.permission.INTERNET | 是 | 联网权限。Android SDK需要联网才能使用。 |
android.permission.ACCESS_NETWORK_STATE | 否(推荐开启) | |
android.permission.CAMERA | 是 | 摄像头权限。该权限在Android 6.0及以上版本属于动态权限。 |
android.permission.READ_PHONE_STATE | 否(推荐开启) | |
android.permission.READ_EXTERNAL_STORAGE | 否(推荐开启) |
SDK下载和配置
下载Android SDK,该SDK为Android标准aar包。
下载完毕之后解压,将Android SDK文件夹中的所有aar文件拷贝到工程下的libs目录中,并在工程的build.gradle文件中添加如下依赖。
// SDK modules implementation files('libs/aliyun-identityplatform-xxx.aar') implementation files('libs/aliyun-identityface-xxx.aar') implementation files('libs/aliyun-identitycrypto-xxx.aar') implementation files('libs/aliyun-identityocr-xxx.aar') implementation files('libs/tygerservice-xxx.aar') implementation files('libs/Android-AliyunFaceGuard-xxx.aar') // SDK third-party dependency modules implementation 'androidx.appcompat:appcompat:1.1.0' implementation 'com.squareup.okhttp3:okhttp:3.11.0' implementation 'com.squareup.okio:okio:2.2.2' implementation 'com.aliyun.dpa:oss-android-sdk:2.9.4' implementation 'com.alibaba:fastjson:1.1.72.android'
说明上述依赖中,xxx代表SDK的具体版本号。
使用中不能缺少三方依赖库,否则会导致SDK功能异常。
接口说明
Android SDK包含初始化SDK(install)、获取MetaInfo(getMetaInfo)和开始认证(verify)接口。
初始化SDK(install)
函数原型:
public void install(Context context);
参数说明:
名称
类型
说明
context
Context
当前Application的context。
返回值:无。
获取MetaInfo (getMetaInfo)
函数原型:
public static String getMetaInfo(Context context);
参数说明:
名称
类型
说明
context
Context
当前Application的context。
返回值:
String类型,以JSON格式返回当前移动设备端的环境信息。返回值示例如下:
{
"apdidToken": "",
"appName": "com.aliyun.identity.platform",
"appVersion": "1.0.1",
"bioMetaInfo": "5.1.0:11501568,4",
"deviceBrand": "xxx",
"deviceManufacturer": "xxx",
"deviceModel": "xxx",
"deviceType": "android",
"identityVer": "1.0.0",
"osVersion": "10",
"sdkVersion": "1.0.9"
}
开始认证(verify)
函数原型:
public void verify(String transactionId, Map<String, String> extParams, IdentityCallback callback);
参数说明:
名称
类型
说明
transactionId
String
从服务端初始化认证接口(Initialize)获取的transactionId。
说明每个transactionId只能调用一次verify函数,每次调用verify函数之前务必重新获取transactionId。
extParams
Map<String, String>
扩展参数,通常情况下传null即可。目前支持的自定义字段,extParams取值,请参见extParams配置说明。
callback
IdentityCallback
认证结果的回调接口。回调格式如下:
public class IdentityResponse { // See the description of "Return Code". public int code; // Result code description. public String message; } public interface IdentityCallback { boolean response(IdentityResponse response); }
extParams配置说明:
Key名
说明
示例(String类型)
IdentityParams.OcrResultButtonColor
OCR识别结果页面的底部按钮颜色。
#FF0000
IdentityParams.RoundProgressColor
扫脸时的圆圈颜色。
#FF0000
IdentityParams.ShowBlbumIcon
证件OCR识别环节,是否展示相册上传入口:
1:展示(默认)
0:不展示
1
IdentityParams.ShowOcrResult
证件OCR识别环节,是否展示识别结果页:
1:展示(默认)
0:不展示
1
IdentityParams.MaxErrorTimes
重试次数上限。
可设置范围为3~10次,默认10次。
10
IdentityParams.CardOcrTimeOutPeriod
OCR识别环节超时时长。
可设置范围为20~60秒,默认20秒。
20
IdentityParams.FaceVerifyTimeOutPeriod
活体采集检测环节超时时长。
可设置范围为20~60秒,默认20秒。
20
IdentityParams.OcrResultTimeOutPeriod
OCR识别结果页面可编辑时长。
可自定义配置,默认不限。
60
IdentityParams.SdkLanguage
SDK默认支持的多语言语种如下:
zh-Hans:中文简体
zh-Hant:中文繁体
en:英文
ja:日文
ko:韩文
id:印尼语
ms:马来语
th:泰语
vi:越南语
说明除上述默认支持的语言外,SDK还支持客户自定义语言,请参见新增语言。
zh-Hans
CloseButtonLayout
关闭按钮的布局:
left:左侧(默认)
right:右侧
left
返回值:无。
新增语言
新增自定义语言,则需要执行以下操作实现:
打开App应用工程(集成ID Verification SDK的module)。
在应用工程下创建目标语言文件夹及 string.xml 语言资源文件。以新增俄罗斯语言为例,在主module工程下面新建俄罗斯语言的values文件夹,将string.xml添加到对应的语言文件夹下面,其他语言同理。
将string.xml文件中的value内容自行翻译成对应的语言。可参考附录1中的模板,将中文修改成目标语言。
在代码中指定自定义的目标语言,格式:“language-country”。如下示例代码以设置俄罗斯语为例:
错误码说明
错误码 | 是否计费 | 结果码描述 |
1000 | 是 | 用户完成了刷脸过程,认证建议结果为通过。该结果仅供参考,可通过调用服务端CheckResult接口获取最终认证结果,并进行下一步处理。 |
1001 | 是 | 用户完成了刷脸过程,认证建议结果为未通过。该结果仅供参考,可通过调用服务端CheckResult接口获取最终认证结果、未通过的详细原因,并进行下一步处理。 |
1002 | 否 | 系统错误。 |
1003 | 否 | SDK初始化失败,请确认客户端时间是否正确。 |
1004 | 否 | 相机权限错误。请参考以下步骤尝试解决:
|
1005 | 否 | 网络错误。 |
1006 | 否 | 用户退出。 |
1007 | 否 | TransactionId无效. |
1009 | 否 | 客户端时间戳错误。 |
1011 | 否 | 提交证件类型错误。 |
1012 | 否 | 识别出的证件关键信息缺失或格式校验失败。 |
1013 | 否 | 图片质量不佳。 |
1014 | 否 | 错误次数超出上限。 |
1015 | 否 | 安卓系统版本过低。 |
1016 | 否 | 未获取到相机权限。 |
示例代码
public class MainActivity extends AppCompatActivity {
private String transactionId = "";
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
// 初始化SDK
IdentityPlatform.getInstance().install(MainActivity.this);
// 获取MetaInfo
String metaInfo = IdentityPlatform.getMetaInfo(MainActivity.this);
/**
* 将MetaInfo发送到App服务器端,调用云端Initialize接口获取transactionId
*/
// transactionId = getTransactionIdFromServer(metaInfo);
// 设置SDK语言
Map<String, String> extParams = new HashMap<>();
extParams.put(IdentityParams.SdkLanguage, "en");
// 开始认证
IdentityPlatform.getInstance().verify(transactionId, extParams,
new IdentityCallback() {
@Override
public boolean response(final IdentityResponse response) {
if (IdentityResponseCode.IDENTITY_SUCCESS == response.code) {
Toast.makeText(MainActivity.this,
"Verification passed", Toast.LENGTH_LONG).show();
} else {
Toast.makeText(MainActivity.this,
"Verification failed([" + response.code + "]" +
response.message + ")",
Toast.LENGTH_LONG).show();
}
return true;
}
});
}
}
混淆配置
-verbose
-keep class com.aliyun.identity.platform.api.** {*;}
-keep class com.aliyun.identity.IdentityUtils {*;}
-keep class com.aliyun.identity.ocr.IdentityOcrApi {*;}
-keep class com.aliyun.identity.platform.model.** {*;}
-keep class com.aliyun.identity.platform.config.** {*;}
-keep class com.aliyun.identity.face.IdentityFaceApi {*;}
-keep class com.face.verify.intl.** {*;}
-keep class com.alibaba.fastjson.** {*;}
-keep class net.security.device.api.** {*;}
-keep class face.security.device.api.** {*;}
-keep class com.dtf.toyger.** {*;}
Demo代码包
您可以下载Android Demo进行体验。
附录1
<string name="identity_aliyun_no_face">没有检测到脸</string>
<string name="identity_aliyun_distance_too_far">靠近一点</string>
<string name="identity_aliyun_distance_too_close">离远一点</string>
<string name="identity_aliyun_face_not_in_center">把脸移入圈内</string>
<string name="identity_aliyun_bad_pitch">请正对手机</string>
<string name="identity_aliyun_bad_yaw">请正对手机</string>
<string name="identity_aliyun_is_moving">再清晰一点</string>
<string name="identity_aliyun_bad_brightness">脸部亮一点</string>
<string name="identity_aliyun_bad_quality">请调整姿势</string>
<string name="identity_aliyun_bad_eye_openness">请正对手机</string>
<string name="identity_aliyun_blink_openness">请眨一眨眼</string>
<string name="identity_aliyun_stack_time">请保持不动</string>
<string name="identity_aliyun_is_blur">再清晰一点</string>
<string name="identity_aliyun_face_init_text">请正对屏幕</string>
<string name="identity_aliyun_face_comm_tips_text">拿起手机,眨一眨眼</string>
<string name="identity_aliyun_zface_processing">正在处理</string>
<string name="identity_message_box_title_not_support">当前系统不支持刷脸</string>
<string name="identity_message_box_message_not_support">刷脸仅在高版本及以上系统可用</string>
<string name="identity_message_box_title_no_camera_permission">权限不足</string>
<string name="identity_message_box_message_no_camera_permission">请确保已经赋予App摄像头权限</string>
<string name="identity_message_box_title_operation_time_out">操作超时</string>
<string name="identity_message_box_title_network">网络不给力</string>
<string name="identity_message_box_message_network">请检查网络</string>
<string name="identity_message_box_title_sys_error">本次操作失败</string>
<string name="identity_message_box_message_sys_error">抱歉,系统出错了,请再试一次</string>
<string name="identity_message_box_title_exit_tip">确定退出吗?</string>
<string name="identity_message_box_message_exit_tip">露个脸就能通过</string>
<string name="identity_message_box_btn_ok_tip">确定</string>
<string name="identity_message_box_btn_cancel_tip">取消</string>
<string name="identity_message_box_title_retry_face_scan">操作超时</string>
<string name="identity_message_box_message_retry_face_scan">正对手机,更容易成功</string>
<string name="identity_message_box_btn_retry_ok">再试一次</string>
<string name="identity_message_box_title_retry_face_scan_time_out">本次操作失败</string>
<string name="identity_message_box_message_retry_face_scan_time_out">刷脸失败次数过多,请稍后再试</string>
<string name="identity_message_box_message_btn_retry_ok_time_out">我知道了</string>
<string name="identity_ocr_alert_net_message_error">网络不给力,请重试</string>
<string name="identity_ocr_alert_retry_text">重试</string>
<string name="identity_ocr_alert_exit_text">退出</string>
<string name="identity_final_handleing">认证中...</string>
附录2
Android语言码
提供Android的部分语言码,供参考。
自定义语言 | xml文件命名 | 语言码 |
|
|
|