全部产品
  • 首页 > 
  • 离线授权认证SDK API说明

离线授权认证SDK API说明

注意:离线授权认证 SDK 的实际应用效果与硬件配置和设备所处环境密切相关,目前只通过项目合作方式输出,前期需要评估方案可行性。

人脸算法对设备的要求

机器:

  • 系统:Android 4.4及以上
  • 系统类型:32位、64位
  • 处理器:4核,1.45GHz及以上
  • 内存:1G及以上

镜头:

  • 分辨率:RGB镜头1080p, 红外镜头:800X600及以上(需要使用红外功能的需要关注)
  • 固定30帧,无拖影,RGB镜头建议是宽动态
  • 拍出的照片清晰可辨认,人脸区域宽度大于100像素

SDK的使用与初始化

只需关注 SDK 提供的 VerifySDKManager 类,上层与 SDK 的交互都是通过 VerifySDKManager 进行调用。有三种初始化方式:

方式一,使用SDK授权激活的初始化方法:

VerifySDKManager.initWithToken(xxx)

initWithToken具体方法如下:

  1. /**
  2. * 使用SDK授权激活的初始化方法
  3. * @param context 当前activity的上下文
  4. * @param token 激活使用的accessToken,从实人认证服务端申请获得
  5. * @param initWithTokenCallback 回调
  6. * @return
  7. */
  8. public VerifySDKManager.initWithToken(Context contextString tokenInitWithTokenCallback initWithTokenCallback);

使用initWithToken初始化方法,需要开启设备管理功能:

VerifySDKManager.setNeedDeviceManage(xxx)

setNeedDeviceManage具体方法如下:

  1. /**
  2. * 开启设备管理功能
  3. * @param needDeviceManage 是否开启设备管理
  4. * @return
  5. */
  6. public VerifySDKManager.setNeedDeviceManage(boolean needDeviceManage)

方式二,使用 SDK 内部缺省参数时的初始化方法:

  1. VerifySDKManager.getInstance().init(getApplicationContext());

方式三,若您需要对 SDK 修改人脸检测的最小尺寸、是否支持端侧翻拍检测、端侧翻拍检测的分数阈值、人脸检索的比对分数阈值等配置参数,请使用如下初始化方法:

  1. VerifySDKManager.getInstance().setXXX(xxx).init(getApplicationContext());

其中 setXXX(xxx) 方法具体如下:

  1. /**
  2. * 设置最小检测人脸
  3. * @param minFaceDetectSize 人脸检测的最小尺寸,取值范围0-1,定义为占图像min(宽,高)的比例,默认值0.1
  4. * @return
  5. */
  6. public VerifySDKManager setMinFaceDetectSize(float minFaceDetectSize);
  7. /**
  8. * 人脸位置有效区域边界
  9. * @param leftBorder 人脸位置有效区域的左边界,定义为占旋转后图像宽度的比例,默认值0.1
  10. * @param rightBorder 人脸位置有效区域的右边界,定义为占旋转后图像宽度的比例,默认值0.9
  11. * @param topBorder 人脸位置有效区域的上边界,定义为占旋转后图像高度的比例,默认值0.1
  12. * @param bottomBorder 人脸位置有效区域的下边界,定义为占旋转后图像高度的比例,默认值0.9
  13. * @return
  14. */
  15. public VerifySDKManager setBorders(float leftBorder, float rightBorder, float topBorder, float bottomBorder);
  16. /**
  17. * 设置是否开启离线翻拍检测
  18. * @param needRecapCheck
  19. * @return
  20. */
  21. public VerifySDKManager setNeedRecapCheck(boolean needRecapCheck);
  22. /**
  23. * 设置红外图像的帧高度,默认值为720
  24. * @param nirFrameH
  25. * @return
  26. */
  27. public VerifySDKManager setNirFrameH(int nirFrameH);
  28. /**
  29. * 设置红外图像的帧宽度,默认值为720
  30. * @param nirFrameW
  31. * @return
  32. */
  33. public VerifySDKManager setNirFrameW(int nirFrameW);
  34. /**
  35. * 设置红外图像的旋转角度,默认值为0
  36. * @param nirAngle
  37. * @return
  38. */
  39. public VerifySDKManager setNirAngle(int nirAngle);
  40. /**
  41. * 设置RGB图像的旋转角度,默认值为0
  42. * @param nirAngle
  43. * @return
  44. */
  45. public VerifySDKManager setRgbAngle(int rgbAngle);
  46. /**
  47. * 设置是否需要红外活体能力,若设置需要红外活体能力,那么setNirFrameW & setNirFrameH & setNirAngle & setRgbAngle 为必要参数
  48. * @param needNirLiveness
  49. * @return
  50. */
  51. public VerifySDKManager setNeedNirLiveness(boolean needNirLiveness);

