SDK端接入

授权方式说明

离线人脸识别SDK目前支持在线联网激活，以获得SDK使用授权，被授权的设备和App，在有效期内可以运行SDK，离线完成包括人脸库管理、人脸检测、人脸比对、人脸检索、活体判断等功能。授权结束之后，将无法使用任何功能，需要重新激活获得授权。

免费测试：我们为每个接入方提供2个免费测试授权，用于SDK接入试用，测试授权在激活后的1个月内有效。

正式购买：客户根据业务需要购买相应时长的SDK使用授权，具体定价可联系阿里云客户经理咨询。

步骤一：SDK下载

离线人脸识别SDK可通过服务端接口进行下载。关于服务端接口的具体内容，请参见CreateVerifySDK和DescribeVerifySDK。

步骤二：在工程中导入SDK

1. 设定依赖包所在的路径：

   apply plugin: 'com.android.application'
    repositories {
        flatDir {
            dirs '../libs'
        }
    }                    

2. 设定引入的本地库所在路径，将需要引入的依赖包都放在../libs目录，包含所有需要的库。
3. 在gradle文件中引入以下需要的库依赖：

   implementation (name:'lib-verify-xxx-release',ext:'aar')
   implementation (name:'SecurityGuardSDK-external-release-5.4.121',ext:'aar')
   implementation (name:'SecurityBodySDK-external-release-5.4.79',ext:'aar')
   implementation "com.squareup.okhttp3:okhttp:3.12.0" // 版本可以和业务工程的okhttp版本保持一致。                    

   说明 未来各依赖库的版本号会有所变化，实际版本号以下载到的SDK为准。

ABI类型

defaultConfig {
    ndk {
        abiFilters "armeabi-v7a", "arm64-v8a"
    }
}

关于gradle（重要）

离线人脸识别SDK目前只支持gradle plugin版本在3.4.1版本及以下。

步骤三：SDK初始化及相关配置

接入方只需关注SDK提供的VerifySDKManager类，上层与SDK的交互都是通过VerifySDKManager进行调用。

步骤四：SDK用户库操作

初始化成功后，如果要使用SDK的人脸1：N检索能力，需要进行相应用户库操作，向人脸库中添加人脸图片，否则人脸检索将无法匹配。

如果要使用SDK的人脸1:1比对能力，则可以不关注用户库操作，请参见人脸识别部分的说明。

• 加载用户库

  接口名：loadUserLib

  接口描述：用于初始时加载全量用户库。

  表 15. loadUserLib参数说明

  名称	类型	描述
  listener	VerifyLibEventListener	用户库操作回调。

  示例代码：

  // 加载用户数据到内存。
  VerifySDKManager.getInstance().loadUserLib(verifyLibEventListener);           

