字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

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字段的值进行预脱敏，例如进行哈希处理。

"123456abcd"

sceneCode

String

64

否

null

场景码，用来为数据分析指定不同的业务场景。

当需要区分不同业务场景中的数据表现时，建议根据业务用途为sceneCode字段设置不同的值，例如login、riskVerify、payment、changePassword。

"changePassword"

serviceLevel

String

32

否

CONNECT0002

该参数已不再推荐使用，建议设置productConfig中的具体参数。

人脸活体检测服务等级。取值如下：

• CONNECT0001：该等级具有基本的活体检测能力。检测过程直接在原页面完成，从而减少了用户流失。该等级适用于对通过率要求较高的场景。
• CONNECT0002：该等级具有基本的活体检测能力。ZOLOZ SDK使用眨眼检测方法进行活体检测。
• CONNECT0003：该等级具有高等级的活体检测能力。ZOLOZ SDK使用多动作检测方法进行活体检测。

说明：H5模式不支持传入serviceLevel字段。

"CONNECT0002"

operationMode

String

32

否

STANDARD

该参数已不再推荐使用，建议设置productConfig中的具体参数。

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

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

说明：H5模式不支持传入operationMode字段。

"STANDARD"

h5ModeConfig

H5ModeConfig

-

否

null

H5 Connect的配置信息。详细信息，请参见H5ModeConfig。

说明：当metaInfo的值为MOB_H5时必须传入该字段。

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

productConfig

ProductConfig

-

否

null

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

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

{

   "livenessMode":"STANDARD",

   "actionCheckItems":["FACEBLINK","HEADLOWER"],

   "actionRandom":"Y",

   "deeperMode":"STANDARD"

 }

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

state

String

128

否

transactionId字段的值

用于恢复客户上下文的标识符。您可以为该字段设置任意值，当ZOLOZ SDK回调商户的移动App时会将该值作为参数传递。

"G006600016CN20190114000000009572520355"

completeCallbackUrl

String

128

是

-

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

"http://xxx.html"

interruptCallbackUrl

String

128

是

-

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

"http://xxx.html"

locale

String

16

否

en

网页语言，目前支持以下语言：

• en：英语
• id：印尼语
• zh-CN：简体中文

"en"

isIframe

String

1

否

N

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

"Y"

uiCfg

String

256

否

null

自定义UI配置，采用JSON字符串格式。目前仅支持titlebarbgcolor、titlebartextcolor和buttoncolor。

"{\"titleBackgroudColor\": \"#0064FF\",\"titleTextColor\": \"#FFFFFF\",\"topTipColor\": \"#0064FF\"}"

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

livenessMode

String

10

否

STANDARD

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

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

"STANDARD"

antiInjectionMode

String

10

否

CLOSED

该参数已废弃，后续不再维护，为了保证API兼容性，该参数会继续保留。

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

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

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

"CLOSED"

actionCheckItems

List<String>

-

否

FACEBLINK

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

• FACEBLINK：眨眼
• MOUTHOPEN：张嘴
• HEADSHAKE：摇头
• HEADLOWER：低头
• HEADRAISE：抬头
• NOACTION：无动作。当actionCheckItems设置为NOACTION时，SDK版本需满足以下要求：

• iOS SDK：使用1.5.5.250519182352及以上版本
• Android SDK：使用1.5.5.250519101845及以上版本

说明：

• NOACTION与其他动作互斥，不能同时设置。
• 为确保更好的用户体验，建议仅选择一种动作，避免同时使用两种及以上动作。
• 每种动作类型只能传入一次，请勿重复传入相同的动作类型。

["FACEBLINK","HEADLOWER"]

actionRandom

String

1

否

N

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

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

"Y"

deeperMode

String

10

否

CLOSED

AIGC攻击检测的Deeper等级，Deeper检测功能的详细介绍，请参见什么是Deeper。该参数支持以下取值：

• CLOSED：Deeper的所有能力均不开启，例如AIGC检测算法、终端风险检测等。如果业务场景不需要AIGC攻击检测，则无需开启。
• STANDARD：推荐的标准等级。
• LOOSE：相对宽松的等级，可用于低风险场景。
• STRICT：相对严格的等级，可用于高风险场景。

注意：需要先购买Deeper产品，才能使用该功能。

"STANDARD"

字段名称

数据类型

必须返回

描述

示例值

result

Result

是

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

{

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

}

transactionId

String

否

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

说明：仅当交易进入处理阶段后系统才会返回transactionId。如果在开始处理交易之前发生错误，系统不会返回transactionId。包括但不限于以下情况：

• 请求参数非法，例如入参格式错误或缺失必传参数。
• 请求未能成功到达服务器，例如网络问题或网关故障。
• 系统限流导致请求被拒绝。

"G006600016CN20190114000000009572520355"

clientCfg

String

否

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

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

"……"

结果码

结果状态

描述

SUCCESS

S

API调用成功。

UNABLE_GET_IMAGE

F

未找到参考源（因未注册而验证导致的错误）。

HIGH_RISK

F

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

ACCOUNT_SERVICE_SUSPEND

F

用户账号被风险引擎列入黑名单。

DEVICE_NOT_SUPPORT

F

不支持当前的设备类型。

OS_NOT_SUPPORT

F

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

SDKVERSION_NOT_SUPPORT

F

不支持ZOLOZ SDK当前的版本。

INVALID_ARGUMENT

F

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

SYSTEM_ERROR

F

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