kmm-2d

Android-SDK-活体检测（Kotlin Multiplatform Mobile 2D）

快速体验 Demo

安装 CV-Demo.apk 到您的手机，使用测试账号进行登录。

集成 SDK 到您的工程中

如果您想使用默认的 UI 样式，则按照如下方式，在项目的 /shared/build.gradle.kts 中添加依赖：

...
android {
    ...
    dependencies {
        api("ai.advance.mobile-sdk.android:liveness-detection:2.1.8")
        api("androidx.appcompat:appcompat:1.6.1")
        api("androidx.constraintlayout:constraintlayout:2.1.4")
        // 默认 UI 模块
        api(":ai.advance.mobile-sdk.android:liveness-detection-ui:2.1.6@aar")
    }
}

如果您需要自定义 UI，则按照如下步骤进行：

点击此链接下载 UI 模块源码并解压。
拷贝liveness-kotlin/liveness/src/main/kotlin/ai文件夹至 shared/src/androidMain/kotlin目录。
拷贝liveness-kotlin/liveness/src/main/res文件夹至shared/src/androidMain/，如果 androidMain 文件夹中已存在 res 文件夹，则需要手动将两个 res 文件夹中的内容合并。
拷贝liveness-kotlin/liveness/src/main/AndroidManifest.xml文件至shared/src/androidMain/，如果androidMain文件夹中已存在AndroidManifest.xml文件，则打开已有的文件，在节点中注册LivenessActivity。

打开根目录下settings.gradle.kts文件，增加 maven 仓库配置：

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://public-n3.advai.net/repository/maven-releases/")
        }
    }
}

打开/shared/build.gradle.kts，增加依赖项：

    ...
android {
    ...
    dependencies {
        api("ai.advance.mobile-sdk.android:liveness-detection:2.1.8")
        api("androidx.appcompat:appcompat:1.6.1")
        api("androidx.constraintlayout:constraintlayout:2.1.4")
    }
}

SDK 版本更新

快速入门

初始化SDK。

// 最后一个布尔值代表是否开通的 Global 服务，如果是则设置为 true，反之为 false。
// init 方法在 application 中调用
GuardianLivenessDetectionSDK.init(this,your market,false);

设置动作难度（在 setLicenseAndCheck() 方法之前调用，否则不生效）

您可以根据业务要求指定动作检测的难度(EASY，NORMAL，HARD)，默认为 NORMAL

GuardianLivenessDetectionSDK.setDetectionLevel(GuardianLivenessDetectionSDK.DetectionLevel.EASY);

校验 license

license 由您的服务端调用我们 openAPI 获取，启动活体检测之前调用

String license = "xxx";
String checkResult = GuardianLivenessDetectionSDK.setLicenseAndCheck(license);
if ("SUCCESS".equals(checkResult)) {
    // license 有效
   startLivenessActivity();
} else {
    // license 不可用，过期/格式错误/appId未备案
}

启动活体检测与获取检测结果。

SDK 默认不检查相机权限，如果您希望权限的申请交由 SDK 处理，可在 SDK 初始化方法调用后，调用如下方法，则 LivenessActivity 中会执行权限申请的操作：

GuardianLivenessDetectionSDK.letSDKHandleCameraPermission();

每次进行活体检测成功后，会返回唯一的 livenessId 和本次检测的 600*600 像素的清晰正面照片。

您需要将 livenessId 传给您的服务端，由服务端调用 openAPI 获取本次检测的分值。

您可以通过 SDK 提供的方法直接获取图片，也可以由服务端调用 openAPI 获取。

/**
 * 请求状态码
 */
public static final int REQUEST_CODE_LIVENESS = xxxx;

/**
 * 启动活体检测
 */
private void startLivenessActivity() {
    Intent intent = new Intent(this, LivenessActivity.class);
    startActivityForResult(intent, REQUEST_CODE_LIVENESS);
}

/**
 * 获取检测结果
 */
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    if (requestCode == REQUEST_CODE_LIVENESS) {
        if (LivenessResult.isSuccess()) {// 活体检测成功
            String livenessId = LivenessResult.getLivenessId();// 本次活体id
            boolean pay = LivenessResult.isPay();// 是否收费
            Bitmap livenessBitmap = LivenessResult.getLivenessBitmap();// 本次活体图片
        } else {// 活体检测失败
            String errorCode = LivenessResult.getErrorCode();// 失败错误码
            String errorMsg = LivenessResult.getErrorMsg();// 失败原因
            String transactionId = LivenessResult.getTransactionId(); // 流水号，可用于排查问题
            ...
        }
    }
}

动作顺序说明

默认的动作顺序是 [眨眼]->[摇头]，如需自定义动作顺序请参考如下代码：

在启动LivenessActivity页面前调用如下方法：

// 第一个布尔值代表是否打乱传入的动作顺序，true 代表打乱顺序。
GuardianLivenessDetectionSDK.setActionSequence(true,Detector.DetectionType.POS_YAW, Detector.DetectionType.MOUTH, Detector.DetectionType.BLINK);

自定义返回的图像尺寸

// 支持设置的入参范围：[300,1000]，单位：像素
GuardianLivenessDetectionSDK.setResultPictureSize(600);

返回多张图片(默认关闭)

