金融级实人认证服务提供Android客户端SDK,帮助您在业务应用(App)中实现刷脸认证功能。您可以通过应用服务端认证初始化接口,向阿里云服务器调用发起认证请求接口并获取刷脸认证的唯一标识CertifyId,然后使用CertifyId唤起刷脸认证客户端SDK。本文结合示例代码介绍Android客户端的接入流程。

使用限制

金融级实人认证服务Android客户端SDK具有以下使用限制。

  • 不支持模拟器模式调试。
  • 仅支持Android 4.4及以上系统版本的移动智能设备(手机或Pad)接入。

依赖配置

下载金融级实人认证Android SDK。该SDK为Android标准AAR包。下载后,在Android Studio中进行AAR包引用。

例如,您可在完成AAR包下载后,将其放入工程目录的libs目录,并添加以下依赖:

#阿里云实人认证SDK
implementation files('libs/android-aliyunbasicstl-sdk-release-xxx.aar')
implementation files('libs/android-aliyuncomm-sdk-release-xxx.aar')
implementation files('libs/Android-AliyunDevice-xxx.aar')
implementation files('libs/android-aliyunface-sdk-release-xxx.aar')
implementation files('libs/android-aliyunocr-sdk-release-xxx.aar')
implementation files('libs/APSecuritySDK-DeepSec-xxx.aar')
implementation files('libs/photinus-xxx.aar')
implementation files('libs/tygerservice-xxx.aar')

#三方依赖库
implementation 'com.squareup.okhttp3:okhttp:3.11.0'
implementation 'com.squareup.okio:okio:1.14.0'
implementation 'com.alibaba:fastjson:1.2.62'
implementation 'com.aliyun.dpa:oss-android-sdk:+'
说明 以上代码示例中xxx表示版本号,使用过程中,请替换为SDK包中文件的实际版本号。

接口定义

/**
 * 刷脸认证接口。
 */
public class ZIMFacade {

    /**
     * 初始化接口,建议接入方在调用其它接口前,先调用此接口。
     * 
     * @context Context
     */
    public static void install(Context context);

    /**
     * 获取环境参数接口。
     * 
     * @context Context
     */
    public static String getMetaInfos(Context context);

    /**
     * identify interface for android
     * 需在UI线程上调用,不会阻塞调用线程。
     *
     * @param certifyId:刷脸认证唯一标识,请从刷脸认证服务端认证初始化接口获取。
     * @param useMsgBox:当刷脸认证过程中出现异常情况,是否使用SDK内部的弹框提示。
     *                    如果取值为true,则SDK先弹框提示,确定之后,返回错误码。
     *                    如果取值为false,则不弹提示框,直接返回错误码,客户App自行决定如何提示。
     * @param callback:认证结果的回调接口。
     */
    public void verify(String certifyId, boolean useMsgBox,, ZIMCallback callback);

    /**
     * 开始进行实名认证,带自定义参数的版本。
     * @param certifyId:刷脸认证唯一标识,请从刷脸认证服务端认证初始化接口获取。
     * @param useMsgBox:表示是否在SDK内部使用弹框提示错误信息。
     * @param extParams:扩展参数。
     * @param callback:identify result
     */
    public void verify(final String zimId, boolean useMsgBox, HashMap<String, String> extParams, ZIMCallback callback);
}

