initialize

概览

  • API URL:/api/v1/zoloz/facecapture/initialize
  • API 描述:该接口用于初始化ZOLOZ中的人脸采集进程,并为其生成一个唯一的事务ID。后续在与ZOLOZ交互的所有过程中均使用该事务ID。

说明:该接口不支持重复调用,即不符合幂等性。

请求参数

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

bizId

String

32

-

业务ID,业务的唯一标识,用于追踪业务。例如,商户业务相关数据库中的序列号。

说明:ZOLOZ服务器不检查该字段的值是否唯一。为了更便捷地追踪业务,建议开启商户服务器,并确保业务ID的唯一性。

"2017839040588699"

metaInfo

String

512

-

SDK和用户设备的元信息。该字段的值由ZOLOZ SDK以JSON字符串格式返回。

说明:不要修改返回值,直接传递即可。如果是H5接入模式,则设置为MOB_H5

"{ \"deviceType\": \"android\", \"appVersion\": \"1.0.9\", \"osVersion\": \"9\", \"appName\": \"com.zoloz.atomic.client\", \"bioMetaInfo\": \"3.46.0:2916352,0\", \"apdidToken\": \"69b74bfe-bf7f-4d3b-ac59-907ee09e7955\", \"deviceModel\": \"MI 6\", \"zimVer\": \"1.0.0\" }"

userId

String

64

-

商户的用户ID或其他可用于识别某一用户的标识,例如手机号码、电子邮件地址等。

建议对userId字段的值进行预脱敏,例如进行哈希处理。

"not mandatory"

serviceLevel

String

32

FACECAPTURE0002

人脸活体检测和用户动作检测的服务等级。取值如下:

  • FACECAPTURE0001:ZOLOZ使用无交互人脸活体检测。
  • FACECAPTURE0002:ZOLOZ使用眨眼检测方法进行活体检测。
  • FACECAPTURE0003:ZOLOZ使用多动作检测方法进行活体检测。这些动作从以下列表中随机选择两个:眨眼、张嘴、抬头、低头、左摇头、右摇头。
  • FACECAPTURE0005:ZOLOZ使用眨眼检测方法进行活体检测。该服务等级会额外采集一张闭眼的人脸图片,且该服务等级仅支持在原生SDK模式下使用。
  • FACECAPTURE0010:ZOLOZ使用眨眼检测方法进行活体检测。该服务等级会额外采集一张闭眼的人脸图片,且该服务等级仅支持在Web SDK模式下使用。

"FACECAPTURE0002"

operationMode

String

32

STANDARD

为身份验证配置操作模式。取值如下:

  • CLOSED:所有的算法和风控规则都未开启。该操作模式可用于测试场景,测试进程不受算法和风控规则的影响。
  • STANDARD:推荐的标准模式。
  • LOOSE相对宽松的模式,可用于低风险场景。
  • STRICT:相对严格的模式,可用于高风险场景。

"STANDARD"

h5ModeConfig

H5ModeConfig

-

null

H5 Face Capture的配置信息。详细信息,请参见H5ModeConfig

{ "completeCallbackUrl":"http://xxx/result.html", "interruptCallbackUrl":"http://xxx/result.html" }

productConfig

ProductConfig

-

null

为Face Capture产品提供更精细化的控制。详细信息,请参见ProductConfig

说明:如果同时设置了productConfig、serviceLevel和operationMode,则serviceLevel和operationMode均不生效,ZOLOZ将只读取productConfig的值。

{ "livenessMode":"STANDARD", "antiInjectionMode":"CLOSED", "actionCheckItems":["FACEBLINK","HEADLOWER"], "actionRandom":"Y", "actionFrame:":["EYECLOSE"] }

H5ModeConfig字段说明

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

state

String

128

transactionId字段的值

用于恢复客户上下文的标识符。

您可以为该字段设置任何值,当ZOLOZ SDK回调商户的移动App时将该值作为参数进行传递。

"G006600016CN20190114000000009572520355"

completeCallbackUrl

String

128

-

当整个身份验证完成时,为浏览器指定即将重定向的回调URL。

"http://xxx/result.html"

interruptCallbackUrl

String

128

-

当进程中断时,为浏览器指定重定向到的回调URL。

"http://xxx/result.html"

isIframe

String

1

N

是否需要在iframe中打开网页,如果需要设置为Y,否则设置为N。

"Y"

locale

String

16

en

网页语言,目前仅支持以下语言:

  • en(英语)
  • id(印度尼西亚语)
  • fl(菲律宾语)

"en"

uiCfg

String

256

null

自定义UI配置,采用JSON字符串格式。仅支持isDesktop

"{\"isDesktop\":\"Y\"}"

ProductConfig字段说明

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

livenessMode

String

10

STANDARD

人脸活体检测等级。取值如下:

  • CLOSED:所有的算法和风控规则都未开启。该等级可用于测试场景,测试进程不受算法和风控规则的影响。
  • STANDARD:推荐的标准等级。
  • LOOSE:相对宽松的等级,可用于低风险场景。
  • STRICT:相对严格的等级,可用于高风险场景。

"STANDARD"

antiInjectionMode

String

10

CLOSED

防注入检测等级。防注入检测能够有效抵御使用换脸图片或视频进行的注入攻击。取值如下:

  • CLOSED:所有的防注入算法都不开启。如果业务场景不需要注入攻击检测,则不需要开启。
  • STANDARD:推荐的标准等级。
  • LOOSE预留等级,暂不支持使用。
  • STRICT预留等级,暂不支持使用。

