upgrade

活体检测 SDK 升级指南 (3D)

V3.6.19（2026.10.13）

版本介绍

解决摄像头id 缓存为-1 问题：在获取摄像头异常情况下可能会缓存摄像头 id 为-1，导致多次开启活体仍然无法正常打开相机。

版本升级

将依赖版本号修改为3.6.19:

dependencies {
  ...
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.6.19'
}

V3.6.18（2026.08.20）

版本介绍

LivenessResult 增加 getSupportApplicationIds 方法，可以调用此方法获取 license 中配置的 applicationid 列表，来辅助排 APPLICATION_ID_NOT_MATCH 错误

版本升级

将依赖版本号修改为3.6.18:


xxxxxxxxxx
dependencies {
  ...
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.6.18'
}

V3.6.17（2026.08.04）

版本介绍

修复主线程 Handler 为 null 问题。
修复相机预览更新阶段的数组越界崩溃。完善实体类 ProGuard / R8 保留规则。

版本升级

将依赖版本号修改为3.6.17:


xxxxxxxxxx
dependencies {
  ...
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.6.17'
}

V3.6.16（2026.07.08）

版本介绍

修复极少情况下图片黑边问题

版本升级

将依赖版本号修改为3.6.16:


xxxxxxxxxx
dependencies {
  ...
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.6.16'
}

V3.6.15（2026.06.26）

版本介绍

适配 android 16。
修复检测过程中 C++ 空指针异常。

活体检测支持横屏模式。

UI SDK 中默认使用竖屏模式。如果您需要支持横屏模式，可以在宿主应用的 AndroidManifest.xml 中重新声明该 activity，如下所示：


xxxxxxxxxx
<activity
  android:name="aai.liveness.activity.LivenessActivity"
  android:launchMode="singleTop"
  android:screenOrientation="fullSensor"
  android:configChanges="orientation|screenSize|screenLayout|smallestScreenSize"
  android:theme="@style/Theme.AppCompat.Light.NoActionBar"
  tools:replace="android:screenOrientation"/>

您也可以自定义活体检测页面的横竖屏模式 UI。但是我们仍然建议您保持竖屏模式，这在小屏手机上体验更好。在大屏设备上（OS 版本 > 36 & 宽度 > 600dp），即使声明了竖屏模式，设备也会忽略此设置，并根据设备的物理方向自动切换。

版本升级

将依赖版本号修改为3.6.15:


xxxxxxxxxx
dependencies {
  ...
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.6.15'
}

V3.6.14（2026.04.09）

版本介绍

修复视频录制时偶发的 ANR。
修复相机控件 onLayout 方法中因锁竞争引发的 ANR。
修复调用 setAutoFocus 和 getNumberOfCameras 方法造成的 ANR。

版本升级

将依赖版本号修改为3.6.14:


xxxxxxxxxx
dependencies {
  ...
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.6.14'
}

V3.6.13（2026.02.27）

版本介绍

修复了多线程导致的相机使用问题

版本升级

将依赖版本号修改为3.6.13:


xxxxxxxxxx
dependencies {
  ...
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.6.13'
}

V3.6.12（2026.02.09）

版本介绍

修复了相机 ANR 问题

版本升级

将依赖版本号修改为3.6.12:


xxxxxxxxxx
dependencies {
  ...
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.6.12'
}

V3.6.11（2026.01.29）

版本介绍

修复一些相机问题

版本升级

将依赖版本号修改为3.6.11:


xxxxxxxxxx
dependencies {
  ...
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.6.11'
}

V3.6.10（2025.12.22）

版本介绍

去掉Mac地址和IMEI采集

版本升级

将依赖版本号修改为3.6.10:


xxxxxxxxxx
dependencies {
  ...
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.6.10'
}

V3.6.9（2025.12.17）

版本介绍

修复相机预览导致的ANR
修复关闭相机导致的ANR
修复JSONObject导致的并发问题
修复JNI崩溃

版本升级

将依赖版本号修改为3.6.9:


xxxxxxxxxx
dependencies {
  ...
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.6.9'
}

V3.6.8（2025.11.24）

版本介绍

分辨率选择修复，解决 no_best_image 问题
JNI 崩溃修复

版本升级

将依赖版本号修改为3.6.8:


xxxxxxxxxx
dependencies {
  ...
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.6.8'
}

V3.6.7（2025.11.18）

版本介绍

修复活体完成时偶现的流程卡住问题
修复部分机型上提示活体不支持的问题

版本升级

将依赖版本号修改为3.6.7:


xxxxxxxxxx
dependencies {
  ...
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.6.7'
}

V3.6.6（2025.11.10）

版本介绍

解决在低端设备上打开相机导致的ANR问题

版本升级

将依赖版本号修改为3.6.6:


xxxxxxxxxx
dependencies {
  ...
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.6.6'
}

