ID_NFC_Android接入 - ID Verification

IDV NFC认证服务提供Android客户端SDK，帮助您在业务应用（App）中实现NFC认证功能。本文结合示例代码介绍Android客户端的接入流程。

使用限制

不支持模拟器模式调试,不支持x86架构。
仅支持Android 4.4及以上系统版本，且设备支持NFC的移动智能设备（手机或Pad）接入。

权限说明

权限	是否必须	说明
android.permission.INTERNET	是	联网权限。Android SDK需要联网才能使用。
android.permission.ACCESS_NETWORK_STATE	是	联网权限。Android SDK需要联网才能使用。
android.permission.NFC	是	NFC读取权限
android.permission.CAMERA	否（护照三要素通过OCR获取时需要此权限）	摄像头权限。该权限在Android 6.0及以上版本属于动态权限。

SDK下载和配置

下载Android SDK，该SDK为Android标准aar包。
下载完毕之后解压，将Android SDK文件夹中的所有aar文件拷贝到工程下的libs目录中，并在工程的build.gradle文件中添加如下依赖。

dependencies {
  // SDK modules 
  implementation files('libs/idv-identityplatform-xxx.aar') 
  implementation files('libs/idv-ientitycrypto-xxx.aar') 
  implementation files('libs/idv-identityocr-xxx.aar') 
  implementation files('libs/tygerservice-xxx.aar') 
  implementation files('libs/idv-identitybase-sdk-xxx.aar') 
  implementation files('libs/idv-identitymnn-xxx.aar') 
  implementation files('libs/idv-identityocrservice-xxx.aar') 
  implementation files('libs/idv-identitynfc-xxx.aar') 
  implementation files('libs/IDOCR_PubSDK_Android-1.0.0.aar') 

  // 或者用fileTree 方式依赖指定IDV实人认证服务SDK AAR目录，
  //implementation(fileTree(dir: "libs", includes: ["*.aar"]))

  implementation "androidx.appcompat:appcompat:1.5.0"//升级
  implementation "androidx.activity:activity:1.7.0"
  implementation "androidx.recyclerview:recyclerview:1.0.0"//升级
  implementation 'com.squareup.okhttp3:okhttp:4.9.3'//升级
  implementation 'com.squareup.okio:okio:2.8.0'//升级
  implementation 'com.aliyun.dpa:oss-android-sdk:2.9.21'
  implementation 'com.alibaba:fastjson:1.1.72.android'
}

说明

上述依赖中，xxx代表SDK的具体版本号。
使用中不能缺少三方依赖库，否则会导致SDK功能异常。

接口说明

Android SDK包含初始化SDK（install）、获取MetaInfo（getMetaInfo）和开始认证（verify）接口。

初始化SDK（install）

函数原型

public void install(Context context);
public void install(Context context,Map<String, String> options);

参数说明

context：当前Application的context。

options：信息采集可选项，默认可以为null。可选参数如下：

重要

ID Verification客户端内置设备助手安全模块，为了满足不同地域数据收集合规要求，提供了不同的数据上报区域。您可以基于用户属性不同，设置CustomUrl和CustomHost指定不同的上报站点。
一次应用会话生命周期内只能指定一个地域上报，且服务端查询时地域需要和上报地域保持一致。各产品服务端支持的地域有所不同，详情请参考支持的地域。
各地域的CustomUrl：
- 中国香港：https://cloudauth-device.cn-hongkong.aliyuncs.com
- 新加坡：https://cloudauth-device.ap-southeast-1.aliyuncs.com
- 印度尼西亚（雅加达）：https://cloudauth-device.ap-southeast-5.aliyuncs.com
- 美国（硅谷）：https://cloudauth-device.us-west-1.aliyuncs.com
- 德国（法兰克福）：https://cloudauth-device.eu-central-1.aliyuncs.com
- 马来西亚（吉隆坡）：https://cloudauth-device.ap-southeast-3.aliyuncs.com

字段名	说明	示例
IPv6	是否使用IPv6域名上报设备信息： 0（默认）：否（使用IPv4域名） 1：是（使用IPv6域名）	"1"
DataSwitch	设备信息上报时机。 0（默认）：初始化时 1：获取Token时说明建议采用默认配置。	"1"
CustomUrl	设置数据上报服务器域名。	具体内容，请参见各地域的CustomUrl。
CustomHost	设置数据上报服务器host。	"cloudauth-device.ap-southeast-1.aliyuncs.com" 说明此处为新加坡地域示例，其他地域的host，请参见各地域的CustomUrl。

