# M3 人脸识别服务第三方应用接入开发文档

# 一、引言

为提升数据准确和安全性,增强人事考勤管理能力、流程审批管理能力和 M3 Android 客户端 APP 安全,A8 V9.0 版本新增人脸识别能力。

适用于考勤签到、流程审批、支付等需要二次身份验证场景。

# 二、接入前提条件

注意:人脸识别当前只支持注意:人脸识别当前只支持 M3 ,不支持微协同

# 1、服务准备

  • * 安装部署旷视人脸服务,并创建自建应用

    获取旷视服务安装包与授权需要联系旷视官方商务或运维技术人员。

    参考文档:【旷视人脸识别(FaseID企业版)私有化服务安装部署文档】

  • * 申请 A8 服务加密狗,需要人脸识别插件

  • * 安装部署 A8 服务,并完成人脸服务相关配置

  • * 仅支持 A8 V9.0 及以上版本。M3 客户端 4.6.0 及以上版本。

# 2、技术准备

# 三、接入流程概述

# 四、技术接入指南

# 1、OA PC 人脸识别接口

  • API: window.faceEECheck(success, error)

  • 资源依赖文件引入

    <scrpit src="${path}/apps_res/faceId/js/faceIdQrCode.js" />
    

    ${path} 在 OA 后端 JSP 文件中作为 el 参数。如前后端分离可以将 ${path} 改为 seeyon 或其他(根据实际情况)。

  • 参数说明

    参数名称 类型 说明
    success function 成功回调函数
    error function 失败回调函数
  • 调用示例

    window.faceEECheck(function(data) {
        // 这里实现人脸识别成功回调
    }, function(error) {
        // 这里实现人脸识别失败回调
    })
    
  • 成功回调参数说明

    参数名称 类型 说明
    qrCodeData Object
    qrCodeData.grImageurl String 人脸识别认证二维码地址。(一般业务不需要)
    qrCodeData.bizInfoToken String 识别结果查询码
    qrCodeData.bizNo String 业务码
  • 失败回调参数说明

    无返回参数

# 2、移动H5应用调用人脸识别接口

  • API: cmp.sdk.faceEECheck(attendance, success, error)

  • 资源依赖文件引入

    <scrpit src="cmp://cmp/v/js/cmp-i18n.js" />
    <scrpit src="cmp://cmp/v/js/cordova/__CMPSHELL_PLATFORM__/cordova.js" />
    <scrpit src="cmp://cmp/v/js/cordova/cordova-plugins.js" />
    <scrpit src="cmp://cmp/v/js/cmp.js" />
    
  • 参数说明

    参数名称 类型 说明
    attendance boolean 是否是考勤模块调用,默认 false。非 OA 标准产品考勤业务都需要传入 false
    success function 成功回调函数
    error function 失败回调函数
  • 调用示例

    cmp.sdk.faceEECheck(false, function(data) {
        // 这里实现人脸识别成功回调
    }, function(error) {
        // 这里实现人脸识别失败回调
    })
    
  • 成功回调参数说明

    参数名称 类型 说明
    code int 返回码:200 成功,其他均失败
    type String 认证状态
    1:成功
    2:人脸录入成功
    qrCodeId String 二维码ID
    bit String 结果查询码(bizInfoToken )
    message String 返回消息
  • 失败回调参数说明

    参数名称 类型 说明
    type String -1:用户主动注销
    500:其他异常

# 3、服务端人脸识别 API