V3.6.5（2025.11.07）

版本介绍

适配Android15

版本升级

将依赖版本号修改为3.6.5:


xxxxxxxxxx
dependencies {
  ...
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.6.5'
}

V3.6.4（2025.9.09）

版本介绍

修复崩溃：在部分手机上，打开相机时偶现的ANR

版本升级

将依赖版本号修改为3.6.4:


xxxxxxxxxx
dependencies {
  ...
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.6.4'
}

V3.6.3（2025.8.01）

版本介绍

修复崩溃：因并发问题导致的偶现崩溃问题

版本升级

将依赖版本号修改为3.6.3:


xxxxxxxxxx
dependencies {
  ...
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.6.3'
}

V3.6.2（2025.6.03）

版本介绍

优化分辨率选择，确保在绝大多数手机上进行活体检测时，能够保持合理的手机距离。

版本升级

将依赖版本号修改为3.6.2:


xxxxxxxxxx
dependencies {
  ...
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.6.2'
}

V3.6.1（2025.5.28）

版本介绍

解决因分辨率选择导致用户在部分机型上需要将手机放远才能进行活体识别的问题。

版本升级

将依赖版本号修改为3.6.1:


xxxxxxxxxx
dependencies {
  ...
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.6.1'
}

V3.6.0（2025.4.2）

版本介绍

支持 Android 15 16 KB 的页面大小
优化计费相关规则

版本升级

将依赖版本号修改为3.6.0:


xxxxxxxxxx
dependencies {
  ...
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.6.0'
}

设置 SignatureId（可选功能，若不设置此 id 或设置为空，则维持 livenessId 方式不变）
在已知的下述情况下，AAI 生成的 livenessId 未能传达到您的服务端，这些 livenessId 的结果就会丢失。为了解决此问题，您的后端可以调用 AAI 接口生成 SignatureId 并传给 SDK。SignatureId 可用于获取活体分数，与 livenessId 具备等效的功能。
1. 活体图片上传过程中，用户点击返回键离开页面
2. 活体成功后，App 发生意外（如网络异常，App 异常等）未能将 livenessId 传给服务端

请注意：SignatureId 可为空，但不可重复使用


xxxxxxxxxx
GuardianLivenessDetectionSDK.setSignatureId(signatureId);

V3.5.1（2025.1.23）

New Features

优化墨西哥网络
修复已知问题

Migration Guides

将依赖版本号修改为3.5.1:


xxxxxxxxxx
dependencies {
  ...
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.5.1'
}

V3.5.0（2024.12.24）

版本介绍

增加安全模块，提升安全性

版本升级

将依赖版本号修改为3.5.0:


xxxxxxxxxx
dependencies {
  ...
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.5.0'
}

V3.4.1（2024.10.9）

版本介绍

修复bug

版本升级

将依赖版本号修改为3.4.1:


xxxxxxxxxx
dependencies {
  ...
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.4.1'
}

V3.4.0（2024.9.4）

版本介绍

调整UI交互和提示语，以提升用户体验。
提升活体近脸采集阶段性能，在无人脸和多人脸情况下给出相应提示，而非直接退出，进一步提高用户通过率，用户不再接收到 FACE_MISSING 和 MULTIPLE_FACE 错误码。
优化活体采集过程，去掉 3 秒等待时间并减少图像上传阶段的耗时。
增强防 Hook 注入攻击的安全性。
targetSdk 升级至 34

版本升级

将依赖版本号修改为3.4.0:


xxxxxxxxxx
dependencies {
  ...
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.4.0'
}

V3.3.1（2024.7.22）

版本介绍

修复蓝牙可能导致的安卓12以上的崩溃

版本升级

将依赖版本号修改为3.3.1:


xxxxxxxxxx
dependencies {
  ...
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.3.1'
}

V3.3.0（2024.5.31）

版本介绍

解决报毒问题
活体 SDK 被 VirusTotal 上部分平台误报存在病毒，如果您的应用推广依赖 VirusTotal 的检测结果，建议您升级到此版本
- 如果您由于 SDK 报毒问题集成过某些特定版本，导致您修改了导入的 SDK 类路径以适配这些版本，在集成 3.3.0 时，您可以还原这些改动，SDK 的类路径会固定为 aai.liveness.**
- 如果之前集成的特定版本修改过 LivenessView 的名称，在集成 3.3.0 时，请将此类的名称还原为LivenessView
- 3.3.0 是一个标准通用的版本，尽管我们全量修改了内部类的名称以及加密算法，仍然不能完全避免在未来被标记。从 3.3.0 版本开始，我们支持给您打包专属版本(了解专属版本)，专属版本的内部类不会与其他客户产生重复，能更大程度上避免被标记，并且专属版本与标准版本的集成除了版本号的不同，没有其他集成上的差异。
优化活体采集过程的性能，用户使用上的通过率明显提升。

