获得离线活体检测SDK后,您可以参考本文档将SDK集成到您的Android应用中。

在工程中导入SDK

  1. 解压离线活体SDK-ANDROID.zip包,将以下Android依赖包引入到您的应用工程中。
    fastjson-1.2.62.jar
    greensdk-4.9.0-green-release.aar
    MiddleTierSDK-external-release-5.5.13874142.aar
    SecurityBodySDK-external-release-5.5.28-preInstall.aar
    SecurityGuardSDK-external-release-5.5.28-preInstall.aar

    具体请参见以下步骤:

    1. 设定引入的本地库所在路径。将需要引入的依赖包都放在./libs目录下,包含所有需要的库。
    2. 配置gradle
      repositories {
              flatDir {
                  dirs './libs'
              }
          }
    3. build.gradle文件中引入以下依赖包。
      dependencies {
          // 本地包依赖。
          implementation fileTree(dir: './libs', include: ['*.jar','*.aar'])
          // 远程包依赖。
          implementation ('com.alibaba.android.mnnkit:core:0.0.5') {
              exclude module: "fastjson"
          }
      }
    4. 解压jniLibs-libc++_shared.zip包到jniLibs目录。
      目录

      目前离线实人SDK版本已经移除了armeabi架构的so库文件,如遇到初始化报-1004 错误,在aligreen-license.bin确认没问题的前提下,可能是 abiFilters配置不正确,需要在SDK应用的build.gradle中进行以下配置。

      android {
          defaultConfig {
              ndk {
                  abiFilters "armeabi-v7a", "arm64-v8a"
              }
          }
      }
      注意 如果您一定要使用armeabi架构类型,但是又无法升级到v7或v8类型,可以自行解压aremabi.zipjniLibslibc++_shared.zip文件,使用里面的armeabi solibc++_shared.so库文件代替。
    5. 配置签名。

      代码示例

      signingConfigs {
              release {
                  // 修改为您的release签名文件信息。
                  storeFile file('test.jks')
                  storePassword "test1234"
                  keyAlias "key0"
                  keyPassword "test1234"
                  // 修改为您的release签名文件信息。
      
                  v1SigningEnabled true
                  v2SigningEnabled true
              }
              debug { 
                  // 修改为您的release签名文件信息。
                  storeFile file('test.jks')
                  storePassword "test1234"
                  keyAlias "key0"
                  keyPassword "test1234"
                  // 修改为您的debug签名文件信息。
      
                  v1SigningEnabled true
                  v2SigningEnabled false
              }
          }
      注意 在debug模式下,v1签名为true,v2为false。
  2. 导入yw_1222_xxx.jpg文件到您的应用工程中的res/drawable/目录下。
    注意 如果没有这个文件夹,请先在您的工程中创建,否则将无法正常工作。
    如果在安卓工程打包时启用了shrinkResources true,还需要在res/raw/keep.xml文件中添加以下内容:
    <resources xmlns:tools="http://schemas.android.com/tools" tools:keep="@drawable/yw_1222_*"/>
  3. 导入aligreen-license.bin文件到您的工程中的assets目录。
    注意 如果没有这个文件夹,请先在您的工程中创建,否则将无法完成初始化。
  4. 在离线活体检测SDK的清单文件AndroidManifest.xml中添加以下权限:
    • <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    • <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
    • <uses-permission android:name="android.permission.CAMERA" />
  5. 如果开启了混淆(minifyEnabled true)功能,需要在混淆配置文件proguard-rules.pro中添加以下配置:
    -keep class com.alibaba.wireless.security.**{*;}
    -keep class com.alibaba.security.biometrics.**{*;}

