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

关于离线活体SDK产品功能的详细说明,请参见离线活体检测SDK

使用说明

  • SDK联网说明

    如果您购买的SDK License非永久有效(例如有效期是1年),那么您的终端用户在使用扫脸功能时手机设备必须连接网络;如果您购买的SDK License永久有效,那么SDK是纯离线的模式,您的终端用户在使用扫脸功能时手机设备可以不连接网络。

  • SDK功能说明

    只有SDK版本为4.13.1版本及以上,才同时具备活体检测(终端用户做动作活体并进行翻拍检测后采集到活体人脸图片)和人脸1:1比对能力。人脸1:1比对能力是在4.13.1版本新增的,低于该版本的只具备活体检测功能。

    当您从实人认证控制台下载到的SDK,默认只有短期试用授权的活体检测功能,不具备人脸1:1功能的使用授权。如果您需要购买活体检测功能的正式授权(有效期授权或永久授权),或购买人脸1:1功能的使用授权,您可以联系阿里云客户经理进行咨询和开通,或者通过工单联系我们。

在工程中导入SDK

  1. 解压离线活体SDK-ANDROID.zip包,将以下Android依赖包引入到您的应用工程中。
    fastjson-1.2.62.jar
    greensdk-xxx-xxx-release.aar
    
    // 压缩包提供的是三方保镖版本,可以直接替换成二方版本,需要二方版本升级到6.5.4以上
    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文件到您的应用工程中的目录下。
    注意 如果没有这个文件夹,请先在您的工程中创建,否则将无法正常工作。
    如果在安卓工程打包时启用了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权限:
    // 确保初始化之前需要获取sdcard权限。
         if (ActivityCompat.checkSelfPermission(MainActivity.this, Manifest.permission.WRITE_EXTERNAL_STORAGE) != PackageManager.PERMISSION_GRANTED) {
                ActivityCompat.requestPermissions(this, new String[]{Manifest.permission.WRITE_EXTERNAL_STORAGE}, 0x11);
            } else {
            // 调用init初始化接口。
            }
  2. 调用初始化接口。
    SDK自4.13.1版本开始具备活体检测和人脸1:1能力,包含翻拍模型、人脸1:1模型。从实人认证控制台下载到的SDK默认包含了所有算法模型,所以包体积较大(约30 MB)。考虑按需使用和控制包体积两个方面,目前提供两种接入方式:
    • 内置模型模式

      指SDK里内置相应模型后集成到业务App中,这种集成模式会增加App的体积,但是终端用户可以直接使用扫脸功能,不需要动态下载模型。永久授权的License必须使用内置模式。

    • 动态下载模式:

      指SDK里不内置相应模型,而是在终端用户使用扫脸功能时,联网动态下载,这种集成模式可以控制App增加的体积,但是需要用户在手机联网状态下动态下载模型后开始扫脸。目前翻拍模型、人脸1:1比对模型均支持动态下载。

    1. 使用内置模型。
      /**
       * 初始化方法1。
       * @param Context contxt
       * @param InitListener initListener
       */
      AligreenSdkManager.getInstance().init(MainActivity.this, new InitListener() {
                      @Override
                      public void onFinish(int code, String message) {
      
                      }
                  });

      使用该方式时,需要从控制台下载离线活体SDK-ANDROID.zip并解压。然后在文件夹\SDK包\models\目录中找到model_live.binmodel_feats.bin两个文件,按需将其拷贝到接入应用的assets文件夹中。

      其中,model_live.bin是指翻拍检测基本能力,必须要拷贝,表示您的终端用户在做交互动作时可以实时判断是否攻击;model_feats.bin是指人脸1:1比对能力,如果实际业务不涉及该功能则不需要拷贝该文件。

      说明 如果您购买的是永久授权License,则必须使用该内置模型的集成方式,因为永久授权License的情况下,SDK是纯离线的模式,刷脸过程与阿里云服务器没有交互,无法动态下载模型。
    2. 使用动态下载的模式。
      从服务器上动态下载模型(以减少SDK接入时的包体体积)。
      /**
       * 初始化方法2。
       * @param Context context
       * @param boolean 是否开启模型从线上下载功能(需要用户手机具备网络能力),设置为false时和初始化方法1效果一致。
       * @param InitListener initListener
       */
      AligreenSdkManager.getInstance().init(MainActivity.this, true, new InitListener() {
                      @Override
                      public void onFinish(int code, String message) {
      
                      }
                  });
      说明 因为是从服务器下载模型,所以该方式不需要拷贝model_live.binmodel_feats.bin两个文件到assets中。这种接入模式只适用于SDK的License是非永久有效的(例如1年有效期)。
  3. 调用以下接口进行人脸采集。
    /**
     * 此接口使用默认配置来进行人脸采集。
     * 默认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) {
            // 人脸采集结束。
        }
    });
    // 1:1比对能力。
    // 基于BiometricsConfig.Builder构造配置示例并进行参数设置。
    BiometricsConfig.Builder bioConfigBuilder = new BiometricsConfig.Builder();
    bioConfigBuilder.setSecret(SECRET);//必填,aes加密密钥。
    bioConfigBuilder.setActionCount(int actionCount); // 
    设置动作个数。
    bioConfigBuilder.setShowTutorial(boolean showTutorial); // 是否显示导航(预备)页。
    bioConfigBuilder.setRecapThreshold(float recapThreshold); // 翻拍检测阈值(阈值越大意味着越宽松)。
    
    // 设置指定活体动作,可选设置。
     List<ActionStrategy> actionArrayList = new ArrayList<>();
     actionArrayList.add(ActionStrategy.BLINK); // 请眨眼。
     actionArrayList.add(ActionStrategy.MOUTH); // 张嘴。
     // actionArrayList.add(ActionStrategy.POS_YAW); // 摇头。
    // actionArrayList.add(ActionStrategy.POS_PITCH);// 点头。
    bioConfigBuilder.setActionStrategy(actionArrayList);
    
    
    FaceImage faceImage = new FaceImage(this, path);
    BiometricsConfig config = buildConfig();
    AligreenSdkManager.getInstance().startWithFaceImage(TestMainActivity.this, config, new BiometricsCompareListener() {
                @Override
                public void onStart() {
                }
    
                @Override
                public void onShow() {
                }
    
                @Override
                public void onDismiss() {
                }
    
                @Override
                public void onFinish(FaceScoreResult result) {
                //score:比对分。
                //code:错误码。
                }
            }, faceImage);
  4. 获取人脸结果。您可以在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();
  5. 采集图片并解密。
    AESUtils.decrypt(result.getBigImageData(), SECRET)

SDK包体积优化

目前离线活体检测SDK携带了算法模型,这些算法模型会占用较大的包体积,为了对包体积进行优化,我们提供了模型动态下载的能力,使用该能力需要具备以下前提条件:
  • License非永久授权。
  • 您的终端用户手机设备支持联网,且网络环境良好(不建议在2G、3G这种弱网环境中)。
说明 如果您购买的是永久授权的License,则只能使用内置模型的接入方式;如果您购买的是非永久授权的License,则可以使用模型动态下载的方式。使用该方式时,不需要拷贝model_live.binmodel_feats.bin至工程assets目录。
支持下载的模型:
  • 翻拍模型:model_live.bin
  • 1:1模型:model_feats.bin
在调用活体检测或1:1比对能力之前调用SDK初始化接口init(Context context, boolean isPreDownload, InitListener listener),并将 isPreDownload参数设置为true
/**
 * 预加载模型,如果你为了降低包体积本地没有内置模型,所以需要远程加载模型,在模型没有更新的时候只需要加载一次即可。
 * 建议应用启动时调用,后台异步任务,不阻塞主线程。
 *
 * @param Context context
 * @param boolean 是否开启模型从线上下载功能(需要具备网络能力),设置为false时和初始化方法1效果一致。
 * @param InitListener initListener
 */
AligreenSdkManager.getInstance().init(MainActivity.this, true, new InitListener() {
                @Override
                public void onFinish(int code, String message) {

                }
            });

UI定制

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

错误码说明

错误代码 说明
0 集成成功。
-2 客户端上内部错误。一般出现在集成阶段,需检查logcat运行时的日志排查问题原因。
-4 您手动退出或因识别失败次数大于4次,导致客户端默认退出。
-1001 SDK未初始化。一般是由于您未调用初始化接口或初始化时因为没有存储权限导致失败。
-1002 获取服务端License 失败。
-1003 License已过期。
-1004 License不正确。
-1005 执行动作数量超出上限。
说明 最多执行两个动作。
-1006 获取License时间戳出错。
-1007 未设置secret参数。
-1008 算法初始化失败。
-1009 License不支持1:1比对能力。
-1010 算法模型初始化失败,或模型不存在。
-1011 算法识别错误。
1008 输入人脸图片没有人脸。
1009 输入人脸图片质量差。
1010 输入参数pixelformat不正确。

常见问题

在配置时,如果出现报错信息: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"。