UI 交互调整

当前 3D 活体在整个检测过程中椭圆都是同一种颜色，我们对检测时的状态做了调整，保持静止状态下呈现绿色，其他状态呈现灰色。
如果您想维持之前的交互效果，可以调用下面的方法设置这两种状态下的椭圆颜色


xxxxxxxxxx
mLivenessView.setOvalColor(Color.parseColor("#5BC413"));
mLivenessView.setOvalNormalColor(Color.parseColor("#5BC413"));

支持截取指定时间下的一张审计图


xxxxxxxxxx
 // 在原有审计图的配置上，新增 setRelativeSecondsCaptureAfterCameraLaunched(2.3f) 配置，您可以指定相对于相机打开后的截图时间，单位为秒。如果不调用此项设置，则不会截取本张图
// 新增的这张图存在于原有的图像数组中
GuardianLivenessDetectionSDK.setAuditImageConfig(new AuditImageConfig
        .AuditImageConfigBuilder()
        .setEnableCollectSwitch(true)
        .setImageCaptureInterval(400)
        .setImageMaxNumber(10)
        .setImageWidth(400)
        .setImageQuality(30)
        .setRelativeSecondsCaptureAfterCameraLaunched(2.3f)
        .build());

增加远近景图片上传时间戳
从 3.3.0 版本开始，当您调用后端取分接口时，会额外返回 farImageTime、nearImageTime 分别表示远景图的截取时间戳、近景图的截取时间戳

版本升级

将依赖版本号修改为3.3.0:


xxxxxxxxxx
dependencies {
  ...
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.3.0'
}

V3.2.0（2024.5.17）

版本介绍

视频录制编码优化： 优化了视频录制编码流程,并修复了在各种设备上存在的几个编码问题。这一增强确保在所有支持的设备上都能实现更流畅和更可靠的视频捕捉。
设备智能更新： 设备智能模块已经过更新,以提高性能和准确性。如果您希望删除此模块,请联系我们的技术支持团队以获取帮助和指导。
增强防Hook注入攻击安全性： 通过实施水印和额外的环境检查,我们加强了防范Hook注入攻击的防御。这些措施提供了一层额外的安全性,以保护免受欺诈活动的危害。

版本升级

将依赖版本号修改为3.2.0:


xxxxxxxxxx
dependencies {
  ...
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.2.0'
}

V3.1.5（2024.3.27）

版本介绍

删除 ~~LivenessResult.getLivenessScore()~~ 方法
删除过时类 ~~LivenessCameraView.java~~，整合到 LivenessResult
优化图像处理，图片上传接口包体积大幅度缩减

版本升级

将依赖版本号修改为3.1.5:


xxxxxxxxxx
dependencies {
  ...
  // version log:https://public-n3.advai.net/repository/maven-releases/ai/advance/mobile-sdk/android/liveness-detection/maven-metadata.xml
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.1.5'
}

V3.1.4（2024.3.25）

版本介绍

稳定性提升

版本升级

将依赖版本号修改为3.1.4:


xxxxxxxxxx
dependencies {
  ...
  // version log:https://public-n3.advai.net/repository/maven-releases/ai/advance/mobile-sdk/android/liveness-detection/maven-metadata.xml
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.1.4'
}

V3.1.1（2024.1.23）

版本介绍

增加返回审核图片列表的功能
视频录制功能优化:
1. 显著降低视频文件大小
2. 提高兼容性
3. 增强视频的流畅性
4. 将视频大小固定为 300px*300px

版本升级

将依赖版本号修改为3.1.1:


xxxxxxxxxx
dependencies {
  ...
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.1.1'
}

打开审计图截取功能.

启用这个功能后,我们将根据您的配置在用户移动时捕捉多张图像。


xxxxxxxxxx
GuardianLivenessDetectionSDK.setAuditImageConfig(new AuditImageConfig
                .AuditImageConfigBuilder()
                .setEnableCollectSwitch(true)// 功能开关，默认是关闭
                .setImageCaptureInterval(400)// 最小的截取时间间隔,默认间隔为 400ms
                .setImageMaxNumber(10)// 截取最大图像张数，默认为 10
                .setImageWidth(400)// 图像宽度，默认为 400px
                .setImageQuality(30)// 图像压缩质量必须在[30, 100]范围内,默认值为 30
                .build());

获取审计图像


xxxxxxxxxx
List<LivenessImageData> auditImageList = LivenessResult.getAuditImageList();
// 数据结构
public class LivenessImageData {
  public final String base64Image;// Base64 格式的图片
  public final long timestamp;// 图像截取时间戳
}

视频录制功能

通过启用此功能,SDK 将激活视频录制。在完成活体检测过程后,您可以使用 SDK 方法检索视频文件。视频文件格式为 .mp4。请注意,此视频只能通过 SDK 获得,无法从后端获得。使用视频后,您可以决定是否删除本地文件。