服务端 API 依赖 apps-api 模块:com.seeyon.apps.faceId.api.FaceIdApi 类

  • 判断指定人员是否拥有人脸识别授权

    当后端业务需要判断人员是否拥有人脸授权可调用此接口。当指定人员没有人脸识别授权或服务没有人脸插件和人脸识别服务不可用时,返回 false。反之返回true。

    boolean hasFaceIdAuth(long memberId);
    

    备注:此接口同时会验证人脸插件是否可用,人脸服务是否可用。

    • 接口参数

      参数名称 类型 是否必须 说明
      memberId long 人员ID,OA 系统组织架构中的人员的ID
    • 返回数据

      参数名称 类型 默认值 说明
      是否授权 boolean false 是否授权:true 已授权,false 未授权
    • 示例

      import com.seeyon.apps.faceId.api.FaceIdApi;
      
      public class BusinessDemo {
          // 获取人脸识别 API 的实现。注意:调用 faceIdApi 的方法时建议对 faceIdApi 对象做非空判断
      	private FaceIdApi faceIdApi = (FaceIdApi) AppContext.getBean("faceIdApi");
          
          public void testDemo() {
              // ... 业务实现
              boolean has = faceIdApi.hasFaceIdAuth(-54122145481136741347L); // 判断人员是否有人脸识别授权
              if (has) {
                  // ... 业务实现
              } else {
                  // ... 业务实现
              }
              // ... 业务实现
          }
      }
      
  • 判断是否有人脸插件

    当业务模块需要根据是否有人脸插件处理逻辑时,可以通过此接口判断服务是否拥有人脸插件。

    boolean hasFaceIdPlugin();
    
    • 接口参数

    • 返回数据

      参数名称 类型 默认值 说明
      是否有插件 boolean false 是否有插件:true 有插件,false 无插件或插件不可用
    • 示例

      import com.seeyon.apps.faceId.api.FaceIdApi;
      
      public class BusinessDemo {
          // 获取人脸识别 API 的实现。注意:调用 faceIdApi 的方法时建议对 faceIdApi 对象做非空判断
      	private FaceIdApi faceIdApi = (FaceIdApi) AppContext.getBean("faceIdApi");
          
          public void testDemo() {
              // ... 业务实现
              boolean has = faceIdApi.hasFaceIdPlugin(); // 判断是否有插件
              if (has) {
                  // ... 业务实现
              } else {
                  // ... 业务实现
              }
              // ... 业务实现
          }
      }
      
  • 人脸是否可用

    当业务模块需要根据是否有人脸插件切人脸服务是否可用处理逻辑时,可以调用此接口判断。

    boolean faceIdEnable();
    

    备注:此接口同时会验证人脸插件是否可用。

    • 接口参数

    • 返回数据

      参数名称 类型 默认值 说明
      是否有插件 boolean false 是否授权:true 有插件,false 无插件或插件不可用
    • 示例

      import com.seeyon.apps.faceId.api.FaceIdApi;
      
      public class BusinessDemo {
          // 获取人脸识别 API 的实现。注意:调用 faceIdApi 的方法时建议对 faceIdApi 对象做非空判断
      	private FaceIdApi faceIdApi = (FaceIdApi) AppContext.getBean("faceIdApi");
          
          public void testDemo() {
              // ... 业务实现
              boolean has = faceIdApi.faceIdEnable();
              // ... 业务实现
          }
      }
      
  • 检查识别结果

    当业务场景中,用户完成人脸识别后,服务端应对验证结果进行二次校验。此时可根据前端接口返回的参数传入后端接口中。在后端接口调用此接口进行二次校验人脸识别结果。

    Map<String, Object> checkRecognitionResult (String bizNo, String bizInfoToken);
    
    • 接口参数

      参数名称 类型 是否必须 说明
      bizNo String 业务编码
      bizInfoToken String 业务查询码
    • 返回数据

      参数名称 类型 默认值 说明
      bizNo String 业务编码
      status String failed 结果状态:
      created:认证请求已创建未开始
      erifying:认证中
      success:认证成功
      failed:认证失败
      cancelled:认证被取消中止
      timeout:认证流程超时
    • 示例

      import com.seeyon.apps.faceId.api.FaceIdApi;
      
      public class BusinessDemo {
          // 获取人脸识别 API 的实现。注意:调用 faceIdApi 的方法时建议对 faceIdApi 对象做非空判断
      	private FaceIdApi faceIdApi = (FaceIdApi) AppContext.getBean("faceIdApi");
          
          public void testDemo() {
              // ... 业务实现
              Map<String, Object> result = faceIdApi.checkRecognitionResult("Pcn12SA", "jEf92Lsn172");
              String status = String.valueOf(result.get("status"));
              String bizNo = String.valueOf(result.get("bizNo"));
              if ("success".equals(status)) {
                  // ... 业务实现
              } else {
                  // ... 业务实现
              }
              // ... 业务实现
          }
      }
      
  • 业务模块人脸服务是否可用

    判断人脸识别业务模块是否可用及用户是否购买相关只插件,仅适用标准产品 M3 Android 唤醒标准产品人脸识别考勤签到标准产品人脸识别流程审批。第三方接入或其他场景此接口无用,无需调用此接口判断。

    boolean faceIdByBusinessPluginEnable(String businessPluginName)
    
    • 接口参数

      参数名称 类型 是否必须 说明
      businessPluginName String 业务模块ID:
      faceId_m3_awakening:M3 唤醒
      faceId_clock:人脸识别考勤签到
      faceId_approve:人脸识别流程审批
    • 返回数据

      参数名称 类型 默认值 说明
      模块是否可用 boolean false true:可用;false:不可用
    • 示例

      import com.seeyon.apps.faceId.api.FaceIdApi;
      
      public class BusinessDemo {
          // 获取人脸识别 API 的实现。注意:调用 faceIdApi 的方法时建议对 faceIdApi 对象做非空判断
      	private FaceIdApi faceIdApi = (FaceIdApi) AppContext.getBean("faceIdApi");
          
          public void testDemo() {
              // ...
              boolean has = faceIdApi.hasFaceIdAuth(-54122145481136741347L);
              // ...
          }
      }
      
创建人:puwb
修改人:puwb