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

背景信息

为了您的业务安全,实人认证Android SDK(以下简称SDK)与应用的包名(AndroidManifest.xml中的package)和签名(build.gradle中的signingConfig)绑定,修改应用的包名或签名后都需要在实人认证管理控制台重新下载SDK。

另外,debug包和release包在使用不同签名时不能混用同一张签名图片文件(yw_1222_*.jpg)。

注意 如果debug模式下未指定使用签名,IDE(以Android Studio为例)默认使用debug.keystore进行签名(Linux、MacOS下一般在~/.android/debug.keystore进行签名),该签名和您的release包的正式签名不相同。
如果您不了解如何生成自己的签名文件并指定使用签名,请参见Android官方文档Sign your app。其中,
说明 如果您需要用到V2方式的签名,生成签名文件时请同时勾选V1、V2签名;如果只选择V2签名,APK将无法在Android 7.0以下版本安装。

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

在工程中导入SDK

在控制台成功上传APK包后,您可以下载并获取到一个名为阿里云认证SDK-ANDROID.zip的ZIP压缩包。将其解压后,您可以看到在一级目录下有yw_1222_0670.jpgclient.zip两个文件。

关于签名图片

yw_1222_0670.jpg是签名图片文件,该文件和您上传的APK的包名以及签名强绑定,用于SDK的使用授权。

注意 不同包名或签名的包不能共用一个签名图片文件。当您的应用改变了包名或签名后,请务必将其重新上传到实人认证控制台,获取新的签名图片文件。不同包名或签名的渠道包也受到同样的限制。

将签名图片文件导入到工程应用模块的res/drawable目录下。如果没有这个目录,请先在工程中创建,否则将无法正常工作。

另外,如果工程在打包时启用了shrinkResources对资源进行压缩,还需要在keep.xmlres/raw/keep.xml)文件中添加以下内容:
<resources xmlns:tools="http://schemas.android.com/tools" tools:keep="@drawable/yw_1222_*" />

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

关于SDK包

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

说明 以下内容支持RPSDK 4.0.0及以上版本。
名称 描述
UI定制使用方法.md 活体识别Native端UI定制使用指南。
Sample/ 可参考的Demo工程,打上TODO标签的内容表示需要注意的点。
SDK包/rpsdk-xxx.aar 活体、认证SDK依赖包。
SDK包/windvane-min-xxx.jar WebView依赖包。
SDK包/fastjson-xxx.jar fastjson扩展依赖包。
说明 如果工程已集成该包,可忽略,但务必保证已集成的包的版本号高于实人认证服务提供的包的版本号。
SDK包/oss-android-sdk-xxx.aar OSS上传依赖包。
说明 如果工程已集成该包,可忽略,但为了兼容Android 9.0,请务必保证版本号在2.9.0以上。公共Maven库中已有该包,在dependencies下也可通过com.aliyun.dpa:oss-android-sdk:+定位。
SDK包/okhttp-xxx.jar 网络请求依赖包。
说明 如果工程已集成该包,可忽略,但务必保证使用3.0系列版本,且版本号高于实人认证服务提供的包的版本号。公共Maven库中已有该包,在dependencies下也可通过com.squareup.okhttp3:okhttp:+定位。
SDK包/okio-xxx.jar okhttp扩展依赖包。
说明 如果工程已集成该包,可忽略,但务必保证已集成的包的版本号高于我们提供的包的版本号。公共Maven库中已有该包,在dependencies下也可通过com.squareup.okio:okio:+定位。
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目录下。libs
同时,如果RPSDK包版本是3.2.0.0及以上,解压出jniLibs.zip压缩包内容后,需要将内容拷至src/main/jniLibs(默认JNI依赖SO文件目录)下。jniLibs
说明 src/main/jniLibs并不是固定的,这和您定义的默认源集配置(sourceSets)有关,具体请参见Google官方文档更改默认源集配置。默认情况下,jni的SO库文件在src/main/jniLibs下。

如果您之前已集成过旧版本的SDK,请覆盖相应SDK依赖包文件(删除旧版本的包)。如果您之前RPSDK版本是3.0.x.x,新版本在3.1.x.x以上,请同时更新签名图片文件yw_1222_0670.jpg

在工程中集成SDK

说明 对于SDK 4.4.0版本,请您务必升级SDK中的安全加固相关的aar包。

添加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.4.0', ext:'aar')
    implementation (name:'oss-android-sdk-2.9.2', ext:'aar')
    implementation (name:'SecurityGuardSDK-external-release-5.5.13814304', ext:'aar')
    implementation (name:'SecurityBodySDK-external-release-5.5.14', ext:'aar')
    implementation (name:'MiddleTierSDK-external-release-5.5.13814304', 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"
            }
    }
}

关于签名配置

