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

前提条件

请在Android 4.0.3+ (minSdkVersion >= 15) 以上版本的系统运行。

权限说明

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

权限 是否必须 备注
android.permission.INTERNET 没有该权限将导致SDK功能不可用。
android.permission.ACCESS_NETWORK_STATE 否(推荐赋予) 无。
android.permission.CAMERA 这些权限在Android 6.0以上机型中需要动态获取。

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

android.permission.READ_PHONE_STATE 否(推荐赋予)
android.permission.WRITE_EXTERNAL_STORAGE 否(推荐赋予)

配置依赖

  1. 下载卡证核身SDK(Android)到本地并完成解压。SDK为Android标准.aar包。
  2. 将解压得到的所有.aar文件导入到业务App工程的/libs目录下,并在App的build.gradle中添加以下依赖关系:
    说明 可能需要根据Android Studio版本略微调整。
    // SDK模块。
    implementation files('libs/aliyun-identityplatform-xxx.aar')
    implementation files('libs/aliyun-identityocr-xxx.aar')
    implementation files('libs/Android-AliyunDevice-xxx.aar')
    implementation files('libs/aliyun-ai-core-xxx.aar')
    implementation files('libs/aliyun-ai-xnn-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.1.72.android'
说明
  • 上述依赖关系中xxx表示SDK具体的版本号。
  • 在使用中不能缺少SDK三方依赖库,否则SDK功能会异常。

函数说明

卡证核身SDK包含初始化SDK(install)、获取MetaInfo(getMetaInfo)和开始认证(verify)3个函数,具体说明如下。

初始化SDK(install)函数
  • 描述:

    调用该函数完成SDK内部初始化。该函数需要在App启动的时候尽可能早去执行。

  • 函数原型:
    public void install(Context context);
  • 参数说明:
    名称 类型 说明
    context Context 当前Activity的context,主要用来后续context.startActivity启动SDK页面。
    注意 该参数值必须是当前Activity的Context值,否则会导致调用失败。
  • 返回值:

    无。

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

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

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

  • 函数原型:
    public static String getMetaInfo(Context context);
  • 参数说明:
    名称 类型 说明
    context Context 当前Activity的context。
  • 返回值:
    以JSON格式返回当前移动设备端的环境信息。返回值示例如下:
    {
        "apdidToken": "",
        "appName": "com.aliyun.identity.platform",
        "appVersion": "1.0.1",
        "bioMetaInfo": "5.1.0:11501568,4",
        "deviceBrand": "Xiaomi",
        "deviceManufacturer": "Xiaomi",
        "deviceModel": "Mi 10",
        "deviceType": "android",
        "identityVer": "1.0.0",
        "osVersion": "10",
        "sdkVersion": "1.0.9"
    }
开始认证(verify)函数
  • 描述:

    调用该函数发起卡证核身。

  • 函数原型:
    public void verify(String certifyId, Map<String, String> extParams,
                           IdentityType verifyMode, IdentityCallback callback);
  • 参数说明:
    名称 类型 说明
    certifyId String 从服务端初始化认证接口(InitSmartVerify)获取的CertifyId
    说明 每个CertifyId只能调用一次verify函数,每次调用verify函数之前都必须重新获取CertifyId
    extParams Map<String, String> 用户自定义参数,可以为空。目前支持自定义的字段请参见extParams支持的字段说明
    verifyMode IdentityType 识别证件类型,目前支持的类型如下:
    • IT_IDCARD:表示身份证。
    • IT_BANK:表示银行卡。
    callback IdentityCallback 认证结果回调。回调格式如下:
    public class IdentityOcrInfo {
        public String CertName;
        public String CertNo;
        public String Nationality;
        public String BirthDate;
        public String Address;
        public String Authority;
        public String StartDate;
        public String EndDate;
        public String NowDate;
        public String BankCardNo;
        public Bitmap IDCardFrontImage;
        public Bitmap IDCardBackImage;
        public Bitmap BankCardImage;
    }
    
    public class IdentityResponse {
        // 结果Code,具体含义可参考“返回值说明”章节。
        public int code;
        
        // 结果Code描述。
        public String message;
        
        // OCR信息。
        public IdentityOcrInfo ocrInfo;
    }
    
    public interface IdentityCallback {
        boolean response(IdentityResponse response);
    }

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

    名称 说明 示例值
    kIdentityParamKeyIdCardFaceOnly 是否只识别身份证人像面,取值为YESNO NO
    kIdentityParamKeyNextButtonColor OCR识别结果确认页底部按钮的底色。 #FF0000
    kIdentityParamKeyScanMaxTime OCR 证件扫描的超时时间,单位为秒,默认30秒。 30
    kIdentityParamKeyShowResult 是否需要展示OCR识别结果确认页,取值为YESNO YES
    kIdentityParamKeyValidIdCardDate 是否校验身份证有效期,取值为YESNO
    说明 此参数仅在kIdentityParamKeyIdCardFaceOnlyNO时生效。
    NO
    kIdentityParamKeyOcrMode OCR模式,取值:
    • PHOTO:表示拍照模式。
    • SCAN:表示扫描模式。

    默认是拍照模式。

    PHOTO
    kIdentityParamKeyWaterMark 自定义证件图片水印文字。默认文字为“仅供业务使用”。 仅供业务使用
    kIdentityParamKeyShowBlbumIcon 是否展示从相册选择图片的功能,取值为YESNO YES
    kIdentityParamKeyUIMode 选择UI样式。取值:
    • RectMode:阿里云Logo刷脸框。
    • RoundMode(默认):圆形刷脸框。
    RectMode
    kIdentityParamKeyRoundProgressColor 圆形刷脸框模式下,自定义进度条颜色。 #FF6A00
  • 返回值:

    无。

返回值说明

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

Code 说明
1000 认证通过。
1001 认证失败。
1002 系统异常。
1003 SDK初始化失败。
1004 摄像头错误。
1005 网络错误。
1006 用户取消。
1007 CertifyId无效。
1009 客户端时间戳错误。

示例代码

public class MainActivity extends AppCompatActivity {

    // 认证ID,需要从业务服务器端获取。
    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().verify(certifyId, null,
                                              IdentityPlatform.IdentityType.IT_IDCARD,
                                              new IdentityCallback() {
            @Override
            public boolean response(final IdentityResponse response) {
                if (IdentityResponseCode.IDENTITY_SUCCESS == response.code) {
                    Toast.makeText(MainActivity.this,
                                   "认证通过", Toast.LENGTH_LONG).show();
                    IdentityOcrInfo ocrInfo = response.ocrInfo;
                    if(null != ocrInfo){
                        xLogger.e(ocrInfo.CertName + " " + ocrInfo.CertNo);
                    }
                } else {
                    Toast.makeText(MainActivity.this,
                                   "认证失败([" + response.code + "]" + response.message + ")",
                                   Toast.LENGTH_LONG).show();
                }
                return true;
            }
        });
    }
}

接口混淆配置

为了避免不必要的接口混淆带来的问题,请参考以下代码来保留类名(一般用在打release包的时候):
-verbose
-keep class com.aliyun.identity.ocr.** {*;}
-keep class com.aliyun.identity.platform.** {*;}
-keep class com.ant.phone.xmedia.algorithm.** {*;}
-keep class xnn.** {*;}
-keep class net.security.device.api.** {*;}

-keep class com.darsh.multipleimageselect.** { *; }
-dontwarn com.darsh.multipleimageselect.**

-keep class com.soundcloud.android.crop.** { *; }
-dontwarn com.soundcloud.android.crop.**

Demo代码包

卡证核身Demo(Android)