• 添加本地用户照片

  接口名：addUser

  接口描述：添加本地用户照片到用户库，操作结果以回调方式通知，完成后不必重新loadUserLib。添加后，用户照片数据会存储在设备本地数据库，适用于人脸底库数量不大或设备存储空间相对充裕的情况。

  说明 使用该函数添加用户照片，优势是当人脸算法模型更新升级时，接入方不需要再重新入库一次用户照片，SDK会根据本地已有的照片数据重新提取特征值，支持在新模型下的运行；劣势是照片数据会占用一定的设备存储空间。

  表 16. addUser参数说明

  名称	类型	描述
  isSync	Boolean	是否同步调用。 true：表示建议上层调用入库自己管理线程。 false：表示不需要上层调用入库自己管理线程。
  id	String	用户ID，需要保证唯一性。
  type	Integer	生物特征类型，目前只支持BiologyType.BIOLOGY_FACE。
  featureData	byte[]	用户照片的byte源数据，支持JPG、PNG格式。
  verifyLibEventListener	VerifyLibEventListener	用户库操作回调。

  示例代码：

  VerifySDKManager.getInstance().addUser(true, String.valueOf(i), BiologyType.BIOLOGY_FACE,FileUtil.getFileBuffer(path),verifyLibEventListener);

  接口名：addUserWithoutFeatureData

  接口描述：添加本地用户照片，操作结果以回调方式通知。添加后，用户照片数据不会存储在设备本地数据库，适用于人脸底库数量大或设备存储空间有限的情况。

  说明

  • 使用该函数添加用户照片，优势是不占用设备存储空间；劣势是当人脸算法模型更新升级时，本地已有的特征库无法适配新模型，SDK会运行失败，需要接入方再重新入库一次用户照片，以便新模型重新提取特征值，确保SDK正常运行。
  • 使用该函数的接入方，需要在onUserLibLoaded回调函数中处理errorCode=104的错误码，详见onUserLibLoaded调用示例代码。

  表 17. addUserWithoutFeatureData参数说明

  名称	类型	描述
  isSync	Boolean	是否同步调用。 true：表示建议上层调用入库自己管理线程。 false：表示不建议上层调用入库自己管理线程。
  id	String	用户ID，需要保证唯一性。
  type	Integer	生物特征类型，目前只支持BiologyType.BIOLOGY_FACE。
  featureData	byte[]	用户照片的byte源数据，支持JPG、PNG格式。
  verifyLibEventListener	VerifyLibEventListener	用户库操作回调。

  示例代码：

  VerifySDKManager.getInstance().addUserWithoutFeatureData(true, String.valueOf(i), BiologyType.BIOLOGY_FACE,FileUtil.getFileBuffer(path),verifyLibEventListener);

• 删除指定用户生物数据

  接口名：removeUser

  接口描述：删除指定用户生物数据，操作结果以回调方式通知，无需重新loadUserLib。

  表 18. removeUser参数说明

  名称	类型	描述
  isSync	Boolean	是否同步调用。 true：表示建议上层调用入库自己管理线程。 false：表示不需要上层调用入库自己管理线程。
  id	String	用户ID。
  verifyLibEventListener	VerifyLibEventListener	用户库操作回调。

  示例代码：

  VerifySDKManager.getInstance().removeUser(false,id,verifyLibEventListener);

• 清空所有用户数据

  接口名：clearUserLib

  接口描述：清除本地用户库。

  表 19. clearUserLib参数说明

  名称	类型	描述
  isSync	Boolean	是否同步调用。 true：表示建议上层调用入库自己管理线程。 false：表示不建议上层调用入库自己管理线程。
  verifyLibEventListener	VerifyLibEventListener	用户库操作回调。

  示例代码：

  VerifySDKManager.getInstance().clearUserLib(false,verifyLibEventListener);

• 单用户数据更新回调

  接口名：onSingleUserLibUpdate

  接口描述：用户库操作回调，单用户数据更新。

  表 20. onSingleUserLibUpdate参数说明

  名称	类型	描述
  id	String	用户ID。
  errorCode	Integer	错误码，0为正确。

• 用户库加载完成回调

  接口名：onUserLibLoaded

  接口描述：loadUserLib操作回调，用户库加载完成。

  表 21. onUserLibLoaded参数说明

  名称	类型	描述
  errorCode	Integer	错误码，0为正确。 说明 使用addUserWithoutFeatureData函数添加用户的接入方，需要特殊处理该回调函数errorCode=104的错误码，详见下方示例代码中说明。

• 用户库清除回调

  接口名：onUserLibEmpty

  接口描述：clearUserLib操作回调，用户库清除完成。

  表 22. onUserLibEmpty参数说明

  名称	类型	描述
  errorCode	Integer	错误码，0为正确。

  示例代码：

  // 用户库操作回调。
  final OnVerifyLibEventListener verifyLibEventListener = new OnVerifyLibEventListener() {
          @Override
          public void onSingleUserLibUpdate(String id, final int errorCode) {
          // 单用户更新操作完成后处理。
          }
          @Override
          public void onBatchUserLibUpdate(int errorCode) {
          // 批量用户更新，暂时不支持。
          }
         @Override
          public void onUserLibLoaded(int errorCode) {
          // loadUserLib操作完成后处理。
          //特殊说明：使用addUserWithoutFeatureData函数添加用户的接入方，需要在该回调中特殊处理errorCode=104的错误码，操作步骤如下：
          //第一步：调用clearUserLib清除本地数据。
          //第二步：接入方重新入库用户数据。
          }
          @Override
          public void onUserLibEmpty(int errorCode) {
          // clearUserLib操作完成后处理。
          }
  };
                              