支持在每个动作分别采集一张图像，如果打开此开关，由于额外采集了多张图片，会导致 SDK 运行时内存占用提升，如果您的 App 本身已经占用较多内存，则打开此项配置可能会引发内存溢出，请谨慎选择。

GuardianLivenessDetectionSDK.capturePictureQueue(true);

获取图片序列(活体检测成功后获取)：

List<String> imageSequenceList = LivenessResult.getImageSequenceList();

自定义动作时间

支持自定义动作的检测时间，设置后所有动作都生效，单位：毫秒

GuardianLivenessDetectionSDK.setActionTimeoutMills(10000);

用户绑定(强烈建议)。

您可以通过该方法将自己的用户唯一标识传给我们，我们会根据该标识建立映射关系。当遇到问题时，方便同我们进行日志追踪。

GuardianLivenessDetectionSDK.bindUser(String userId)

开启遮挡检测

遮挡检测默认是关闭状态，如需开启遮挡检测，请在初始化SDK之后调用如下方法设置

GuardianLivenessDetectionSDK.isDetectOcclusion(true)

国际化

SDK 支持中文，英文，印尼文，越南语，泰国语，印地语，西班牙语七种语言/语音，跟随手机系统语言自动切换，无需代码设置。

若没有跟随系统语言自动切换，请检查手机语言设置，确保【地区】和【语言】均已切换至对应的语言。
若仍然出现语言国际化问题，同时 app 仅支持某种语言，可以通过在build.gradle中增加如下配置，过滤掉不需要的语言

android {
    defaultConfig {
        ...
        resConfigs("in-rID") // 以仅支持印尼语为例
    }

}

运行时权限

本 SDK 需要如下权限，并且已经在 aar 的清单文件中做了配置。

<uses-feature android:name="android.hardware.camera" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />

关于 App Bundle 打包

SDK 中包含 .so 文件，为了减少包大小，在上架 Google Play 时可以选择使用 Bundle 打包，请验证打包后的 APK 在各个架构的手机上都可以运行，如果出现提示【该设备不支持】，则表示组装 APK 时缺失了 .aar 中的 .so 文件。

代码混淆

SDK 已经做好了代码混淆，无需额外增加配置。

关于Androidx

考虑到 Androidx 与 support 包的互斥，本 SDK 的 .aar 全部是 support 包，如果您的项目是 androidX 类包，编译时遇到提示 support 包冲突错误，请在您项目的根目录下的gradle.properties文件中增加下述配置，重新编译项目即可：

android.enableJetifier=true

SDK 兼容性

最低 Android 版本：4.4 (API Level:19)
SDK 编译版本：API Level：32
额外依赖的第三方库：无
支持的 CPU 架构：armeabi-v7a，arm64-v8a，x86，x86_64，armeabi
SDK 包大小：1.3MB 模型文件 + 每种 CPU 架构约 0.8MB
采集图像大小：默认采集图像分辨率 600px*600px，大小约为 300KB，支持自定义图像尺寸范围：300px~1000px

Error Code:

错误码	解释	解决办法
FACE_MISSING	检测过程中人脸丢失	/
ACTION_TIMEOUT	动作超时	/
MULTIPLE_FACE	检测过程中出现多张人脸	/
MUCH_MOTION	检测过程中动作幅度过大	/
AUTH_BAD_NETWORK	授权请求网络失败	连接 VPN 后重试
CHECKING_BAD_NETWORK	动作结束后图像上传网络请求失败	连接 VPN 后重试
DEVICE_NOT_SUPPORT	该设备不支持活体检测	设备无前置摄像头或不可用
USER_GIVE_UP	用户中途放弃检测	/
UNDEFINED	未定义的其他错误类型	/
NO_RESPONSE	请求网络超时	1.请检查您的网络; 2.请检查是否调用了 init 方法； 3.请确认 license 检查返回的是 SUCCESS
AUTH_PARAMETER_ERROR	授权请求参数错误	请检查初始化方法传入的 key 是否为 SDK 的，并且确保 Market 匹配
AUTH_IAM_FAILED	包名未备案	在 SaaS 上自主配置(Personal Management -> ApplicationId Management)或联系我们添加

错误码

解释

解决办法

FACE_MISSING

检测过程中人脸丢失

ACTION_TIMEOUT

动作超时

MULTIPLE_FACE

检测过程中出现多张人脸

MUCH_MOTION

检测过程中动作幅度过大

AUTH_BAD_NETWORK

授权请求网络失败

连接 VPN 后重试

CHECKING_BAD_NETWORK

动作结束后图像上传网络请求失败

连接 VPN 后重试

DEVICE_NOT_SUPPORT

该设备不支持活体检测

设备无前置摄像头或不可用

USER_GIVE_UP

用户中途放弃检测

UNDEFINED

未定义的其他错误类型

NO_RESPONSE

请求网络超时

1.请检查您的网络;
2.请检查是否调用了 init 方法；
3.请确认 license 检查返回的是 SUCCESS

AUTH_PARAMETER_ERROR

授权请求参数错误

请检查初始化方法传入的 key 是否为 SDK 的，并且确保 Market 匹配

AUTH_IAM_FAILED

包名未备案

在 SaaS 上自主配置(Personal Management -> ApplicationId Management)或联系我们添加