文档

Android客户端接入

更新时间:
重要

本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。

增强版实人认证服务提供Android客户端SDK,帮助您在App中实现实人认证功能。您可通过服务端认证初始化接口,获取唯一标识CertifyId,并使用CertifyId唤起客户端SDK。本文介绍了在Android客户端集成增强版活体检测SDK的详细流程。

前提条件

请在Android 4.0.3+ (minSdkVersion ≥ 15) 以上系统版本的移动设备(手机与PAD上)运行。

说明

不支持模拟器设备、定制硬件设备应用。建议您和商户经理沟通具体定制设备的应用场景,评估切换其他集成方案。

权限说明

为了加强安全效果,当前SDK需要下表描述的权限。

权限

是否必须

备注

android.permission.INTERNET

没有该权限将导致SDK功能不可用。

android.permission.ACCESS_NETWORK_STATE

否(推荐赋予)

无。

android.permission.CAMERA

这些权限在Android 6.0以上机型中需要动态获取。

如果您要启用权限,则接入时需要注意在初始化接口调用之前,确保您的App已经被授予了权限。

android.permission.READ_EXTERNAL_STORAGE

否(推荐赋予)

下载及配置SDK

  1. 下载增强版活体检测SDK(Android)到本地并完成解压。SDK中的文件为Android标准.aar包。

  2. 将解压得到的所有.aar文件导入到业务App工程的/libs目录下,并在App的build.gradle中添加以下依赖关系:

    // SDK模块。
    implementation files('libs/aliyun-identityplatform-xxx.aar')
    implementation files('libs/aliyun-identityface-xxx.aar')
    implementation files('libs/Android-AliyunFaceGuard-xxx.aar')
    implementation files('libs/aliyun-identitycrypto-xxx.aar')
    
    // SDK三方依赖模块。
    implementation 'com.android.support:appcompat-v7:28.0.0'
    implementation 'com.squareup.okhttp3:okhttp:3.11.0'
    implementation 'com.squareup.okio:okio:1.14.0'
    implementation 'com.aliyun.dpa:oss-android-sdk:+'
    implementation 'com.alibaba:fastjson:1.2.83_noneautotype'
说明
  • 上述依赖关系中xxx表示SDK具体的版本号。

  • 在使用中不能缺少SDK三方依赖库,否则SDK功能会异常。

函数说明

增强版活体检测SDK包含初始化SDK(install)、获取MetaInfo(getMetaInfo)和开始认证(faceDetect)3个函数,具体说明如下。

初始化SDK(install)函数

  • 描述:

    调用该函数完成SDK内部初始化。请务必做延迟初始化配置,确保在用户同意《隐私权政策》后,在人脸识别业务场景中初始化SDK。

  • 函数原型:

    public void install(Context context);
  • 参数说明:

    名称

    类型

    说明

    context

    Context

    当前Application的context。

  • 返回值:

    无。

警告

为了确保整个验证过程的安全性,SDK会对设备环境做一些检查,请确保在调用install函数之前App已经获取了android.permission.INTERNET权限,否则将导致SDK功能不可用。

获取MetaInfo(getMetaInfo)函数

  • 描述:

    调用该函数获取当前移动设备端的环境信息,并将这些信息发送到业务服务器端。

    业务服务器端会将这些信息作为参数之一(MetaInfo)调用服务端初始化认证接口(InitSmartVerify),从而获取CertifyId,用于后续验证环节。

  • 函数原型:

    String metaInfo = IdentityPlatform.getInstance().getMetaInfo(MainActivity.this);
  • 参数说明:

    名称

    类型

    说明

    context

    Context

    当前Activity的context。

  • 返回值:

    以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"
    }

开始认证(faceDetect)函数

  • 描述:

    调用该函数发起增强版活体检测。

  • 函数原型:

    public void faceDetect(String certifyId, Map<String, String> extParams, 
                           IdentityCallback callback);
  • 参数说明:

    名称

    类型

    说明

    certifyId

    String

    从服务端初始化认证接口(InitSmartVerify)获取的CertifyId

    说明

    每个CertifyId只能调用一次faceDetect函数,每次调用faceDetect函数之前都必须重新获取CertifyId

    extParams

    Map<String, String>

    自定义用户参数,可以为空。目前支持自定义的字段,请参见extParams

    callback

    IdentityCallback

    认证结果回调。回调格式如下:

    public class IdentityResponse {
        // 结果Code,具体含义可参考“返回值说明”章节。
        public int code;
        
        // 结果Code描述。
        public String message;
    }
    
    public interface IdentityCallback {
        boolean response(IdentityResponse response);
    }

    用户自定义参数extParams支持的字段说明:

    名称

    描述

    示例值

    kIdentityParamKeyRoundProgressColor

    圆形刷脸框模式下,自定义进度条颜色。

    #FF6A00

  • 返回值:

    无。

返回值说明

服务器端的验证结果通过IdentityResponse.code返回,取值范围如下表所示。

Code

说明

1000

认证通过。

1001

认证失败。

1002

系统异常。

1003

SDK初始化失败,请确认客户端时间是否正确,手机系统时间被修改会导致阿里云网关校验异常。

1004

摄像头错误。

1005

网络错误。

1006

用户取消。

1007

CertifyId无效。

1009

客户端时间戳错误。

1010

验证前,没有进行初始化。

1011

操作超时。

1012

暂不支持Android 4.3及以下版本。

1013

没有开启相机权限。

示例代码

public class MainActivity extends AppCompatActivity {

    private String certifyId = "";

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        // 初始化SDK,install和后续的验证接口最好延迟3秒左右。
        IdentityPlatform.getInstance().install(MainActivity.this);

        // 获取MetaInfo。
        String metaInfo = IdentityPlatform.getMetaInfo(MainActivity.this);

        // 将MetaInfo发送到App服务器端,调用云端InitSmartVerify接口获取CertifyId。
        // certifyId = getCertifyIdFromServer(metaInfo);

        // 开始认证。
        IdentityPlatform.getInstance().faceDetect(certifyId, null,
                                                  new IdentityCallback() {
            @Override
            public boolean response(final IdentityResponse response) {
                if (IdentityResponseCode.IDENTITY_SUCCESS == response.code) {
                    Toast.makeText(MainActivity.this,
                                   "认证通过", Toast.LENGTH_LONG).show();
                } else {
                    Toast.makeText(MainActivity.this,
                                   "认证失败([" + response.code + "]" + response.message + ")",
                                   Toast.LENGTH_LONG).show();
                }
                return true;
            }
        });
    }
}

接口混淆配置

为了避免不必要的接口混淆带来的问题,请参考以下代码来保留类名(一般用在打Release包的时候):

-verbose
-keep class com.aliyun.identity.face.** {*;}
-keep class com.aliyun.identity.platform.** {*;}
-keep class com.alipay.zoloz.** {*;}
-keep class net.security.device.api.** {*;}
-keep class com.aliyun.identity.IdentityUtils {*;}

Demo代码包

增强版活体检测Demo(Android)