下载实人认证Android SDK的ZIP压缩包后,您可以参照本文内容将SDK集成到您的Android应用中。

背景信息

为了您的业务安全,实人认证Android SDK(以下简称SDK)与阿里云账号绑定,更换阿里云账号后,需要在实人认证管理控制台重新下载SDK。

关于开发环境IDE,Android Studio是Google官方推出并集成了多个便捷的开发插件的Android开发平台,本文将基于Android Studio(以下简称AS)介绍相关操作。关于Android Studio的更多信息,请参见Android Studio

在工程中导入SDK

在控制台成功上传APK包后,您可以下载并获取到一个名为阿里云认证SDK-ANDROID.zip的ZIP压缩包。

关于SDK包

解压ZIP包后,您将看到一系列SDK相关的依赖包,下表介绍了这些SDK包、文件的说明。其中,xxx表示版本号。

名称 描述
Sample/ 可参考的Demo工程,打上TODO标签的内容表示需要注意的点。
SDK包/rpsdk-xxx.aar 活体、认证SDK。
SDK包/SecurityGuardSDK-external-xxx-xxx.aar 安全加固依赖包。
说明 如果工程已集成阿里体系的其他产品(如阿里百川等)并含有该包,需判断哪个版本较新,并使用较新的版本。
SDK包/SecurityBodySDK-external-xxx-xxx.aar 安全加固依赖包。
说明 如果工程已集成阿里体系的其他产品(如阿里百川等)并含有该包,需判断哪个版本较新,并使用较新的版本。
SDK包/MiddleTierSDK-external-xxx-xxx.aar 安全加固依赖包。
说明 如果工程已集成阿里体系的其他产品(如阿里百川等)并含有该包,需判断哪个版本较新,并使用较新的版本。
SDK包/jniLibs-libc++_shared.zip 包含需要额外加入的SO公共依赖库文件*libc++_shared.so*

Google官方建议存在多个SO时,在编译生成C++ SO文件时选择STL类型为c++_shared,保证扩展性。更多内容,请参见NDK编译—C++ 库支持

RPSDK从3.2.0.0版本开始采用此种编译方式。您也可在Android NDK(建议使用ndk-18)包、目录(ndk-bundle)下的sources/cxx-stl/llvm-libc++/libs/路径下找到不同ABI类型的*libc++_shared.so*文件。

SDK包/jniLibs-armeabi.zip 为节省包体积,RPSDK从3.2.0.0版本开始已不再默认打入兼容armeabi的SO文件。

因为ARM v5(对应ABI类型armeabi)在现在已经是相当老旧的Android系统的CPU架构版本,现在主流的是ARM v7(对应ABI类型armeabi-v7a),并从Android 2.2开始支持。

如果您不需要考虑比之更低的版本,可忽略该ZIP文件。反之,或如果您应用的其他依赖包尚未提供兼容armeabi-v7a的支持包,必须要求armeabi,可在工程src/main/jniLibs(默认)目录下加入该ZIP包下的相应文件。

解压出SDK依赖包后,建议在工程根目录下创建目录libs(已有则忽略),根据上述介绍将SDK包拷入工程的libs目录下。目录
同时,解压出jniLibs.zip压缩包内容后,需要将内容拷至src/main/jniLibs(默认JNI依赖SO文件目录)下。目录2
说明 src/main/jniLibs并不是固定的,这和您定义的默认源集配置(sourceSets)有关。更多内容,请参见Google官方文档更改默认源集配置。默认情况下,jni的SO库文件在src/main/jniLibs下。

在工程中集成SDK

注意 已经集成SDK的客户,在升级新版本SDK时,要升级SDK里的安全加固相关的aar包(即SecurityGuardSDK和SecurityBodySDK相关的aar包)。

当SDK在4.13.0及以上版本,SDK不再强制校验应用的包名和签名,且签名图片已经自动合并到rpsdk_xxx.aar中,所以您最好删除存放在本地的yw_1222_*.jpg图片(主要指之前集成4.13.0之前版本的用户)。

基于包体积考虑,SDK在4.13.0及以上版本已经去除windvaneossokhttp等相关三方包依赖。所以客户可以基于自己实际的业务选择是否删除相关依赖。

添加SDK包依赖

以直接在应用下进行集成为例,在应用module下的build.gradle文件内,声明flatDir路径(如果已有则忽略):

apply plugin: 'com.android.application'

repositories {
  flatDir {
    dirs '../libs'
  }
}

以gradle版本大于等于3.0.0(注意非gradle tools版本,gradle版本可在gradle/wrapper/gradle-wrapper.properties下查看)为例,在应用module下的build.gradle文件内声明SDK包依赖:

