小程序接入说明

小程序接入流程

  1. 通过get_biz_token API接口，设置参数，并获取biz_token。
  2. 在下载中心下载验证微信小程序包，解压得到 faceid-components文件夹。将faceid-components文件夹添加至项目文件根目录。在需要引用组件的页面进行集成。请参见下文详细介绍。
  3. 验证流程结束后，可以通过get_result接口获取本次验证流程的详细信息。

下面对各个步骤进行详细的说明

第1步：获取biz_token

API名称

Get_biz_token

说明

客户服务器端通过此接口可以获得一个biz_token（biz_token唯一且只能使用一次，有效期为1小时，但是您可以在1天内对该结果进行查询）。该请求是POST方法，参数中要包括用户后续验证的相关信息。

API地址

POST https://openapi.faceid.com/lite/v1/get_biz_token

参数

参数名可选/必选类型说明
sign必选String根据API_KEY和API_SECRET生成的签名，签名算法参见相关文档
sign_version必选String签名算法版本，当前仅支持：hmac_sha1
return_url必选String流程结束后跳转到客户定义的页面，必须以http或者https开头，对微信小程序来说，该参数不起作用
notify_url必选String流程结束后，FaceID会通知客户服务器，post请求到该url，必须以http或者https开头, post的参数名是data，data的值是一个json字符串，内容包括：biz_token, error_code，error_msg。biz_token是get_biz_token接口获得的，error_code和error_msg参见后文详述
biz_no可选String"默认为空"。客户业务流水号，建议设置为您的业务相关的流水串号并且唯一。此字段不超过128字节
comparison_type必选Int本次验证服务的类型。
0：表示活体照片和上传照片进行比对(人脸比对)。
liveness_type必选String表示活体检测的类型，当前仅支持：video_number
security_level可选Int表示对比对结果的严格程度限制，默认值为2，可以根据您的场景，选择相应的安全规则，越严格，准确性要求越高，通过率也会相应下降。支持：1(宽松),2(常规),3(严格)
liveness_preferences可选Int1：默认值，表示视频活体采用宽松模式（4个数字对3个就能通过）; 2：表示视频活体采用严格模式（4个数字完全正确才通过）
liveness_retry_count可选Int当视频验证出错时，视频允许上传最大重试次数，默认为3次，用户可以通过该参数设置为1～5
uuid条件必选String当comparison_type=0时，该字段用于标志本次识别对应的用户的唯一ID，要求不长于128字节。建议对来自同一用户的比对请求使用同样的ID
image_ref1条件必选File由您自己提供的参照人脸照片，File类型。当comparison_type=0时，必选。
image_ref2可选File由您自己提供的参照人脸照片，File类型

返回结果

字段类型说明
biz_tokenString生成的biz_token，该字段后续用于调用小程序。请求调用成功时会返回biz_token字段
request_idString用于标示本次请求的唯一的字符串，总返回该字段
time_usedInt整个请求所花费的时间，单位为毫秒，总返回该字段
errorString错误原因，请求调用失败时返回error字段, 该字段可能的内容参见下面的错误说明

错误说明

error字段可能的错误包括：

HTTP状态码error说明
400MISSING_ARGUMENTS:缺少某个必选参数（参数名为key）
400BAD_ARGUMENTS:某个参数（参数名为key）解析出错
403AUTHORIZATION_ERROR:鉴权失败，例如可能的原因是签名过期(EXPIRED_SIGN), 签名错误(INVALID_SIGN), API_KEY停用(API_KEY_BE_DISCONTINUED),未进行企业认证(NON_ENTERPRISE_CERTIFICATION),余额不足(BALANCE_NOT_ENOUGH), 等等
429CONCURRENCY_LIMIT_EXCEEDED请求超过并发
500INTERNAL_ERROR内部错误
413Request Entity Too Large客户发送的请求大小超过了20MB限制

示例

示例：仅做验证

curl -X POST "https://openapi.faceid.com/lite/v1/get_biz_token"
-F sign=<sign>
-F sign_version=hmac_sha1
-F return_url=<return_url>
-F notify_url=<notify_url>
-F liveness_type=video_number
-F comparison_type=0

返回结果示例：成功

{
    "request_id": "1462257147,3149525e-2c24-4862-8e9f-92040595f0a4",
    "time_used": 5,
    "biz_token":"1462257147,34fb21937e47ae719f11cbc719615687",
}

返回结果示例：return_url没填导致的错误

