文档

Android接入

更新时间:

金融级实人认证服务提供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文件中添加如下依赖。

重要

代码示例中xxx表示版本号,使用过程中,请替换为SDK包中文件的实际版本号。

# 阿里云实人认证服务SDK AAR
implementation files('libs/aliyun-base-xxx.aar')
implementation files('libs/aliyun-facade-xxx.aar')
implementation files('libs/aliyun-face-xxx.aar')
implementation files('libs/aliyun-faceaudio-xxx.aar')
implementation files('libs/aliyun-facelanguage-xxx.aar')
implementation files('libs/aliyun-nfc-xxx.aar')
implementation files('libs/aliyun-ocr-xxx.aar')
implementation files('libs/aliyun-photinus-xxx.aar')
implementation files('libs/aliyun-wishverify-xxx.aar') #compileSdkVersion必须在29及以上才可使用 
implementation files('libs/Android-AliyunFaceGuard-xxx.aar')
implementation files('libs/APSecuritySDK-DeepSec-xxx.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'
implementation 'com.aliyun.dpa:oss-android-sdk:2.9.11'

接口说明

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文件中添加如下配置信息:

-keep class com.alipay.deviceid.** { *; }
-keep class net.security.device.api.** {*;}
-keep class face.security.device.api.** {*;}
-keep class org.json.** { *;}
-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>;
}

示例代码

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); // 需客户自己实现

        // 开始验证
        ZIMFacade zimFacade = ZIMFacadeBuilder.create(ctx);
        zimFacade.verify(certifyId, true, null, 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包裁剪说明

  • 本页导读
文档反馈