dependencies {
    implementation fileTree(dir: '../libs', include: ['*.jar'])
    implementation (name:'rpsdk-4.13.2', ext:'aar')
    implementation (name:'SecurityGuardSDK-external-release-5.5.15071059', ext:'aar')
    implementation (name:'SecurityBodySDK-external-release-5.5.15071314', ext:'aar')
    implementation (name:'MiddleTierSDK-external-release-5.5.13874142', ext:'aar')
}
说明 关于AAR包的引入方式建议采用上面例子的写法,不要和JAR包混在一起引入,防止某些gradle版本无法正确解出AAR包内容。

关于ABI类型

SDK目前支持armeabi、armeabi-v7a、arm64-v8a三种ABI类型,其中RPSDK从3.2.0.0版本开始不再默认包含armeabi类型的SO库文件,建议接入方在应用module下的build.gradle文件内,添加abiFilters配置,示例:
android {
      defaultConfig {
            ndk {
                abiFilters "armeabi-v7a", "arm64-v8a"
            }
    }
}

关于签名配置

实人认证SDK要求必须存在V1签名,否则实人认证SDK不能正常工作。关于如何检测APK是否存在V1签名,请参考官方文档自行检查apk是否包含V1签名。参考以下build.gradle配置,开启V1签名。
 v1SigningEnabled true

关于混淆配置

如果您的应用使用了ProGuard进行代码混淆,为了保证实人认证服务需要的一些类不被混淆,需要在ProGuard配置文件中添加相关指令。