返回值：无。

获取MetaInfo （getMetaInfo）

函数原型

public static String getMetaInfo(Context context);

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

返回值：String类型，以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）

重要

调用此方法前，请确认您已将 MetaInfo 传递至服务端，并通过 Initialize 接口获取了 transactionId 。

新版本新增protocol字段返回，新增的protocol通过扩展参数extParams传入。

函数原型

public void verify(String transactionId, Map<String, String> extParams, IdentityCallback callback);

参数说明

名称	类型	说明
transactionId	String	从服务端初始化认证接口（Initialize）获取的transactionId。重要每个transactionId只能调用一次verify函数，每次调用verify函数之前务必重新获取transactionId。
extParams	Map<String, String>	扩展参数，通常情况下传null即可。目前支持的自定义字段，extParams配置说明在下方表格中列出。
callback	IdentityCallback	认证结果的回调接口，回调中的返回码参见IdentityResponse.code表。回调格式如下： `public class IdentityResponse { // See the description of "Return Code". public int code; // Result code description. public String message; } public interface IdentityCallback { boolean response(IdentityResponse response); }`

extParams配置说明

Key	说明	示例（String类型）
IdentityParams.OcrResultButtonColor	OCR识别结果页面的底部按钮颜色。	#FF0000
IdentityParams.ShowBlbumIcon	证件OCR识别环节，是否展示相册上传入口： 1（默认）：展示 0：不展示	1
IdentityParams.MaxErrorTimes	重试次数上限。可设置范围为3~10次，默认10次。	10
IdentityParams.CardOcrTimeOutPeriod	OCR识别环节超时时长。可设置范围为20~60秒，默认20秒。	20
IdentityParams.FaceVerifyTimeOutPeriod	活体采集检测环节超时时长。可设置范围为20~60秒，默认20秒。	20
IdentityParams.OcrResultTimeOutPeriod	OCR识别结果页面可编辑时长。可自定义配置，默认不限。	60
IdentityParams.SdkLanguage	SDK语言自定义设置。默认跟随移动设备系统的设置。说明 SDK具体支持的语言列表，请参见Android和iOS SDK 自定义语种。	zh-Hans
IdentityParams.CloseButtonLayout	关闭按钮的布局： left（默认）：左侧 right：右侧	left
IdentityParams.WaterMark	OCR识别成功后水印文字。	测试水印文字
IdentityParams.Protocol	SDK Protocol。说明通过服务端Initialize接口获取protocol，传入扩展参数中，可减少SDK内部接口交互，提升网络体验。	无

IdentityResponse.code表

错误码	是否计费	subCode	结果码描述
1000	是	A1000_1	用户完成了刷脸过程，认证建议结果为通过。该结果仅供参考，可通过调用服务端CheckResult接口获取最终认证结果，并进行下一步处理。
1001	是	A1001_1	用户完成了刷脸过程，认证建议结果为未通过。该结果仅供参考，可通过调用服务端CheckResult接口获取最终认证结果、未通过的详细原因，并进行下一步处理。
1002	否	A1002_1	模型加载失败。
		A1002_2	App退到后台（按下home键），App再次回到前台，SDK主动退出。
		A1002_3	so库加载失败。
1003	否	A1003_1	初始化接口内容为空。
		A1003_2	初始化接口内容格式错误。
		A1003_3	初始化接口协议连接失败。
		A1003_4	初始化接口内容解密失败。
		A1003_5	初始化接口失败（Code不为200，或BizCode不为CODE_INIT_SUCCESS"）
		A1003_6	初始化接口OSS为空。
		A1003_7	传入空的Context。
1004	否	A1004_1	前置摄像头异常。
		A1004_2	打开摄像头异常。
		A1004_3	后置摄像头异常。
1005	否	A1005_1	初始化接口网络异常。
1005	否	A1005_2	认证接口网络异常
1006	否	A1006_1	用户退出。
1007	否	A1007_1	TransactionId无效。
A1008	否	A1008_1	NFC 模块缺失
		A1008_2	OCR 模块缺失
		A1008_3	人脸模块缺失