{
    "request_id": "1461740007,71eeb124-08f0-47b3-8fc8-ac048cfa1372",
    "time_used": 4,
    "error": "MISSING_ARGUMENTS:return_url",
}

第2步：下载小程序包，并集成

下载地址：https://faceid.com/faceopen/pages/sdk_download

下载"验证微信小程序包"

下面以一个例子进行详细的说明，第一个页面(index页面）用来输入biz_token（biz_token的获取方式参见步骤1），点击确认后，会调用Face ID小程序进行验证。验证完成后，由verify.js处理回调。

  • 下载得到的压缩包解压后得到faceid-components幕布，将该目录添加至项目文件根目录。如下图所示： 1

  • 在index/index.json文件中增加以下配置：

{
  "usingComponents": {
      "base": "../../faceid-components/components/base/base",
      "modal": "../../faceid-components/components/modal/modal"
  }
}
  • 在index/index.js中处理输入token提交的逻辑，示例代码如下：
Page({
  data: {

  },
  onLoad: function () {
  },
  formSubmitProd: function (e) {
    const {token} =  e.detail.value;
    if (!token) {
      this.modal.showModal({
        message: 'token不能为空'
      });
      return;
    }
    wx.navigateTo({
      url: `../verify/verify?token=${token}`
    });
  },
})
  • 在verify/verify.json文件中增加以下配置：
{
  "usingComponents": {
    "faceid-verify": "../../faceid-components/components/index/index"
  }
}
  • 在verify/verify.wxml中定义传递的参数和回调函数，参见：
<!--pages/verify/verify.wxml-->
<faceid-verify token="{{token}}" bind:onFinish="onFinish"/>
  • 在verify/verify.js中完成回调函数, status是状态信息，包括"complete"和”tokenError", 建议当status为complete时调用第3步get_result接口获取进一步信息；为tokenError时调用第1步get_biz_token接口重新申请token
// 定义验证流程结束的回调函数
  onFinish: function (e) {
    console.log(e.detail);
    const {token,status} = e.detail;
    wx.showModal({
      title: '验证流程结束',
      content: token + ',' + status,
      success: function () {
        wx.navigateBack();
      }
    });

注意：正式环境需要在微信公众平台配置小程序的服务器域名 将https://openapi.faceid.com 添加到服务器域名列表中，测试环境可以打开微信开发者工具内 不校验合法域名、web-view（业务域名）、TLS 版本以及 HTTPS 证书

其他说明

  • 进入FaceID 小程序后，就开始进入了FaceID 验证的流程。
  • 处理notify的示例代码如下：
public class ParamController {
    /**
    * notify_url 使用 JavaSpring MVC 框架接受post过来的表单参数
    */
    @RequestMapping(method = RequestMethod.POST, value = "/notify")
    @ResponseBody

    public String toNotify(HttpServletRequest request){
        //获取notify过来的json
        String data = request.getParameter("data");
        System.out.println(String.format("%s",data));
        return String.format("%s",data);
    }
}

页面中典型错误提示和说明

错误提示说明
无效请求，或当前请求已过期Token过期，或者无效token
视频中没有检测到人脸，请重试活体验证过程中，录入的视频中找不到人脸
视频过长，请重试活体验证过程中，录入的视频过大（最大值为20M）
视频质量太差，请重试活体验证过程中，录入的视频质量太差，无法进行识别
未通过念数字识别，请重试活体验证过程未数字语音识别
没有声音，请重试活体验证过程中，录入的视频没有声音，可能的原因是用户手机中未开启该浏览器的语音权限
视频格式无法识别，请重试活体验证过程中，录入的视频格式无法识别

第3步（可选）：获取验证详细信息

API名称

get_result

说明

验证流程结束后，用户服务器可以调用get_result接口，获取本次验证的详细信息。

API地址

GET https://openapi.faceid.com/lite/v1/get_result

参数

参数名可选/必选类型说明
sign必选String根据API_KEY和API_SECRET生成的签名，签名算法参见相关文档
sign_version必选String签名算法版本，当前仅支持：hmac_sha1
biz_token必选Stringget_biz_token接口返回的biz_token
verbose可选Int表示返回数据的详细程度，取值如下：
0：仅返回结论；
1：默认值，返回结论与摘要信息

返回结果

字段类型说明
request_idString用于标示本次请求的唯一的字符串，总返回该字段
time_usedInt整个请求所花费的时间，单位为毫秒，总返回该字段
errorString错误原因，请求调用失败时返回error字段, 该字段可能的内容参见下面的错误说明
biz_tokenString传入的biz_token，原样返回
biz_noString之前在get_biz_token中设置的biz_no字段，如果没有设置，返回为空字符串
result_codeInt结果码
result_messageString结果信息
actionString当前该字段为空列表
imagesJson字段如下：
image_best: 活体检测获得的最优照片，base64编码。该照片会和用户上传的上传照片进行比对。
verificationJson人脸比对的详细结果，可能的字段如下：
- ref1: Json类型，表示活体照片和image_ref1的比对结果
-- confidence: 比对结果的置信度，Float类型，取值［0，100］，数字越大表示风险越小。
-- thresholds: 一组用于参考的置信度阈值，Json类型，包含三个字段，均为Float类型、取值［0，100］:
--- 1e-3: 误识率为千分之一的置信度阈值;
--- 1e-4: 误识率为万分之一的置信度阈值;
--- 1e-5: 误识率为十万分之一的置信度阈值;
--- 1e-6: 误识率为百万分之一的置信度阈值;

- ref2: Json类型，表示活体照片和image_ref2的比对结果，字段和上面的相同。

结果码说明

result_coderesult_message说明
1000SUCCESS待比对照片与上传照片对比是同一个人
2000PASS_LIVING_NOT_THE_SAME待比对照片与上传照片对比不是同一个人
4100FAIL_LIVING_FACE_ATTACK云端活体验证失败
4100CHANGE_FACE_ATTACK活体验证视频中发生了换脸攻击（视频中不是同一个人）
4200NO_FACE_FOUND活体验证视频中没有检测到人脸
4200FACE_QUALITY_TOO_LOW活体验证视频中质量太差
4200INVALID_VIDEO_DURATION活体验证视频中长度不符合要求（2s～20s）
4200VIDEO_TOO_LARGE活体验证视频过大
4200SR_ERROR活体验证视频中，用户读数语音不符合要求
4200NOT_SYNCHRONIZED活体验证视频中，用户读数唇语不符合要求
4200NO_AUDIO活体验证视频无声音
4200VIDEO_FORMAT_UNSUPPORTED活体验证视频格式无法识别
4200LIP_VOICE_NOT_SYNC活体验证视频中语音唇语不同步
4200VIDEO_OK活体验证视频可用
4200VIDEO_MANY_TIMES活体验证视频上传超过阈值（默认为3，get_biz_token接口中liveness_retry_count参数可以设置）
4200VIDEO_INTERNAL_ERROR活体验证内部错误
5000NON_ENTERPRISE_CERTIFICATION客户未进行企业认证
5000BALANCE_NOT_ENOUGH余额不足
5000ACCOUNT_DISABLED账户已停用
6000USER_CANCEL用户主动退出流程
9000==LIVING_NOT_START==验证流程尚未开始

错误说明

error字段可能的错误包括：

error说明HTTP状态码
MISSING_ARGUMENTS:缺少某个必选参数（参数名为key）400
BAD_ARGUMENTS:某个参数（参数名为key）解析出错400
BIZ_TOKEN_USEDbiz_token 已使用400
AUTHORIZATION_ERROR:鉴权失败，例如可能的原因是签名过期(EXPIRED_SIGN), 签名错误(INVALID_SIGN), API_KEY停用(API_KEY_BE_DISCONTINUED),未进行企业认证(NON_ENTERPRISE_CERTIFICATION),余额不足(BALANCE_NOT_ENOUGH), 等等403
DATA_DESTROYED超过可查询时间或超过最多可查询次数403
TOO_MANY_REQUESTS请求超过并发429
INTERNAL_ERROR内部错误500

verification示例

人脸比对(comparison_type=0), 传入了image_ref1, image_ref2

"verification": {
    "ref1": {    ## 活体照片和上传照片1的比对结果
        "confidence": 86.4735,
        "thresholds": {
            "1e-3": 62.168713,
            "1e-4": 69.31534,
            "1e-5": 74.39926,
            "1e-6": 78.038055
        },
      "ref2": {    ## 活体照片和上传照片2的比对结果
          "confidence": 86.4735,
          "thresholds": {
              "1e-3": 62.168713,
              "1e-4": 69.31534,
              "1e-5": 74.39926,
              "1e-6": 78.038055
          }
      }
    }
}

当前版本

  • v1.0.0

历史版本

← H5接入说明产品介绍 →