以AS为例,在应用module下的build.gradle文件内,如果配置了proguardFiles,并且启用了minifyEnabled,则表明已使用指定的配置文件(一般为proguard-rules.pro)进行了代码混淆,示例:
android {
    ...
    buildTypes {
        release {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
}
那么在相应的ProGuard配置文件(proguard-rules.pro)中添加以下配置信息,保证实人认证服务需要的类不被混淆,示例:
-keep class com.alibaba.security.**{*;}
-keep class com.taobao.dp.**{*;}
-keep class com.taobao.wireless.security.**{*;}
-keep class com.alibaba.wireless.security.**{*;}
-keep class android.taobao.windvane.**{*;}
-keep class android.webkit.JavascriptInterface
另外,如果工程在打包时启用了shrinkResources对资源进行压缩,还需要在keep.xml(res/raw/keep.xml)文件中添加以下内容:
<resources xmlns:tools="http://schemas.android.com/tools"
    tools:keep="@drawable/yw_1222_*, @layout/rp_*, @drawable/rp_*" />
注意 当工程环境配置的Android Gradle Plugin Version为4.2.0及以上版本时,该keep配置会失效,导致工程打Release包时签名图片依然被混淆不能使用。所以在接入时,您需要在工程的gradle.properties文件中加入android.enableResourceOptimizations=false,防止资源被混淆。

目前暂未支持gradle plugin version为7.0及以上版本。

如果您想了解关于资源压缩的更多内容,请参见Andriod官方文档Shrink your app。其中,压缩资源章节介绍了如何使用shrinkResources压缩资源,以及配置keep.xml,自定义要保留的资源。更多内容,请参见压缩资源

关于权限配置

使用SDK需要在AndroidManifest.xml中添加以下权限声明(已有则忽略):
<uses-permission android:name="android.permission.CAMERA"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>

Sample示例工程

压缩包内包含了可参考的样例工程(目录是Sample)。打上TODO标签的内容表示接入时需要注意的点。请您按照TODO标签的注意点,修改您业务的包名、签名和安全图片后,加上token就可以正常运行该工程。

使用SDK

初始化

一般在应用启动时,调用RPVerify的初始化接口。示例:
import android.app.Application;
import android.content.Context;

import com.alibaba.security.realidentity.RPVerify;

public class DemoApplication extends Application {
    private Context appContext;

    @Override
    public void onCreate() {
        super.onCreate();
        appContext = this.getApplicationContext();
        // 初始化实人认证SDK。
        RPVerify.init(appContext);
    }
}

上述写法并不是必须的,您可以在调用RPVerify其他接口前的任意位置调用初始化,但为了方便维护和管理,建议您按照示例操作。

调用实人认证

调用开始实人认证的接口前,需要您提前获取verifyTokenverifyToken由您的服务端调用发起认证请求接口DescribeVerifyToken获取),将其传入接口。

注意 返回的msg为具体的错误信息,建议自行存储。
RPVerify.start(DemoActivity.this, "", new RPEventListener() {
      @Override
      public void onFinish(RPResult auditResult, String code, String msg) {
        if (auditResult == RPResult.AUDIT_PASS) {
              // 认证通过。建议接入方调用实人认证服务端接口DescribeVerifyResult来获取最终的认证状态,并以此为准进行业务上的判断和处理。
              // do something
        } else if (auditResult == RPResult.AUDIT_FAIL) {
              // 认证不通过。建议接入方调用实人认证服务端接口DescribeVerifyResult来获取最终的认证状态,并以此为准进行业务上的判断和处理。
              // do something
        } else if (auditResult == RPResult.AUDIT_NOT) {
              // 未认证,具体原因可通过code来区分(code取值参见错误码说明),通常是用户主动退出或者姓名身份证号实名校验不匹配等原因,导致未完成认证流程。
              // do something
        }
      }
});
说明 code取值请参见错误码说明
RPVerify.start接口支持除RPMin外的所有认证方案,该接口会以加载H5的方式显示页面,如果您选择的认证方案只包含活体检测步骤,并对调起实人认证的速度有较高的要求,可以使用RPVerify.startByNative接口:
RPVerify.startByNative(DemoActivity.this, "", new RPEventListener() {
    @Override
      public void onFinish(RPResult auditResult, String code, String msg) {
        Toast.makeText(DemoActivity.this, auditResult + "", Toast.LENGTH_SHORT).show();

        if (auditResult == RPResult.AUDIT_PASS) {
              // 认证通过。建议接入方调用实人认证服务端接口DescribeVerifyResult来获取最终的认证状态,并以此为准进行业务上的判断和处理。
              // do something
        } else if (auditResult == RPResult.AUDIT_FAIL) {
              // 认证不通过。建议接入方调用实人认证服务端接口DescribeVerifyResult来获取最终的认证状态,并以此为准进行业务上的判断和处理。
              // do something
        } else if (auditResult == RPResult.AUDIT_NOT) {
              // 未认证,具体原因可通过code来区分(code取值参见错误码说明),通常是用户主动退出或者姓名身份证号实名校验不匹配等原因,导致未完成认证流程。
              // do something
        }
      }
});
说明
  • code取值请参见错误码说明
  • startByNative接口仅支持活体检测认证方案(如RPBioOnlyFDBioOnlyFVBioOnly),包含身份证件拍摄等其他步骤的认证方案需要使用start接口。

无论是start接口还是startByNative接口,在开始实人认证的接口中,verifyToken参数由接入方的服务端调用实人认证服务的DescribeVerifyToken接口获得。

错误码说明

具体请参见下表说明:
auditResult code code释义
RPResult.AUDIT_PASS 1 认证通过。
RPResult.AUDIT_FAIL 2~12 表示认证不通过,具体的不通过原因可以查看服务端的查询认证结果(DescribeVerifyResult)接口文档中认证状态的表格说明。
RPResult.AUDIT_NOT -1 未完成认证,原因:用户在认证过程中,主动退出。
-10 未完成认证,原因:设备问题,如设备无摄像头、无摄像头权限、摄像头初始化失败、当前手机不支持端活体算法等。
-20 未完成认证,原因:端活体算法异常,如算法初始化失败、算法检测失败等。
-30 未完成认证,原因:网络问题导致的异常,如网络链接错误、网络请求失败等。需要您检查网络并关闭代理。
-40 未完成认证,原因:SDK异常,原因包括SDK初始化失败、SDK调用参数为空、活体检测被中断(如电话打断),重复认证等。
-50 未完成认证,原因:用户活体失败次数超过限制。
-60 未完成认证,原因:手机的本地时间和网络时间不同步。
-10000 未完成认证,原因:客户端发生未知错误。
3001 未完成认证,原因:认证token无效或已过期。
3101 未完成认证,原因:用户姓名身份证实名校验不匹配。
3102 未完成认证,原因:实名校验身份证号不存在。
3103 未完成认证,原因:实名校验身份证号不合法。
3104 未完成认证,原因:认证已通过,重复提交。
3203 未完成认证,原因:设备不支持刷脸。
3204 未完成认证,原因:非本人操作。
3206 未完成认证,原因:非本人操作。
3208 未完成认证,原因:公安底照不存在。

UI定制

实人认证服务为您提供UI定制功能,您可以根据实际需要自定义实人认证页面的按钮颜色、文案颜色、文案字体大小和图片资源等信息。UI定制功能仅适用于实人认证Android SDK版本在4.6.2版本及以上。更多内容,请参见UI定制

// 设置UI自定义皮肤路径。
public RPConfig.Builder setSkinPath(String path);
// 设置皮肤是否内置。
public RPConfig.Builder setSkinInAssets(boolean b);

自定义配置

  • 设置可配置项

    可通过RPConfig.Builder创建一个RPConfig类实例。

    // 退出弹框是否需要确认。
    public RPConfig.Builder setShouldAlertOnExit(boolean shouldAlertOnExit);
    // 转场动画。
    public RPConfig.Builder setTransitionMode(TransitionMode transitionMode);
    // 是否需要声音。
    public RPConfig.Builder setNeedSound(boolean needSound);
  • 传入配置项

    可通过初始化接口设置你需要的UI样式。

    RPVerify.start(android.content.Context, String verifyToken, com.alibaba.security.realidentity.RPConfig config, RPEventListener listener)

常见问题

请参见Android集成常见问题