react-native-2d

Android-SDK-活体检测 (React Native 版本 2D)

快速体验 Demo

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

集成 SDK 到您的工程中

根据您项目依赖的 react-native 库版本，下载对应的 SDK，下载完成解压后将liveness文件夹拷贝至android目录中，与app文件夹同级。

修改android/settings.gradle文件如下，增加对liveness模块的引用

...
include ':app', ':liveness'

如果您项目的com.facebook.react:react-native库版本号大于等于0.60.0，需要在android/gradle.properties文件增加如下配置

android.enableJetifier=true

修改android/app/build.gradle文件，增加库依赖，然后同步gradle完成 SDK 依赖配置

...
android {
    ...
}

dependencies {
    ...
    // 增加以下依赖
    api project(':liveness')
}

如果拉取 aar 失败，建议尝试如下操作：

如果您的 gradle 版本小于 7.0，在项目的根目录下build.gradle增加 maven 仓库：

allprojects {
    repositories {
        ...
        maven { url 'https://public-n3.advai.net/repository/maven-releases/' }
    }
}

如果您的项目 gradle 版本大于7.0，在项目的根目录下settings.gradle增加 maven 仓库:

dependencyResolutionManagement {
    ...
    repositories {
        ...
        maven {
            url 'https://public-n3.advai.net/repository/maven-releases/'
        }
    }
}

如果上述做法仍然无法拉取 aar，您可以通过下方链接下载 aar，然后手动依赖到项目中：

下方链接以 lib 2.1.8 和 core 4.5 为例，修改链接中的版本号可以下载对应的版本。

SDK 版本更新

liveness/build.gradle中有 SDK 依赖的版本(版本记录)，通过修改版本号来更新SDK：

dependencies {
    implementation 'com.android.support:appcompat-v7:28.0.0'
    // You can view the list of SDK versions for updating the SDK at this link
    // http://public-n3.advai.net/repository/maven-releases/ai/advance/mobile-sdk/android/liveness-detection-rn/maven-metadata.xml
    api 'ai.advance.mobile-sdk.android:liveness-detection-rn:2.1.8'
    implementation 'com.android.support.constraint:constraint-layout:2.0.4'
}

快速入门

引入LivenessReactPackage。

在 android/app目录中找到实现了 ReactApplication 的类，默认名称为 MainApplication，增加LivenessReactPackage

import ai.advance.liveness.sdk.rn.LivenessReactPackage;

public class MainApplication extends Application implements ReactApplication {

    private final ReactNativeHost mReactNativeHost = new ReactNativeHost(this) {

     @Override
        protected List<ReactPackage> getPackages() {
            return Arrays.<ReactPackage>asList(
                    new MainReactPackage(), new LivenessReactPackage()
            );
        }
        ...
    }
  ...
}

初始化 SDK。

Market 的可用取值： [Indonesia, India, Philippines, Philippines2, Vietnam, Malaysia, Thailand, BPS, CentralData, Mexico, Singapore, Aksata, Pakistan, Nigeria]

// 最后一个布尔值代表是否开通的 Global 服务，如果是则设置为 true，反之为 false。
NativeModules.LivenessModule.initSDKByLicense("your market",false);

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

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

NativeModules.LivenessModule.setDetectionLevel(GuardianLivenessDetectionSDK.DetectionLevel.EASY);

校验 license。

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

NativeModules.LivenessModule.setLicenseAndCheck("your license",(successCode)=>{
 // license 校验成功，可以启动活体检测
},(errorCode)=>{
    // license 不可用，过期/格式错误/appId未备案
})

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

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

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

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

示例代码：

NativeModules.LivenessModule.startLiveness(
        (successJsonData)=>{
        // 该回调表示活体检测成功
        },
        (failedJsonData)=>{
         // 该回调表示活体检测失败或者用户取消了检测
        }
      )
    }}

successJsonData数据结构：

回调参数	类型	解释
livenessId	String	本次活体检测图片的 id
livenessBase64Str	String	本次活体检测采集的 base64 格式的图片
transactionId	String	追踪本次活体检测日志的事务id
isPay	Boolean	本次活体检测调用是否收费

failedJsonData 数据结构

回调参数	类型	解释
transactionId	String	追踪本次活体检测日志的事务id
errorMessage	String	本次活体检测失败的原因
errorCode	String	错误码

动作顺序说明

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

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

// 第一个布尔值代表是否打乱传入的动作顺序，true 代表打乱顺序。
//  动作数组支持配置任意个动作
// POS_YAW：摇头
// MOUTH：张嘴
// BLINK：眨眼
NativeModules.LivenessModule.setActionSequence(true,["POS_YAW", "MOUTH", "BLINK"]);

自定义返回的图像尺寸

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

自定义动作时间

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

NativeModules.LivenessModule.setActionTimeoutMills(10000);

用户绑定(强烈建议)。

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

NativeModules.LivenessModule.bindUser("your user id")

开启遮挡检测

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

NativeModules.LivenessModule.isDetectOcclusion(true)

国际化

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

若没有跟随系统语言自动切换，请检查手机语言设置，确保【地区】和【语言】均已切换至对应的语言。
若仍然出现语言国际化问题，同时 app 仅支持某种语言，可以通过在android/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 包冲突错误，请将android/app/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	授权请求网络失败	翻墙后重试
CHECKING_BAD_NETWORK	动作结束后图像上传网络请求失败	翻墙后重试
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

授权请求网络失败

翻墙后重试

CHECKING_BAD_NETWORK

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

翻墙后重试

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)或联系我们添加