注意:开启防注入检测会略微增加误报率和运行时间,开启前请先联系ZOLOZ技术支持。

"CLOSED"

actionCheckItems

List<String>

-

FACEBLINK

客户端和Web端的动作检测列表。取值如下:

  • FACEBLINK:眨眼
  • MOUTHOPEN:张嘴
  • HEADSHAKE:摇头
  • HEADLOWER:低头
  • HEADRAISE:抬头

说明:为了更好的用户体验,不建议使用两种及以上的动作。

["FACEBLINK","HEADLOWER"]

actionRandom

String

1

N

客户端和Web端的动作检测顺序是否随机。取值如下:

  • Y:随机。
  • N:不随机,则按照actionCheckItems中的顺序进行检测。

"Y"

actionFrame

List<String>

-

null

采集其他帧图片。取值如下:

  • EYECLOSE闭眼帧。

["EYECLOSE"]

rearCamera

String

1

N

是否使用后置摄像头,仅支持在Web SDK模式下使用。取值如下:

  • Y:使用后置摄像头。
  • N:使用前置摄像头。

说明:当rearCamera设置为Y时,使用后置摄像头采集人脸,仅支持静默采集或眨眼采集。

"Y"

cropFaceImage

String

1

N

是否额外返回一张裁剪出脸部区域的人脸图片。取值如下:

  • Y:是
  • N:否

"Y"

checkDeviceRisk

String

1

N

是否开启设备风险检测。取值如下:

  • Y:开启设备风险检测。
  • N:不开启设备风险检测。

"Y"

返回参数

字段名称

数据类型

必须返回

描述

示例值

result

Result

API请求结果,包含结果状态、结果码和结果消息。

{

"resultStatus": "S", "resultCode": "SUCCESS", "resultMessage": "Success"

}

transactionId

String

ZOLOZ服务器为人脸采集进程生成的唯一事务ID。此ID将作为Face Capture checkresult API请求的输入参数。

说明:当人脸采集进程出现错误时,例如参数无效,则不返回事务ID。

"G006600016CN20190114000000009572520355"

clientCfg

String

客户端配置信息,包括SDK连接和行为参数。

说明:当result.resultStatus的值为S时,才返回该字段。

"……"

处理结果

根据请求结果执行下一步的响应动作,具体如下:

  • 当result.resultStatus的值为S时,表示调用ZOLOZ Face Capture initialize API成功,并返回唯一的事务ID。
  • 当result.resultStatus的值为F时,表示调用ZOLOZ Face Capture initialize API失败。请检查错误码获取有关该错误的更多信息,并分析导致该错误的原因。

API通用结果码

有关通用结果码的完整列表,请参见API通用结果码

API特有结果码

Face Capture initialize API的结果码见下表。

结果码

结果状态

描述

SUCCESS

S

API调用成功。

HIGH_RISK

F

检测到高风险。用户账号被风险引擎冻结。

DEVICE_NOT_SUPPORT

F

不支持当前的设备类型。

OS_NOT_SUPPORT

F

不支持当前设备的操作系统。

SDKVERSION_NOT_SUPPORT

F

不支持ZOLOZ SDK当前的版本。

INVALID_ARGUMENT

F

输入参数无效。关于无效参数的详细信息,请查看返回的resultMessage。

SYSTEM_ERROR

F

其他内部错误。有关错误详情,请查看返回的resultMessage。

代码示例

不同的接入模式请求结构略有不同。在H5模式下初始化人脸采集进程时,必须指定H5ModeConfig对象。

请求示例

  • 原生Face Capture请求示例
copy
{
  "bizId":"2017839040588699",
  "metaInfo": "{\"apdidToken\":\"69b74bfe-bf7f-4d3b-ac59-907ee09e7955\",\"appName\":\"com.zoloz.atomic.client\",\"appVersion\":\"1.0.9\",\"bioMetaInfo\":\"3.46.0:2916352,0\",\"deviceModel\":\"MI 6\",\"deviceType\":\"android\",\"osVersion\":\"9\",\"zimVer\":\"1.0.0\"}",
  "userId": "not mandatory",
  "productConfig": {
    "livenessMode":"STANDARD",
    "antiInjectionMode":"CLOSED",
    "actionCheckItems":["FACEBLINK","HEADLOWER"],
    "actionRandom":"Y",
    "actionFrame:":["EYECLOSE"]
  }
}
  • H5 Face Capture请求示例
copy
{
  "bizId":"dummy_bizid_1626180988600",
  "metaInfo":"MOB_H5",
  "userId":"dummy_userid_1626180988600",
  "h5ModeConfig":{
      "completeCallbackUrl":"http://xxx/result.html",
      "interruptCallbackUrl":"http://xxx/result.html"
  },
  "productConfig": {
    "livenessMode":"STANDARD",
    "antiInjectionMode":"CLOSED",
    "actionCheckItems":["FACEBLINK","HEADLOWER"],
    "actionRandom":"Y",
    "actionFrame:":["EYECLOSE"]
  }
}

返回示例

ZOLOZ服务器返回的响应代码示例。

copy
{
    "result": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "Success"
    },
    "transactionId":"G006600016CN20190114000000009572520355", 
    "clientCfg": "……"   
}