检查您工程的Gradle Plugin版本是否大于3.4.1,如果Gradle Plugin版本大于3.4.1,请您将Gradle Plugin版本降至3.4.1,并将Gradle版本降至5.4.1。如果无法降低Gradle Plugin及Gradle版本,需要在您工程的App模块下的build.gradle中添加签名配置,示例:
signingConfigs {
        release {
            //TODO修改为你的release签名文件信息。
            storeFile file('test.jks')
            storePassword "test1234"
            keyAlias "key0"
            keyPassword "test1234"
            //TODO修改为你的release签名文件信息。

            v1SigningEnabled true
            v2SigningEnabled true
        }
        debug {
            //TODO修改为你的release签名文件信息。
            storeFile file('test.jks')
            storePassword "test1234"
            keyAlias "key0"
            keyPassword "test1234"
            //TODO你的debug签名文件信息。

            v1SigningEnabled true
            v2SigningEnabled false
        }
    }

    buildTypes {
        release {
            minifyEnabled false
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
            signingConfig signingConfigs.release
        }

        debug {
            minifyEnabled false
            signingConfig signingConfigs.debug
        }
}

关于混淆配置

如果您的应用使用了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.taobao.securityjni.**{*;}
-keep class com.taobao.wireless.security.**{*;}
-keep class com.ut.secbody.**{*;}
-keep class com.taobao.dp.**{*;}
-keep class com.alibaba.wireless.security.**{*;}
-keep class com.alibaba.security.rp.**{*;}
-keep class com.alibaba.security.cloud.**{*;}
-keep class com.alibaba.security.realidentity.**{*;}
-keep class com.alibaba.security.biometrics.**{*;}
-keep class com.alibaba.sdk.android.**{*;}
-keep class android.taobao.windvane.**{*;}

关于权限配置

使用SDK需要在AndroidManifest.xml中添加以下权限声明(已有则忽略):
<uses-permission android:name="android.permission.CAMERA"/>
如果您使用的RPSDK版本在3.0.0.4(不含)以下,还需要添加以下权限声明(已有则忽略):
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>

Sample示例工程

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

使用SDK

在使用SDK时,您只需关注RPSDK内的RPVerify相关接口(RPSDK>=4.1.0)。
注意 对于4.0.0和4.0.4版本的RPSDK,您需要关注的接口为CloudRealIdentityTrigger

初始化

一般在应用启动时,调用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);
    }
}
注意 对于4.0.0和4.0.4版本,应用启动时,调用CloudRealIdentityTrigger#initialize初始化接口。

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

调用实人认证

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

注意
  • 返回的msg为冗余字段,不包含任何信息。
  • 对于4.0.0和4.0.4版本,应用启动时,调用CloudRealIdentityTrigger#start接口。
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接口。另外,使用startVerifyByNative接口时,对应的认证方案不支持在实人认证控制台配置引导页、授权页、结果页等,需接入方自行处理。如果需要在实人认证控制台配置使用引导页、授权页、结果页等,则只能使用start接口。
  • 对于4.0.0和4.0.4版本,应用启动时,调用CloudRealIdentityTrigger#startVerifyByNative接口。
如果使用startByNative接口,第三个回调参数可以传入RPEventListener类实例。该类除了可以正常获取认证结果外,也可以在活体识别页面启动时和关闭时分别做自己的处理。示例:
RPVerify.startByNative(DemoActivity.this, "", new RPEventListener() {
    @Override
      public void onFinish(RPResult auditResult, String code, String msg) {
        // 整个认证流程结束,回调认证结果。
      }
});

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

错误码说明

ALRealIdentityCallback#onAuditResult中可获取到认证状态和认证失败时的错误码,具体请参见下表说明。
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 未完成认证,原因:非本人操作。

UI定制

目前的SDK包仅支持活体识别Native页面的UI定制。其他像H5页面中的输入姓名和身份证、拍摄证件照等页面暂不支持定制。

自定义图片等资源

可将需要替换的图片放在assets/facetheme/下。目前支持替换以下静态资源:
  • face_nav_button.png:屏幕下方按钮,像素为716*114。
  • face_top_back.png:屏幕顶端关闭按钮,像素为36*36。
  • face_top_sound_on.png:屏幕顶端声音按钮的声音打开状态,按钮的像素为36*36。
  • face_top_sound_off.png:屏幕顶端声音按钮的声音关闭状态,按钮的像素为36*36。
自定义配置
  1. 设置可配置项。
    可通过RPConfig.Builder实例创建一个RPConfig类实例,并参考设置以下字段参数:
    //按钮文字颜色 (引导页/失败页等按钮)。
    public RPConfig.Builder setButtonTextColor(String buttonTextColor);
    //认证失败时候的文案颜色。
    public RPConfig.Builder setErrorTextColor(String errorTextColor);
    //认证过程中提示文案颜色。
    public RPConfig.Builder setPromptTextColor(String promptTextColor);
    //认证过程中提示颜色。
    public RPConfig.Builder setTipTextColor(String tipTextColor);
    //波纹颜色。
    public RPConfig.Builder setWavesColor(String wavesColor);
    //波纹过程中的颜色。
    public RPConfig.Builder setWavesDetectingColor(String wavesDetectingColor);
    //波纹底色。
    public RPConfig.Builder setWavesBgColor(String wavesBgColor);
    //转场动画。
    public RPConfig.Builder setTransitionMode(TransitionMode transitionMode);
    //以弹框形式显示识别页面。
    public RPConfig.Builder setShowWithDialog(boolean showWithDialog);
    //是否需要声音。
    public RPConfig.Builder setNeedSound(boolean needSound);
  2. 传入配置项。

    可通过初始化接口RPVerify.start(android.content.Context, String verifyToken,com.alibaba.security.realidentity.RPConfig config, RPEventListener listener)设定您需要的UI样式。

常见问题

请参见Android集成常见问题