步骤五：SDK人脸识别

人脸1：1比对说明

SDK支持实时视频流和人脸图片进行比对，这是最为常见的1：1对比类型。针对一张事先获取的图片（通常为身份证芯片照、证件照片等），与摄像头实时采集的符合条件的人脸图片进行比对。通常适用于有人值守的场景。

人脸1：N检索

将需要识别的人脸图片注册到本地人脸库中，当有用户需要识别身份时，从视频流中实时采集符合条件的人脸图片，与人脸库中的人脸集合比对，得到检索结果。如果是无人值守的情况，建议可以开启翻拍检测或红外活体保障安全性。

如果在初始化时设置开启了翻拍检测或红外活体检测，则摄像头采集的人脸图片必须同时通过活体检测，才能进入人脸检索环节，任一活体检测未通过，都不会进行人脸检索。

• 人脸1:1比对调用
  • 接口名：doFaceMatchWithImage
    接口描述：RGB摄像头帧数据与人脸图片进行1：1比对，结果以回调方式通知。适用于设备上只有RGB单目摄像头，或者有双目摄像头但未开启红外活体检测的情况，可以使用该接口进行1：1比对。

    表 23. doFaceMatchWithImage参数说明

    名称	类型	描述
    data	byte[]	检测到合格人脸时的RGB帧数据。
    width	Integer	帧数据宽度。
    height	Integer	帧数据高度。
    imageFormat	Integer	帧数据格式，Android默认选择ImageFormat.NV21。
    imageAngle	Integer	读取到合格人脸时的图片旋转角度，取值0/90/180/270，从摄像头的回调接口中获取。
    cameraRotation	Integer	读取到合格人脸时的相机旋转角度，取值0/90/180/270，从摄像头的回调接口中获取。
    targetBitmap	Bitmap	待比对人脸图片。
    listener	FaceMatchWithImageListener	1:1比对回调。

    示例代码：

    // 当未开启红外活体功能时，使用OnFaceMatchWithImageListener类型做回调。
    // 1:1比对的回调
    OnFaceMatchWithImageListener faceMatchWithImageListener = new
    OnFaceMatchWithImageListener() {
        @Override
        @param faceMatchResult可以通过faceMatchResult.getMatchItems().get(0).getScore()获取对比分数。
        public void onMatchResult(FaceMatchResult faceMatchResult) {
         // 与目标图片匹配后的处理。
    }
    @Override
    public void onRecapDetected(byte[] data,
    int width, int height, int imageAngle, int cameraRotation, float recapScore){
      // 检测到人脸翻拍。
    
    }
    };
    // 1:1比对调用。
    VerifySDKManager.getInstance().doFaceMatchWithImage(data,width,height, ImageFormat.NV21, degree, cameraRotation, targetBitmap, faceMatchWithImageListener)
                                        

  • 接口名：doFaceMatchWithImageWithNir
    接口描述：RGB和红外摄像头帧数据与人脸图片进行1：1比对，结果以回调方式通知。适用于设备上有双目红外的摄像头，在开启红外活体检测的情况下，可以使用该接口进行1：1比对。

    表 24. doFaceMatchWithImageWithNir参数说明

    名称	类型	描述
    nirData	byte[]	检测到合格人脸时的红外帧数据。
    rgbData	byte[]	检测到合格人脸时的RGB帧数据。
    width	Integer	RGB帧数据宽度。
    height	Integer	RGB帧数据高度。
    imageFormat	Integer	帧数据格式，Android默认选择ImageFormat.NV21。
    imageAngle	Integer	读取到合格人脸时的图片旋转角度，取值0/90/180/270，从摄像头的回调接口中获取。
    cameraRotation	Integer	读取到合格人脸时的相机旋转角度，取值0/90/180/270，从摄像头的回调接口中获取。
    targetBitmap	Bitmap	待比对人脸图片。
    nirFaceDetectListener	FaceMatchWithImageListener	人脸检测、检索比对、翻拍检测回调。

    示例代码：

    // 当开启红外检测时，使用OnFaceMatchWithImageNirListener类型做回调。
    final OnFaceMatchWithImageNirListener faceMatchWithImageNirListener = new OnFaceMatchWithImageNirListener() {
           @Override
           @param faceMatchResult可以通过faceMatchResult.getMatchItems().get(0).getScore()获取对比分数。
        public void onMatchResult(FaceMatchResult faceMatchResult) {
         // 与目标图片匹配后的处理。
    }
            @Override
            public void onRecapDetected(byte[] data, int width, int height, int imageAngle, int cameraRotation, float recapScore) {
        // 检查到人脸翻拍。
            }
            @Override
            public void onFaceDetectedInNIR(byte[] nirData, int width, int height, int nirAngle, NirFaceInfo nirFaceInfo){
                // 红外摄像头检查到人脸。
            }
            @Override
            public void onNofaceDetectedInNIR(byte[] nirData, int width, int height, int nirAngle){
        // 红外摄像头没有检查到人脸。
            }
        };
    //  1：1比对接口调用，带红外活体。
    VerifySDKManager.getInstance().doFaceMatchWithImageWithNir(nirData,data,width, height,ImageFormat.NV21,degree,cameraRotation, faceMatchWithImageNirListener);

