离线活体检测如何将AndroidSDK集成到应用中-阿里云帮助中心

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

使用说明

SDK联网说明
如果您购买的SDK License非永久有效（例如有效期是1年），那么您的终端用户在使用扫脸功能时手机设备必须连接网络；如果您购买的SDK License永久有效，那么SDK是纯离线的模式，您的终端用户在使用扫脸功能时手机设备可以不连接网络。
SDK功能说明
您从实人认证控制台下载的SDK，默认只有短期试用授权的活体检测功能。如果您需要购买活体检测功能的正式授权（有效期授权或永久授权），请联系阿里云客户经理咨询和开通。

前提条件

已获取正确的Android SDK。

关于离线活体SDK产品功能的详细介绍，请参见离线活体检测SDK。

在工程中导入SDK

解压离线活体SDK-ANDROID.zip包，将以下Android依赖包引入到您的应用工程中。

说明关于如何获取离线活体SDK-ANDROID.zip包，请参见下载离线SDK。

greensdk-x.x.x-green.aar
MiddleTierSDK-external-release-5.5.13874142.aar
SecurityBodySDK-external-release-5.5.15071314.aar
SecurityGuardSDK-external-release-5.5.15071059.aar

具体请参见以下步骤：

设定引入的本地库所在路径。将需要引入的依赖包都放在./libs目录下，包含所有需要的库。

配置gradle。

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

在build.gradle文件中引入以下依赖包。

dependencies {
    // 本地包依赖。
    implementation fileTree(dir: './libs', include: ['*.jar','*.aar'])
    // 远程包依赖。
    implementation("com.squareup.okhttp3:okhttp:3.12.0")    
    implementation("com.squareup.okio:okio:1.16.0")
    }
}

解压jniLibs-libc++_shared.zip包到jniLibs目录，并引入arm64-v8a，armeabi-v7a文件夹到jniLibs目录下。
目前离线实人SDK版本已经移除了armeabi架构的so库文件，如遇到初始化报-1004 错误，在aligreen-license.bin确认没问题的前提下，可能是abiFilters配置不正确，需要在SDK应用的build.gradle中进行以下配置。
```
android {
    defaultConfig {
        ndk {
            abiFilters "armeabi-v7a", "arm64-v8a"
        }
    }
}
```
重要如果您一定要使用armeabi架构类型，但是又无法升级到v7或v8类型，可以自行解压aremabi.zip、jniLibslibc++_shared.zip文件，使用里面的armeabi so、libc++_shared.so库文件代替。

配置签名。

代码示例

signingConfigs {
        release {
            // 修改为您的Release签名文件信息。
            storeFile file('test.jks')
            storePassword "test1234"
            keyAlias "key0"
            keyPassword "test1234"
            // 修改为您的Release签名文件信息。

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

            v1SigningEnabled true
            v2SigningEnabled false
        }
    }

重要在Debug模式下，v1签名为true，v2为false。

如果出现如下错误，需要在AndroidManifest.xml application标签中加上属性tools:replace="android:allowBackup"

导入yw_1222_xxx.jpg文件到您的应用工程中的目录下。
重要如果没有这个文件夹，请先在您的工程中创建，否则将无法正常工作。
如果在安卓工程打包时启用了shrinkResources true，还需要在res\raw\keep.xml文件中添加以下内容：
```
<resources xmlns:tools="http://schemas.android.com/tools" tools:keep="@drawable/yw_1222_*"/>
```
导入aligreen-license.bin、model_live.bin文件到应用的assets目录。
重要如果没有这个文件夹，请先在您的工程中创建，否则将无法完成初始化。
在离线活体检测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" />
如果开启了混淆（minifyEnabled true）功能，需要在混淆配置文件proguard-rules.pro中添加以下配置：
```
-keep class com.alibaba.wireless.security.**{*;}
-keep class com.alibaba.security.biometrics.**{*;}
```

使用SDK

基础能力

使用离线活体检测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初始化接口。
        }

调用初始化接口。
从阿里云控制台下载到的SDK默认包含了所有算法模型，所以包体积比较大（约8.5 MB），考虑按需使用和控制包体积两个方面，目前提供两种接入方式：
- 内置模型模式
  指SDK里内置相应模型后集成到业务App中，这种集成模式会增加App的体积，但是终端用户可以直接使用扫脸功能，不需要动态下载模型。永久授权的License必须使用内置模式。
- 动态下载模式：
  指SDK里不内置相应模型，而是在终端用户使用扫脸功能时，联网动态下载，这种集成模式可以控制App增加的体积，但是需要用户在手机联网状态下动态下载模型后开始扫脸。目前翻拍模型支持动态下载。
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.bin文件，将其拷贝到接入应用的assets文件夹中。model_live.bin是指翻拍检测基本能力，必须要拷贝，表示您的终端用户在做交互动作时可以实时判断是否攻击。
  说明如果您购买的是永久授权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.bin文件到assets中。这种接入模式只适用于SDK的License是非永久有效的（例如1年有效期）。

调用以下接口进行人脸采集。

/** 
* 此接口可自定义多个配置来进行人脸采集。 
* 配置AES加密密钥，密钥由接入方传入，必填，活体采集的图片默认加密 
* 配置动作个数为 0、1、2 
* 配置是否显示导航（预备）页 
* 配置翻拍检测阈值（阈值越大意味着越宽松） 
*/
AligreenSdkManager.getInstance().startBiometricsDetect(Context, BiometricsConfig, BiometricsDetectListener);

BiometricsConfig设置以及回调使用示例：

// 基于BiometricsConfig.Builder构造配置示例并进行参数设置。
BiometricsConfig.Builder bioConfigBuilder = new BiometricsConfig.Builder();
bioConfigBuilder.setSecret(SECRET);// 必填，aes加密密钥。
bioConfigBuilder.setActionCount(int actionCount); // 设置动作个数，最大支持2个动作。
bioConfigBuilder.setShowTutorial(boolean showTutorial); // 是否显示导航（预备）页。
bioConfigBuilder.setRecapThreshold(float recapThreshold); // 翻拍检测阈值（阈值越大意味着越宽松）。

// 设置指定活体动作，可选设置，最大支持2个动作。
 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);

// 调用活体识别接口。
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) {
        // 人脸采集结束。
    }
});

获取人脸结果。您可以在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();// JPG格式，需要使用aes，对应的secret解密。默认加密。
/**
 * 获取错误码。
 * @return int
 */
public int getCode();

采集图片并解密。

AESUtils.decrypt(result.getBigImageData(), SECRET)

SDK包体积优化

目前离线活体检测SDK携带了算法模型，这些算法模型会占用较大的包体积，为了对包体积进行优化，我们提供了模型动态下载的能力，使用该能力需要具备以下前提条件：

License非永久授权。
您的终端用户手机设备支持联网，且网络环境良好（不建议在2G、3G这种弱网环境中）。

说明如果您购买的是永久授权的License，则只能使用内置模型的接入方式；如果您购买的是非永久授权的License，则可以使用模型动态下载的方式。使用该方式时，不需要拷贝model_live.bin至工程assets目录。

支持下载的模型：翻拍模型model_live.bin

在调用活体检测能力之前调用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参数。调用接口进行人脸采集时，必须设置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"。