xxxxxxxxxx
GuardianLivenessDetectionSDK.setRecordVideoSwitch(true);
GuardianLivenessDetectionSDK.setMaxRecordVideoSeconds(60);// 最大录制时长为 2 到 60 秒之间,默认为 60 秒。

获取视频文件


xxxxxxxxxx
File videoFile = LivenessResult.getVideoFile(this);

V3.1.0（2023.12.22）

版本介绍

新增闭眼检测功能
新增 eventId 用于排查日志

版本升级

将依赖版本号修改为3.1.0：


xxxxxxxxxx
dependencies {
  ...
  // 版本更新记录请查看：https://public-n3.advai.net/repository/maven-releases/ai/advance/mobile-sdk/android/liveness-detection/maven-metadata.xml
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.1.0'
}

获取 eventId，请务必保存此 id ，用于联系我们进行问题排查


xxxxxxxxxx
// 活体结束后获取，无论成功失败都有此 id   String eventId = LivenessResult.getEventId();

V3.0.9（2023.12.1）

版本介绍

修复 VirusTotal 上所有平台的报警

版本升级

参考此链接

V3.0.7，V3.0.8

V3.0.6（2023.10.11）

版本介绍

支持 cert-pinning

版本升级

将依赖版本号修改为3.0.6：


xxxxxxxxxx
dependencies {
  ...
  // 版本更新记录请查看：https://public-n3.advai.net/repository/maven-releases/ai/advance/mobile-sdk/android/liveness-detection/maven-metadata.xml
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.0.6'
}

V3.0.5（2023.9.5）

版本介绍

删除 GuardianLivenessDetectionSDK.capturePictureQueue()方法，不再支持返回图片序列
删除静态方法 IMediaPlayer.isPlayEnable()，使用mLivenessView.isSoundPlayEnable()替代

增加检测成功后获取近景图的方法：


xxxxxxxxxx
Bitmap nearBitmap = LivenessResult.getNearBitmap();
String nearBase64Str = LivenessResult.getNearBase64Str();

版本升级

将依赖版本号修改为3.0.5：


xxxxxxxxxx
dependencies {
  ...
  // 版本更新记录请查看：https://public-n3.advai.net/repository/maven-releases/ai/advance/mobile-sdk/android/liveness-detection/maven-metadata.xml
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.0.5'
}

V3.0.4（2023.8.1）

版本介绍

bug fix

版本升级

将依赖版本号修改为3.0.4：


xxxxxxxxxx
dependencies {
  ...
  // 版本更新记录请查看：https://public-n3.advai.net/repository/maven-releases/ai/advance/mobile-sdk/android/liveness-detection/maven-metadata.xml
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.0.4'
}

V3.0.3（2023.7.26）

版本介绍

算法检测优化，提高采集到的图片质量

版本升级

将依赖版本号修改为3.0.3：


xxxxxxxxxx
dependencies {
  ...
  // 版本更新记录请查看：https://public-n3.advai.net/repository/maven-releases/ai/advance/mobile-sdk/android/liveness-detection/maven-metadata.xml
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.0.3'
}

V3.0.0/V3.0.1/V3.0.2（2023.7.17）

版本介绍

全新的 3D 检测，防范屏幕攻击
网络安全性提升

版本升级

将依赖版本号修改为3.0.2：


xxxxxxxxxx
dependencies {
  ...
  // 版本更新记录请查看：https://public-n3.advai.net/repository/maven-releases/ai/advance/mobile-sdk/android/liveness-detection/maven-metadata.xml
  implementation 'ai.advance.mobile-sdk.android:liveness-detection:3.0.2'
}

SDK 新增下列可选权限，如您不希望 App 清单中出现下列权限，在您的 App 模块AndroidManifest.xml文件中移除该项权限即可。以ACCESS_FINE_LOCATION为例：<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" tools:node="remove"/>


xxxxxxxxxx
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />

建议将提示语放置到如下图位置(LivenessView 上方)，便于用户查看提示内容
建议缩短提示语长度如下，便于用户理解提示信息
- FACENOTCENTER：Center your face in the frame
- FACENOTSTILL&FACECAPTURE：Hold steady
- FACENOTFRONTAL：Please look straight
- FACEMISSING：Position your face in the frame
- FACESMALL：Move closer
- FACELARGE：Move away

设置活体控件的背景色(请勿在 LivenessView 上覆盖蒙版图，如果已经覆盖，需要移除)


xxxxxxxxxx
mLivenessView.setMaskColor(getResources().getColor(R.color.xxx);

设置活体控件的椭圆框颜色


xxxxxxxxxx
mLivenessView.setOvalColor(getResources().getColor(R.color.xxx));