用户库操作

加载用户库

  1. public void loadUserLib(VerifyLibEventListener listener)

添加本地用户照片

  1. /**
  2. * 添加本地用户照片
  3. * @param isSync 是否同步调用,建议上层调用入库自己管理线程,该参数传true,否则传false
  4. * @param id 用户id
  5. * @param type 生物特征类型,目前只支持Type.BIOLOGY_FACE
  6. * @param featureData 用户照片的byte源数据,支持jpg、png格式
  7. * @param verifyLibEventListener 用户库操作回调
  8. */
  9. public void addUser(boolean isSync, String id, int type, byte[] featureData, VerifyLibEventListener verifyLibEventListener)

删除指定用户生物数据

  1. /**
  2. * 删除指定 userId 的生物数据
  3. * @param isSync 是否同步调用,建议上层调用入库自己管理线程,该参数传true,否则传false
  4. * @param id 用户ID
  5. * @param verifyLibEventListener 用户库操作回调
  6. */
  7. public void removeUser(boolean isSync, String id, VerifyLibEventListener verifyLibEventListener)

清空所有用户数据

  1. /**
  2. * 清除本地用户库
  3. * @param isSync 是否同步调用,建议上层调用入库自己管理线程,该参数传true,否则传false
  4. * @param listener 用户库操作回调
  5. */
  6. public void clearUserLib(boolean isSync, VerifyLibEventListener listener)

用户库操作回调

  1. public interface VerifyLibEventListener {
  2. /**
  3. * 单用户数据更新回调,
  4. * @param id 用户ID
  5. * @param errorCode 错误码,0为正确
  6. */
  7. void onSingleUserLibUpdate(String id, int errorCode);
  8. /**
  9. * 批量用户更新回调,暂不支持
  10. * @param errorCode
  11. */
  12. void onBatchUserLibUpdate(int errorCode);
  13. /**
  14. * 用户库加载完成
  15. * @param errorCode
  16. */
  17. void onUserLibLoaded(int errorCode);
  18. /**
  19. * 用户库清楚回调
  20. * @param errorCode
  21. */
  22. void onUserLibEmpty(int errorCode);
  23. }

人脸检测和检索

调用方法

  1. /**
  2. * 摄像头帧数据采集,执行内部逻辑,以回调方式通知调用方
  3. * @param data 帧数据
  4. * @param width 帧数据宽度
  5. * @param height 帧数据高度
  6. * @param imageFormat 帧数据格式,Android默认选择ImageFormat.NV21
  7. * @param imageAngle 图片旋转角度,0/90/180/270,从摄像头的回调接口中获取
  8. * @param cameraRotation 相机旋转角度,0/90/180/270,从摄像头的回调接口中获取
  9. * @param faceDetectWithMatchListener 人脸检测、比对、翻拍检测回调
  10. */
  11. public void feedPreviewFrame(final byte[] data, final int width, final int height, final int imageFormat, final int imageAngle, final int cameraRotation, FaceDetectWithMatchListener faceDetectWithMatchListener)
  12. /**
  13. * 红外摄像头帧数据采集,执行内部逻辑,以回调方式通知调用方
  14. * @param nirData 红外帧数据
  15. * @param rgbData RGB帧数据
  16. * @param width 帧数据宽度
  17. * @param height 帧数据高度
  18. * @param imageFormat 帧数据格式,Android默认选择ImageFormat.NV21
  19. * @param imageAngle 图片旋转角度,0/90/180/270,从摄像头的回调接口中获取
  20. * @param cameraRotation 相机旋转角度,0/90/180/270,从摄像头的回调接口中获取
  21. * @param nirFaceDetectListener 红外人脸检测、比对、翻拍检测回调
  22. */
  23. public void feedPreviewFrameWithNir(final byte[] nirData, final byte[] rgbData, final int width, final int height, final int imageFormat, final int imageAngle, final int cameraRotation, FaceDetectWithMatchListener nirFaceDetectListener);