使用SDK

  1. 使用离线活体检测SDK之前,请您先执行以下操作调用初始化接口:
    // 确保初始化之前需要获取sdcard权限。
         if (ActivityCompat.checkSelfPermission(MainActivity.this, Manifest.permission.WRITE_EXTERNAL_STORAGE) != PackageManager.PERMISSION_GRANTED) {
                ActivityCompat.requestPermissions(this, new String[]{Manifest.permission.WRITE_EXTERNAL_STORAGE}, requestCode);
            } else {
                AligreenSdkManager.getInstance().init(MainActivity.this, new InitListener() {
                    @Override
                    public void onFinish(int i, String s) {
    
                    }
                });
            }
  2. 调用以下接口进行人脸采集。
    /**
     * 此接口使用默认配置来进行人脸采集。
     * 默认 2 个动作
     * 默认显示导航(预备)页
     * 默认翻拍检测阈值为 82.0
     */
    AligreenSdkManager.getInstance().startBiometricsDetect(Context, BiometricsDetectListener);
    /**
     * 此接口可自定义多个配置来进行人脸采集。
     * 配置动作个数为 0、1、2
     * 配置是否显示导航(预备)页
     * 配置翻拍检测阈值(阈值越大意味着越宽松)
     */
    AligreenSdkManager.getInstance().startBiometricsDetect(Context, BiometricsConfig, BiometricsDetectListener);
    BiometricsConfig设置以及回调使用示例:
    // 基于BiometricsConfig.Builder构造配置示例并进行参数设置。
    BiometricsConfig.Builder bioConfigBuilder = new BiometricsConfig.Builder();
    bioConfigBuilder.setActionCount(int actionCount); // 设置动作个数。
    bioConfigBuilder.setShowTutorial(boolean showTutorial); // 是否显示导航(预备)页。
    bioConfigBuilder.setRecapThreshold(float recapThreshold); // 翻拍检测阈值(阈值越大意味着越宽松)。
    
    // 调用活体识别接口。
    AligreenSdkManager.getInstance().startBiometricsDetect(context, bioConfigBuilder.build(), new BiometricsDetectListener() {
        @Override
        public void onStart() {
            // 开始人脸采集。
        }
    
        @Override
        public void onShow() {
            // 活体识别页面显示。
        }
    
        @Override
        public void onDismiss() {
            // 活体识别页面关闭。
        }
    
        @Override
        public void onFinish(BiometricsResult result) {
            // 人脸采集结束。
        }
    });
  3. 获取人脸结果。您可以在BiometricsDetectListener的onFinish方法中获取采集结果。
    说明 已经废弃的旧的回调接口是FaceImageResultCallback,且只有onFinish方法,建议升级使用BiometricsDetectListener。另外BiometricsDetectListener不再将人脸图片保存在手机内存中,您可以拿到图片二进制数据后自行处理。
    BiometricsResult类实例使用示例:
    /**
     * 获取所有动作图片数据。每个动作可能会有多张图片。
     * @return List<List<byte[]>>
     */
    public List<List<byte[]>> getAllActionImagesData();
    /**
     * 获取指定的某个(按顺序,第一个动作索引是0)动作的所有图片数据。每个动作可能会有多张图片。
     * @return List<byte[]>
     */
    public List<byte[]> getActionImagesData();
    /**
     * 获取人脸大图图片数据。
     * @return byte[]
     */
    public byte[] getBigImageData();
    /**
     * 获取错误码。
     * @return int
     */
    public int getCode();

UI定制

离线活体SDK提供了UI定制功能。关于UI定制的详细介绍,请参见UI定制

错误码说明

错误信息 错误代码 说明
OK 0 集成成功。
NATIVE_ERROR -2 客户端上内部错误。一般出现在集成阶段,需检查logcat运行时的日志排查问题原因。
USER_EXIT -4 您手动退出或因识别失败次数大于4次,导致客户端默认退出。
SDK_NOT_INIT -1001 SDK未初始化。一般是由于您未调用初始化接口或初始化时因为没有存储权限导致失败。
GET_LICENSE_ERROR -1002 获取服务端License 失败。
LICENSE_EXPIRED -1003 License已过期。
LICENSE_NOT_RIGHT -1004 License不正确。
ACTION_COUNT_TOO_LARGE -1005 执行动作数量超出上限。
说明 最多执行两个动作。
GET_LICENSE_TIME_ERROR -1006 获取License时间戳出错。

常见问题

在配置时,如果出现报错信息:Manifest merger failed : Attribute application@allowBackup value=(true) from AndroidManifest.xml:12:9-35 is also present at [SecurityGuardSDK-external-release-5.5.28-preInstall.aar] AndroidManifest.xml:23:9-36 value=(false).

处理建议:您需要在AndroidManifest.xml application标签中添加tools:replace="android:allowBackup"。