在Android客户端集成卡证核身如何使用SDK-阿里云帮助中心

增强版实人认证服务提供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

下载卡证核身SDK（Android）到本地并完成解压。SDK为Android标准.aar包。

将解压得到的所有.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/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）和开始认证（verify）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"
}

开始认证（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	是否只识别身份证人像面，取值为YES或NO。	NO
kIdentityParamKeyNextButtonColor	OCR识别结果确认页底部按钮的底色。	#FF0000
kIdentityParamKeyShowResult	是否需要展示OCR识别结果确认页，取值为YES或NO。	YES
kIdentityParamKeyValidIdCardDate	是否校验身份证有效期，取值为YES或NO。说明此参数仅在kIdentityParamKeyIdCardFaceOnly为NO时生效。	NO
kIdentityParamKeyWaterMark	自定义证件图片水印文字。默认文字为“仅供业务使用”。	仅供业务使用
kIdentityParamKeyShowBlbumIcon	是否展示从相册选择图片的功能，取值为YES或NO。	YES
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 {

    // 认证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 net.security.device.api.** {*;}

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

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

Demo代码包

卡证核身Demo（Android）

名称	类型	说明
context	Context	当前Application的context。

名称	类型	说明
context	Context	当前Activity的context。