initialize

2024-11-05 07:22

概览

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使用较为宽松的活体检测方式，需配合operationMode的值进行判定。 `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", "deeperMode":"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	该参数已废弃，后续不再维护，为了保证API兼容性，该参数会继续保留。防注入检测等级。防注入检测能够有效抵御使用换脸图片或视频进行的注入攻击。取值如下： `CLOSED`：所有的防注入算法都不开启。如果业务场景不需要注入攻击检测，则不需要开启。 `STANDARD`：推荐的标准等级。 `LOOSE`：预留等级，暂不支持使用。 `STRICT`：预留等级，暂不支持使用。注意：开启防注入检测会略微增加误报率和运行时间，开启前请先联系ZOLOZ技术支持。	"CLOSED"
deeperMode	String	10	否	CLOSED	AIGC攻击检测的Deeper等级，Deeper检测功能的详细介绍，请参见什么是Deeper。该参数支持以下取值： `CLOSED`：Deeper的所有能力均不开启，例如AIGC检测算法、终端风险检测等。如果业务场景不需要AIGC攻击检测，则无需开启。 `STANDARD`：推荐的标准等级。 `LOOSE`：相对宽松的等级，可用于低风险场景。 `STRICT`：相对严格的等级，可用于高风险场景。注意：需要先购买Deeper产品，才能使用该功能。	"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	该参数已废弃，替代参数为`deeperMode`。注意：为了保证API兼容性，该参数会继续保留。当该参数设置为`Y`时，checkresult API的返回数据中仍会返回`deviceRisk`字段，但检测出的任何风险都不会用于业务决策，也不会影响最终结果。	"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",
    "deeperMode":"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",
    "deeperMode":"CLOSED",
    "actionCheckItems":["FACEBLINK","HEADLOWER"],
    "actionRandom":"Y",
    "actionFrame:":["EYECLOSE"]
  }
}

返回示例

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

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