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

快速体验 Demo

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

集成 SDK 到您的工程中

1. 下载SDK，下载完成解压后将liveness文件夹拷贝至android目录中，与app文件夹同级。
   

2. 修改liveness目录下 build.gradle 文件，将rn的版本修改为 3.6.4

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

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

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

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

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

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

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

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

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

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

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

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

     • liveness_lib aar[版本更新记录]：https://public-n3.advai.net/repository/maven-releases/ai/advance/mobile-sdk/android/liveness-detection/3.6.4/liveness-detection-3.6.4.aar
     • core aar [版本更新记录] https://public-n3.advai.net/repository/maven-releases/ai/advance/mobile-sdk/android/core/6.0.1/core-6.0.1.aar
     • telemetry aar:https://public-n3.advai.net/repository/maven-releases/ai/advance/mobile-sdk/android/telemetry/1.4.2/telemetry-1.4.2.aar

SDK 版本更新

查看版本更新说明

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

xxxxxxxxxx
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/maven-metadata.xml
    api 'ai.advance.mobile-sdk.android:liveness-detection:3.6.4'
    implementation 'com.android.support.constraint:constraint-layout:2.0.4'
}

合规声明

点击查看合规声明

快速入门

1. 引入LivenessReactPackage。

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

     xxxxxxxxxx
     import aai.liveness.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()
               );
           }
           ...
       }
       ...
     }
     

2. 初始化 SDK。

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

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

3. 设置 SignatureId（可选功能，若不设置此 id 或设置为空，则维持 livenessId 方式不变）

   在已知的下述情况下，AAI 生成的 livenessId 未能传达到您的服务端，这些 livenessId 的结果就会丢失。为了解决此问题，您的后端可以调用 AAI 接口生成 SignatureId 并传给 SDK。SignatureId 可用于获取活体分数，与 livenessId 具备等效的功能。

   xxxxxxxxxx
   1. 活体图片上传过程中，用户点击返回键离开页面
   2. 活体成功后，App 发生意外（如网络异常，App 异常等）未能将 livenessId 传给服务端
   

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

   xxxxxxxxxx
   NativeModules.LivenessModule.setSignatureId(signatureId);
   

4. 设置检测超时时长

   xxxxxxxxxx
   // 支持设置的入参范围：[10000,60000]，单位：毫秒。默认50000
   NativeModules.LivenessModule.set3DLivenessTimeoutMills(50000);      
   

5. 自定义返回的图像尺寸

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

6. 用户绑定(强烈建议)。

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

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

7. 开启遮挡检测

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

   xxxxxxxxxx
   NativeModules.LivenessModule.isDetectOcclusion(true)
   

7. 校验 license。

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

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

8. 设置 SignatureId（可选功能，若不设置此 id 或设置为空，则维持 livenessId 方式不变）

   在已知的下述情况下，AAI 生成的 livenessId 未能传达到您的服务端，这些 livenessId 的结果就会丢失。为了解决此问题，您的后端可以调用 AAI 接口生成 SignatureId 并传给 SDK。SignatureId 可用于获取活体分数，与 livenessId 具备等效的功能。

   xxxxxxxxxx
   1. 活体图片上传过程中，用户点击返回键离开页面
   2. 活体成功后，App 发生意外（如网络异常，App 异常等）未能将 livenessId 传给服务端
   

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

   xxxxxxxxxx
   NativeModules.LivenessModule.setSignatureId(signatureId);
   

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

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

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

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

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

     successJsonData数据结构：

     回调参数	类型	解释
     livenessId	String	本次活体检测图片的 id
     livenessBase64Str	String	本次活体检测采集的 base64 格式的图片(远景)
     nearImageBase64Str	String	本次活体检测采集的 base64 格式的图片(近景)
     transactionId	String	追踪本次活体检测日志的事务id
     eventId	String	通过这个字段可以与我们排查问题
     isPay	Boolean	本次活体检测调用是否收费

     xxxxxxxxxx
     failedJsonData 数据结构
     
     |回调参数|类型|解释|
     |:--:|:--:|:--:|
     |transactionId|String|追踪本次活体检测日志的事务id|
     |eventId|String|通过这个字段可以与我们排查问题|
     |errorMessage|String|本次活体检测失败的原因|
     |errorCode|String|错误码
     

10. 国际化

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

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

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

11. 运行时权限

    • 必须权限

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

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

12. 代码混淆

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

13. 关于Androidx

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

    xxxxxxxxxx
    android.enableJetifier=true 
    

14. SDK 兼容性

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

Error Code: