Android接入 - ID Verification

ID Verification提供Android客户端SDK，帮助您在业务应用（App）中实现eKYC远程身份验证功能。您可通过服务端认证初始化接口，获取唯一标识transactionId，并使用transactionId唤起客户端SDK。本文结合示例代码介绍Android客户端的接入流程。

使用限制

适用系统：Android 4.3及以上版本的手机或平板电脑。
不支持：x86架构设备。

权限说明

为提升安全效果，当前SDK需要以下权限：

权限	是否必须	说明
android.permission.INTERNET	是	联网权限。Android SDK需要联网才能使用。
android.permission.ACCESS_NETWORK_STATE	否（推荐开启）	联网权限。Android SDK需要联网才能使用。
android.permission.CAMERA	是	摄像头权限。该权限在Android 6.0及以上版本属于动态权限。
android.permission.WRITE_EXTERNAL_STORAGE	否	引入`com.aliyun.dpa:oss-android-sdk:$version` 组件会自动声明该权限，如果接入的App不需要此权限，可在`AndroidManifest.xml` 中使用remove标签移除此权限： `<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" tools:remove="true" />`

SDK下载和配置

Android SDK 为标准 AAR 包，请前往客户端SDK发布记录下载。如需体验功能，可同步下载 Android Demo。

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

dependencies {
    // SDK modules 
    implementation files('libs/idv-identityplatform-xxx.aar') 
    implementation files('libs/idv-identityface-xxx.aar') 
    implementation files('libs/idv-identitycrypto-xxx.aar') 
    implementation files('libs/idv-identityocr-xxx.aar') 
    implementation files('libs/Android-AliyunFaceGuard-xxx.aar')
    implementation files('libs/idv-identitybase-sdk-xxx.aar') 
    implementation files('libs/idv-identityservice-sdk-xxx.aar') 
    implementation files('libs/idv-identityquality-sdk-xxx.aar') 
    implementation files('libs/idv-identityblink-sdk-xxx.aar')
    implementation files('libs/idv-identitymouth-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.2.83_noneautotype'
}

说明

上述依赖中，xxx代表SDK的具体版本号。
使用中不能缺少三方依赖库，否则会导致SDK功能异常。
从1.3.4版本开始，tygerservice-xxx.aar组件已被移除。
从1.3.6版本开始，新增idv-identitymouth-sdk-xxx.aar组件。

接口说明

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	认证结果的回调接口，回调中的返回码请参见Native SDK客户端结果码和结果子码说明。回调定义如下： `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.RoundProgressColor	扫脸时的圆圈颜色。	#FF0000
IdentityParams.ShowBlbumIcon	证件OCR识别环节，是否展示相册上传入口： 1（默认）：展示 0：不展示	1
IdentityParams.ShowOcrResult	证件OCR识别环节，是否展示识别结果页： 1（默认）：展示 0：不展示	1
IdentityParams.EditOcrResult	证件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内部接口交互，提升网络体验。	无

结果码

返回的结果码与结果字码信息，请参见Native SDK客户端结果码和结果子码说明。

示例代码

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.blink.BlinkRouter {*;}
-keep class com.idv.identity.service.IdentityFaceService {*;}
-keep class com.idv.identity.service.ocr.IdentityDocService {*;}
-keep class com.idv.identity.mouth.MouthRouter {*;}

-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

#日志混淆，可选
-assumenosideeffects class android.util.Log {
    public static *** d(...);
}

# 若使用的1.3.2之前的版本需要添加如下混淆规则
-keepattributes Signature
-keepattributes *Annotation*
-keep class com.alibaba.fastjson.** { *; }
-keep class * extends com.alibaba.fastjson.TypeReference { *; }

组件裁剪

在 SDK 接入阶段，支持对部分组件进行裁剪。在确保功能完整与安全合规的前提下，建议依据实际产品方案按需集成组件，以最大程度减小 SDK 包体积。详细的裁剪规则，请参见SDK裁剪说明。

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