人脸检测和检索回调

  1. public interface FaceDetectWithMatchListener {
  2. /**
  3. * 检测到人脸,调用方可根据此回调绘制人脸框
  4. * @param data 帧数据
  5. * @param width 帧数据宽度
  6. * @param height 帧数据高度
  7. * @param imageFormat 帧数据格式,Android默认选择ImageFormat.NV21
  8. * @param imageAngle 图片旋转角度,0/90/180/270
  9. * @param cameraRotation 相机旋转角度,0/90/180/270
  10. * @param faceInfo 检测到的人脸信息如在帧中的坐标,宽高
  11. */
  12. void onFaceDetected(byte[] data, int width, int height, int imageFormat, int imageAngle, int cameraRotation, FaceInfo faceInfo);
  13. /**
  14. * 未检测到人脸,可以在这个回调中更新UI,移除之前绘制的人脸框
  15. * @param data data 摄像头传入的帧数据
  16. * @param width width 摄像头传入的帧宽度
  17. * @param height height 摄像头传入的帧高度
  18. * @param imageFormat 帧数据格式,Android默认选择ImageFormat.NV21
  19. * @param imageAngle 图片旋转角度,0/90/180/270
  20. * @param cameraRotation 相机旋转角度,0/90/180/270
  21. */
  22. void onNofaceDetected(byte[] data, int width, int height, int imageFormat, int imageAngle, int cameraRotation);
  23. /**
  24. * 检测到红外帧数据中的人脸,调用方可根据此回调做相应处理
  25. * @param nirData 红外帧数据
  26. * @param width 帧数据宽度
  27. * @param height 帧数据高度
  28. * @param nirAngle 帧数据旋转角度
  29. * @param nirFaceInfo 检测到的红外人脸信息在帧中的坐标
  30. */
  31. void onFaceDetectedInNIR(byte[] nirData, int width, int height, int nirAngle, NirFaceInfo nirFaceInfo);
  32. /**
  33. * 未检测到红外帧数据中的人脸
  34. * @param nirData 红外帧数据
  35. * @param width 帧数据宽度
  36. * @param height 帧数据高度
  37. * @param nirAngle 帧数据旋转角度
  38. */
  39. void onNofaceDetectedInNIR(byte[] nirData, int width, int height, int nirAngle);
  40. /**
  41. * 人脸匹配到库中的用户
  42. * @param data 帧数据
  43. * @param width 帧数据宽度
  44. * @param height 帧数据高度
  45. * @param imageAngle 图片旋转角度,0/90/180/270
  46. * @param cameraRotation 相机旋转角度,0/90/180/270
  47. * @param matchResult 匹配结果,极端情况下可能存在多个人的情况,比如双胞胎
  48. * @param costTime 人脸比对耗时,性能分析调试用
  49. */
  50. void onFaceMatched(byte[] data, int width, int height, int imageAngle, int cameraRotation, FaceMatchResult matchResult, long costTime);
  51. /**
  52. * 检测到翻拍,当初始化时调用了setNeedRecapCheck(true)并且检测到翻拍时,会执行这个回调
  53. * @param data data 摄像头传入的帧数据
  54. * @param width width 摄像头传入的帧宽度
  55. * @param height height 摄像头传入的帧高度
  56. * @param imageAngle 图片旋转角度,0/90/180/270
  57. * @param cameraRotation 相机旋转角度,0/90/180/270
  58. * @param recapScore 算法返回的翻拍检测分数
  59. */
  60. void onRecapDetected(byte[] data, int width, int height, int imageAngle, int cameraRotation, float recapScore);
  61. void onFaceMoving(boolean isMoving);
  62. }

SDK注销与释放

在退出应用时调用,与 init() 方法是成对调用的关系,如果不调用,如果进程没有退出的情况下,重复调用 init() 方法会失败。

  1. VerifySDKManager.getInstance().release();

错误码说明