接口调用

  1. 初始化SDK。
    为了提升身份核验的用户体验,并为刷脸认证准备必要的数据,Android客户端需要进行SDK初始化。初始化的代码示例如下:
    ZIMFacade.install(context);
  2. 获取MetaInfo数据。
    您在调用刷脸认证服务端发起认证请求时,需要传入该MetaInfo值。代码示例如下:
    
    String metaInfos = ZIMFacade.getMetaInfos(context);
  3. 开始认证。
    Android客户端接入支持两种接入场景:手机端接入和手机端+Pad端接入。您可以根据自身业务需要选择接入的场景。两种接入场景的示例代码如下。
    • 手机端接入场景(自定义参数设置请参考Pad端接入场景设置)
      ZIMFacade zimFacade = ZIMFacadeBuilder.create(MainActivity.this);
      zimFacade.verify(certifyId, true, new ZIMCallback() {
       @Override
       public boolean response(ZIMResponse response) {
           // TODO:根据实人认证回调结果处理自身的业务。
           if (null != response && 1000 == response.code) {
               // 认证成功。
           } else {
               // 认证失败。
           }
           return true;
       }
      }
    • 手机端+Pad端接入场景(支持自定义参数)
      说明 金融级实人认证支持设置返回活体检测的视频,默认设置为不返回。如果设置为返回,在您使用金融级实人认证SDK完成认证(不区分认证结果为FT),并在SDK回调时和查询接口返回视频路径,请您及时处理。
      ZIMFacade zimFacade = ZIMFacadeBuilder.create(MainActivity.this);
      
      HashMap<String, String> extParams = new HashMap<>();
      //如需指定活体检测UI界面方向(横屏+竖屏),请指定这一项。
      extParams.put(ZIMFacade.ZIM_EXT_PARAMS_KEY_SCREEN_ORIENTATION, ZIMFacade.ZIM_EXT_PARAMS_VAL_SCREEN_LAND); 
      //如需支持活体视频返回,请指定这一项,并在response.videoFilePath或在服务端查询接口获取视频本地路径。
      extParams.put(ZIMFacade.ZIM_EXT_PARAMS_KEY_USE_VIDEO, ZIMFacade.ZIM_EXT_PARAMS_VAL_USE_VIDEO_TRUE);  
      
      //如需设置OCR的“下一步“按钮颜色(默认可不设置),请设置此项,如红色#FF0000。
      extParams.put(ZIMFacade.ZIM_EXT_PARAMS_KEY_OCR_BOTTOM_BUTTON_COLOR, "#FF0000");
      //如需自定义活体检测页面的进度条颜色(默认可不设置),请设置此项,如红色#FF0000。
      extParams.put(ZIMFacade.ZIM_EXT_PARAMS_KEY_FACE_PROGRESS_COLOR, "#FF0000");
      zimFacade.verify(certifyId, true, extParams, new ZIMCallback() {
          @Override
          public boolean response(final ZIMResponse response) {
              if (1000 == response.code) {
                  showMessageBox("认证通过");
              } else {
                  showMessageBox("认证失败([" + response.code + "]" + response.reason + ")");
              }
      
              return true;
          }
      });
      说明
      • certifyId:刷脸认证唯一标识,可从刷脸认证服务端发起认证请求获取。
      • ZIMCallback的response回调需要有返回值,默认为true
  4. 返回刷脸认证回调结果。
    刷脸认SDK回调结果中的ZIMResponse类,该类中定义了对应的结果编码和原因。代码示例如下:
    /**
     * 刷脸认证回调结果。
     */
    public class ZIMResponse {
        /**
         * 返回结果编码。
         */
        public int code;
        /**
         * 返回结果原因信息。
         */
        public String reason;
    }

    返回结果说明

    错误码 错误码文案 错误码描述
    1000 刷脸成功 表示刷脸成功。
    说明 该结果仅供参考,可通过服务端获取最终认证结果。具体操作,请参见查询认证结果
    1001 系统错误 表示系统错误。
    1003 验证中断 表示验证中断。
    2002 网络错误 表示网络错误。
    2003 客户端设备时间错误 表示客户端设备时间错误。
    2006 刷脸失败 表示刷脸失败。
    说明 如需获取更详细的失败原因,需调用服务端。具体操作,请参见查询认证结果
    说明 关于错误码的更多信息,请参见Android客户端错误码详情

接口混淆配置

为避免接口混淆,您可以参考以下代码来保留类名(通常情况下,在封装release包时会保留类名):

-verbose

-keep class com.aliyun.aliyunface.network.model.** {*;}
-keep class com.aliyun.aliyunface.api.ZIMCallback {*;}
-keep class com.aliyun.aliyunface.api.ZIMFacade {*;}
-keep class com.aliyun.aliyunface.api.ZIMFacadeBuilder {*;}
-keep class com.aliyun.aliyunface.api.ZIMMetaInfo {*;}
-keep class com.aliyun.aliyunface.api.ZIMResponse {*;}
-keep class com.aliyun.aliyunface.api.ZIMSession {*;}
-keep class com.aliyun.aliyunface.config.**{*;}
-keep class com.aliyun.aliyunface.log.RecordBase {*;}
-keep class com.aliyun.aliyunface.ui.ToygerWebView {*;}

-keep class com.alipay.zoloz.toyger.**{*;}
-keep class com.alipay.zoloz.image.** {*;}
-keep class com.alipay.android.** {*;}
-keep class com.alipay.zoloz.toyger.ToygerState { *; }
-keep class com.alipay.zoloz.toyger.algorithm.Astro { *; }

-keep class net.security.device.api.** {*;}
-keep class com.alipay.deviceid.** { *; }
-keep class com.alibaba.fastjson.** {*;}
-keep class com.alibaba.sdk.android.oss.** { *; }
-dontwarn okio.**
-dontwarn org.apache.commons.codec.binary.**

-keepclassmembers,allowobfuscation class * {
     @com.alibaba.fastjson.annotation.JSONField <fields>;
}

权限说明

金融级实人认证为您提供安全的全链路身份核验服务。为了达到更好的设备风险防范效果,建议您在使用App调用刷脸SDK之前,提前向您的用户获取如下权限:

//授权获取手机状态的权限。
<uses-permission android:name="android.permission.READ_PHONE_STATE" />                
//授权获取接入网络的权限。开发人员需注意,Android 6.0以上系统属于动态权限。     
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Demo代码包

您可以下载Android Demo代码包(aliyunfaceDemo.zip)进行体验。