1009	否		客户端时间戳错误。
1010	否	A1010_1	在调用verify之前没有调用install方法。
1011	否		提交证件类型错误。
1012	否	A1012_1	识别出的证件关键信息缺失或格式校验失败。
1013	否		图片质量不佳。
1014	否	A1014_1	错误次数超出上限。
1015	否	A1015_1	安卓系统版本过低。
1016	否	A1016_1	未获取到相机权限。
1017	否	A1017_1	参数异常_productCode为空
2000	否	A2000_1	NFC配置失败
2000	否	A2000_2	未开启NFC权限
2002	否	A2002_1	设备不支持NFC

示例代码

public class MainActivity extends AppCompatActivity {
    private String transactionId = "";
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
    
        // 初始化SDK
        IdentityPlatform.getInstance().install(MainActivity.this);
    
        // 获取MetaInfo
        String metaInfo = IdentityPlatform.getMetaInfo(MainActivity.this);
    
        /**
         * 将MetaInfo发送到App服务器端，调用云端Initialize接口获取transactionId，
         * 新版本会返回protocol数据
         */
        // transactionId = getTransactionIdFromServer(metaInfo).transactionId;
        //protocol ==getTransactionIdFromServer(metaInfo).protocol;;
        
        Map<String, String> extParams = new HashMap();
        //设置协议数据
        extParams.put(IdentityParams.PROTOCOL, protocol);
        // 设置SDK语言
        extParams.put(IdentityParams.SdkLanguage, "en");
        // 开始认证
        IdentityPlatform.getInstance().verify(transactionId, extParams,
                new IdentityCallback() {
                    @Override
                    public boolean response(final IdentityResponse response) {
                        if (IdentityResponseCode.IDENTITY_SUCCESS == response.code) {
                            Toast.makeText(MainActivity.this,
                                    "Verification passed", Toast.LENGTH_LONG).show();
                        } else {
                            Toast.makeText(MainActivity.this,
                                    "Verification failed([" + response.code + "]" +
                                            response.message + ")",
                                    Toast.LENGTH_LONG).show();
                        }
                        return true;
                    }
                });
    }
    
}

混淆配置

-verbose
-keep class com.idv.identity.platform.api.** {*;}
-keep class com.idv.identity.platform.log.** {*;}
-keep class com.idv.identity.util.IdentityUtils {*;}
-keep class com.idv.identity.ocr.IdentityOcrApi {*;}
-keep class com.idv.identity.platform.model.** {*;}
-keep class com.idv.identity.platform.config.** {*;}
-keep class com.idv.identity.face.IdentityFaceApi {*;}


-keep class com.face.verify.intl.** {*;}
-keep class com.alibaba.fastjson.** {*;}
-keep class face.security.device.api.** {*;}
-keep class net.security.device.api.** {*;}
-keep class com.dtf.toyger.** { *; }
-dontwarn net.security.device.api.**
-dontwarn face.security.device.api.**


-keep class com.idv.identity.service.algorithm.** {*;}
-keep class com.idv.identity.base.algorithm.** {*;}
-keep class com.idv.identity.quality.QualityRouter {*;}
-keep class com.idv.identity.service.IdentityFaceService {*;}
-keep class com.idv.identity.service.ocr.IdentityDocService {*;}

-keep class com.alibaba.sdk.android.oss.** { *; }
-dontwarn okio.**
-dontwarn org.apache.commons.codec.binary.**



# NFC
-keep class com.idv.identity.nfc.IdentityNfcApi { *; }
-keep class org.jmrtd.** {*;}
-keep class net.sf.**{*;}
-keep class org.**{*;}
-keep class cn.**{*;}


# Please add these rules to your existing keep rules in order to suppress warnings.
# This is generated automatically by the Android Gradle plugin.
-dontwarn com.fasterxml.**
-dontwarn com.google.**
-dontwarn java.applet.Applet
-dontwarn java.awt.**
-dontwarn javax.**
-dontwarn org.**
-dontwarn retrofit2.**
-dontwarn springfox.documentation.spring.web.json.Json

Demo代码包

您可以下载Android Demo进行体验。

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