错误代码 中文描述 错误状态码
VERIFYSDK_ERR_CODE_BAD_PARAM 参数错误 100
VERIFYSDK_ERR_CODE_ACCESS_WORK_FAILED 访问工作路径错误 101
VERIFYSDK_ERR_CODE_INVALID_PARAM 人脸引擎参数无效 1000
VERIFYSDK_ERR_CODE_SDK_NOT_INIT 人脸引擎未初始化 1001
VERIFYSDK_ERR_CODE_INIT_MULT_TIME 人脸引擎初始化多次 1002
VERIFYSDK_ERR_CODE_FILE_NOT_EXIST 人脸模型文件不存在 1100
VERIFYSDK_ERR_CODE_FILE_SIZE_ERROR 人脸模型文件大小错误 1101
VERIFYSDK_ERR_CODE_VERSION_NOT_MATCH 人脸模型版本不匹配 1102
VERIFYSDK_ERR_CODE_VERSION_NOT_MATCH_FD 人脸模型版本不匹配子错误 11020
VERIFYSDK_ERR_CODE_VERSION_NOT_MATCH_LDM 人脸模型版本不匹配子错误 11021
VERIFYSDK_ERR_CODE_VERSION_NOT_MATCH_LDC 人脸模型版本不匹配子错误 11022
VERIFYSDK_ERR_CODE_L_VERSION_NOT_MATCH_FE 人脸模型版本不匹配子错误 11023
VERIFYSDK_ERR_CODE_VERSION_NOT_MATCH_FEENC 人脸模型版本不匹配子错误 11024
VERIFYSDK_ERR_CODE_CANCEL 取消 1103
VERIFYSDK_ERR_CODE_BUSY 数据库并发操作 1104
VERIFYSDK_ERR_CODE_FEATURE_SIZE_ERROR 人脸特征大小错误 1201
VERIFYSDK_ERR_CODE_LICENCE 授权错误 5000
VERIFYSDK_ERR_CODE_LICENCE_INPUT 输入参数错误 5001
VERIFYSDK_ERR_CODE_LICENCE_DATA_FORMAT 授权文件格式错误 5002
VERIFYSDK_ERR_CODE_LICENCE_SIGN 签名校验错误 5003
VERIFYSDK_ERR_CODE_LICENCE_APKPKG 包名校验错误 5004
VERIFYSDK_ERR_CODE_LICENCE_PUBKEY 公钥校验错误 5005
VERIFYSDK_ERR_CODE_LICENCE_EXPIRE 授权过期 5006
VERIFYSDK_ERR_CODE_LICENCE_NOT_CHECK 未进行授权检查 5007
VERIFYSDK_ERR_CODE_LICENCE_CLIENT_ID 终端标识校验错误 5009
VERIFYSDK_ERR_CODE_LICENCE_EXPIRE_DATE_MODIFIED 授权失效时间被修改 5010
VERIFYSDK_ERR_CODE_NOT_SUPPORT_DEVICE 不支持的硬件型号 6000
VERIFYSDK_ERR_CODE_LOAD_LIBARY_FAILED 加载so失败 6001
VERIFYSDK_ERR_CODE_LICENCE_NOT_EXIST 授权文件不存在 6002
VERIFYSDK_ERR_CODE_SECURITY_TOKEN_SOCKET_TIMEOUT 获取激活token超时,即初始化失败或未完成 7001
VERIFYSDK_ERR_CODE_GET_STATIC_DATA_STORE_COMP SDK安全组件获取appkey失败 7003
VERIFYSDK_ERR_CODE_GET_SECURE_SIGNATURE_COMP SDK安全组件获取加签失败 7004
VERIFYSDK_ERR_CODE_SG_SECEXCEPTION SDK安全组件异常 7002
VERIFYSDK_ERR_CODE_GET_LICENSE_INFO_TOKEN_NULL 带授权token激活时,token为空 8001
VERIFYSDK_ERR_CODE_GET_LICENSE_INFO_NATIVE_FAILED 获取授权失败 8002
VERIFYSDK_ERR_CODE_GET_LICENSE_CHARSETNAME_EXCEPTION 授权token编码转换出错 8003
VERIFYSDK_ERR_CODE_USER_LIB_NOT_LOADED 人脸库还未初始化完成 9001
VERIFYSDK_ERR_CODE_UNKNOWN 人脸模块未知错误 9999
VERIFYSDK_ERR_CODE_ACTIVATE_LICENSE_REQUEST_FAILED 请求失败,激活SDK失败 10001
VERIFYSDK_ERR_CODE_ACTIVATE_LICENSE_DEVICE_NOT_AUTH 未授权,激活SDK失败 10002
VERIFYSDK_ERR_CODE_ACTIVATE_LICENSE_DEVICE_AUTH_EXPIRED 授权到期失效,激活SDK失败 10003
VERIFYSDK_ERR_CODE_ACTIVATE_LICENSE_DATA_NULL 授权文件为空,激活SDK失败 10004