• 人脸1：1比对结果回调
  • 接口名：onMatchResult
    接口描述： 人脸1：1比对结果回调，可获得相应比对分。

    表 25. onMatchResult参数说明

    名称	类型	描述
    result	FaceMatchResult	人脸1:1比对结果。

    示例代码：见人脸1：1比对调用代码示例。
  • 接口名：onRecapDetected

    接口描述：检测到翻拍，且初始化时开启了翻拍检测时，会执行这个回调。

    接口的参数说明可以参考1：N检索中的该回调函数。

  • 接口名：onFaceDetectedInNIR

    接口描述：红外帧数据中检测到人脸时，会回调该函数，调用方可根据此回调做相应处理。

    接口的参数说明可以参考1：N检索中的该回调函数。

  • 接口名：onNofaceDetectedInNIR

    接口描述：红外帧数据中未检测到人脸。

    接口的参数说明可以参考1：N检索中的该回调函数。

• 人脸1：N检索调用

  • 接口名：feedPreviewFrame

    接口描述：RGB摄像头帧数据与人脸库进行1:N检索，结果以回调方式通知。适用于设备上只有RGB单目摄像头，或者有双目摄像头但未开启红外活体检测的情况，可以使用该接口进行检索比对。

    表 26. feedPreviewFrame参数说明

    名称	类型	描述
    data	byte[]	检测到合格人脸时的RGB帧数据。
    width	Integer	帧数据宽度。
    height	Integer	帧数据高度。
    imageFormat	Integer	帧数据格式，Android默认选择ImageFormat.NV21。
    imageAngle	Integer	读取到合格人脸时的图片旋转角度，取值0/90/180/270，从摄像头的回调接口中获取。
    cameraRotation	Integer	读取到合格人脸时的相机旋转角度，取值0/90/180/270，从摄像头的回调接口中获取。
    faceDetectWithMatchListener	FaceDetectWithMatchListener	人脸检测、检索比对、翻拍检测回调。

    示例代码：

    // 当未开启红外活体功能时，使用OnFaceDetectWithMatchListener类型做回调。
    final OnFaceDetectWithMatchListener
    faceDetectListener = new OnFaceDetectWithMatchListener() {
            @Override
            public void onFaceDetected(byte[] data, final int width, final int height, int imageFormat, int imageAngle, int cameraRotation, final FaceInfo faceInfo) {
        // 识别到人脸时。
            }
            @Override
            public void onNofaceDetected(byte[] data, int width, int height, int imageFormat, int imageAngle, int cameraRotation) {
        // 没有识别到人脸时。
            }
            @Override
            public void onFaceMatched(byte[] data, int width, int height, int imageAngle, int cameraRotation, final FaceMatchResult matchResult, final long costTime) {
        // 识别到人脸并在用户库中匹配用户。
            }
            @Override
            public void onRecapDetected(byte[] data, int width, int height, int imageAngle, int cameraRotation, float recapScore) {
        // 检查到人脸翻拍。
            }
            @Override
            public void onFaceMoving(boolean isMoving) {
        // 检查到人脸移动。
            }
    // 1：N检索接口调用，不带红外活体。
    VerifySDKManager.getInstance().feedPreviewFrame(data,width, height,ImageFormat.NV21,degree,cameraRotation, faceDetectWithMatchListener);
                                        

  • 接口名：feedPreviewFrameWithNir

    接口描述：RGB和红外摄像头帧数据与人脸库进行1：N检索，结果以回调方式通知。适用于设备上有双目红外的摄像头，在开启红外活体检测的情况下，可以使用该接口进行检索比对。

    表 27. feedPreviewFrameWithNir参数说明

    名称	类型	描述
    nirData	byte[]	检测到合格人脸时的红外帧数据。
    rgbData	byte[]	检测到合格人脸时的RGB帧数据。
    width	Integer	RGB帧数据宽度。
    height	Integer	RGB帧数据高度。
    imageFormat	Integer	帧数据格式，Android默认选择ImageFormat.NV21。
    imageAngle	Integer	读取到合格人脸时的图片旋转角度，取值0/90/180/270，从摄像头的回调接口中获取。
    cameraRotation	Integer	读取到合格人脸时的相机旋转角度，取值0/90/180/270，从摄像头的回调接口中获取。
    nirFaceDetectListener	FaceMatchWithImageListener	人脸检测、检索比对、翻拍检测回调。

    示例代码：

    // 当开启红外检测时，使用OnNirFaceDetectListener类型做回调。
    final OnNirFaceDetectListener nirFaceDetectListener = new OnNirFaceDetectListener() {
            @Override
            public void onFaceDetected(byte[] data, final int width, final int height, int imageFormat, int imageAngle, int cameraRotation, final FaceInfo faceInfo) {
        // 识别到人脸时。
            }
            @Override
            public void onNofaceDetected(byte[] data, int width, int height, int imageFormat, int imageAngle, int cameraRotation) {
        // 没有识别到人脸时。
            }
            @Override
            public void onFaceMatched(byte[] data, int width, int height, int imageAngle, int cameraRotation, final FaceMatchResult matchResult, final long costTime) {
        // 识别到人脸并在用户库中匹配用户。
            }
            @Override
            public void onRecapDetected(byte[] data, int width, int height, int imageAngle, int cameraRotation, float recapScore) {
        // 检查到人脸翻拍。
            }
            @Override
            public void onFaceMoving(boolean isMoving) {
        // 检查到人脸移动。
            }
            @Override
            public void onFaceDetectedInNIR(byte[] nirData, int width, int height, int nirAngle, NirFaceInfo nirFaceInfo){
                // 红外摄像头检查到人脸。
            }
            @Override
            public void onNofaceDetectedInNIR(byte[] nirData, int width, int height, int nirAngle){
        // 红外摄像头没有检查到人脸。
            }
        };
    // 1：N检索接口调用，带红外活体。
    VerifySDKManager.getInstance().feedPreviewFrameWithNir(nirData,data,width, height,ImageFormat.NV21,degree,cameraRotation,nirFaceDetectListener);
                                        

• 人脸1：N检测到人脸回调

  • 接口名：onFaceDetected

    接口描述：RGB帧数据中检测到人脸时，会回调该函数，调用方可根据此回调绘制人脸框。

    表 28. onFaceDetected参数说明

    名称	类型	描述
    data	byte[]	RGB帧数据。
    width	Integer	RGB帧数据宽度。
    height	Integer	RGB帧数据高度。
    imageFormat	Integer	帧数据格式，Android默认选择ImageFormat.NV21。
    imageAngle	Integer	图片旋转角度。
    cameraRotation	Integer	相机旋转角度。
    faceInfo	FaceInfo	检测到的人脸信息在帧中的坐标，宽高。

    示例代码：见1：N检索调用代码。

  • 接口名：onFaceDetectedInNIR

    接口描述：红外帧数据中检测到人脸时，会回调该函数，调用方可根据此回调做相应处理。

    表 29. onFaceDetectedInNIR参数说明

    名称	类型	描述
    nirData	byte[]	红外帧数据。
    width	Integer	红外帧数据宽度。
    height	Integer	红外帧数据高度。
    nirAngle	Integer	图片旋转角度。
    nirFaceInfo	NirFaceInfo	检测到的红外人脸信息在帧中的坐标，宽高。

    示例代码：见1：N检索调用代码。
• 人脸1：N未检测到人脸回调

  • 接口名：onNofaceDetected

    接口描述：RGB帧数据中未检测到人脸，可以在这个回调中更新UI，移除之前绘制的人脸框。

    表 30. onNofaceDetected参数说明

    名称	类型	描述
    data	byte[]	RGB帧数据。
    width	Integer	RGB帧数据宽度。
    height	Integer	RGB帧数据高度。
    imageFormat	Integer	帧数据格式，Android默认选择ImageFormat.NV21。
    imageAngle	Integer	图片旋转角度。
    cameraRotation	Integer	相机旋转角度。

    示例代码：见1：N检索调用代码。

  • 接口名：onNofaceDetectedInNIR

    接口描述：红外帧数据中未检测到人脸。

    表 31. onNofaceDetectedInNIR参数说明

    名称	类型	描述
    nirData	byte[]	红外帧数据。
    width	Integer	红外帧数据宽度。
    height	Integer	红外帧数据高度。
    nirAngle	Integer	图片旋转角度。

    示例代码：见1：N检索调用代码。
• 人脸1：N检索结果回调

  接口名：onFaceMatched

  接口描述：人脸检索匹配结果回调。

  表 32. onFaceMatched参数说明

  名称	类型	描述
  data	byte[]	RGB帧数据。
  width	Integer	RGB帧数据宽度。
  height	Integer	RGB帧数据高度。
  imageAngle	Integer	图片旋转角度。
  cameraRotation	Integer	相机旋转角度。
  matchResult	FaceMatchResult	匹配结果，极端情况下可能存在多个人的情况，比如双胞胎。
  costTime	Long	人脸检索比对耗时，性能分析调试用。

  示例代码：见1：N检索调用代码。
• 检测到翻拍回调

  接口名：onRecapDetected

  接口描述：检测到翻拍，且初始化时开启了翻拍检测时，会执行这个回调。

  表 33. onRecapDetected参数说明

  名称	类型	描述
  data	byte[]	RGB帧数据。
  width	Integer	RGB帧数据宽度。
  height	Integer	RGB帧数据高度。
  imageAngle	Integer	图片旋转角度。
  cameraRotation	Integer	相机旋转角度。
  recapScore	Float	翻拍得分。

  示例代码：见1：N检索调用代码。
• 人脸移动时的回调

  接口名：onFaceMoving

  接口描述：检测到人脸在移动时，会回调该函数。

  表 34. onFaceMoving参数说明

  名称	类型	描述
  isMoving	Boolean	人脸是否移动。

  示例代码：见1：N检索调用代码。

SDK错误码