常见问题

2025-04-29 04:01

本文为您列出了ZOLOZ eKYC SaaS产品相关FAQs。

通用FAQ

RealID支持哪些证件类型？

RealID支持的证件类型，请参见RealID和ID Recognition支持的证件类型和返回的OCR结果。

RealID中的IDN和独立IDN有什么区别？

RealID中的IDN可通过入参开关来启用或禁用，具备数据自动入库及自动进行风险检测的能力。独立IDN需要客户手动录入数据，并主动调用API进行风险查询。如需了解IDN的全部功能，请参见IDN接口文档。

RealID中的IDN和独立IDN存在以下区别：

对比项	RealID中的IDN	独立IDN
支持场景	仅支持IDN中的KYC场景	KYC和Verification场景均支持
风险查询	自动查询，通过入参开启IDN风险查询功能。	需要客户调用API，根据入参中输入的数据查询风险。
检索时间窗口	默认查询最近30天的数据，可通过入参调整风险查询时间窗口，最长可查询180天的数据。	默认查询最近180天的数据，可通过入参调整风险查询时间窗口，最长可查询180天的数据。
支持的数据量级	单次扫描的数据量最多为50万条	单次扫描的数据量最多为50万条
风险场景及类型	支持KYC场景中的全部功能，包含IDFAKE、DUPLICATE、BATCH_REGISTER、DEEPFAKE。 IDFAKE： SameFaceDifferentIdNumber SameFaceDifferentPerson SameIdDifferentFace SameIdDifferentPerson SamePersonDifferentFace SamePersonDifferentIdNumber DUPLICATE： SameFaceDifferentIdType SameFaceDifferentUserId BATCH_REGISTER： SameFaceBackgroundDifferentFace DEEPFAKE： SameFaceBackgroundDeepfakeFace	支持KYC和Verification场景中的全部功能。 KYC场景 IDFAKE： SameFaceDifferentIdNumber SameFaceDifferentPerson SameIdDifferentFace SameIdDifferentPerson SamePersonDifferentFace SamePersonDifferentIdNumber DUPLICATE： SameFaceDifferentIdType SameFaceDifferentUserId BATCH_REGISTER： SameFaceBackgroundDifferentFace DEEPFAKE： SameFaceBackgroundDeepfakeFace Verification场景 DUPLICATE_VERIFICATION： SamePhotoSameUserId
数据来源	通过RealID采集的数据，且这些数据会自动存储到数据库中。	通过RealID采集的数据和其他外部数据，这些数据均需要调用add API手动录入数据库。
库管理	不支持	支持在数据库中进行添加、删除、检索等操作。

调用隐私删除API可以删除哪些数据？

隐私删除API可以删除以下三类数据：

OCR信息，例如证件ID、姓名等。
采集的证件和人脸照片数据，例如返回的人脸图片（faceImg）、额外需要返回的图片（extraImages）、证件的正面照（frontPageImg）、证件的背面照（backPageImg）等。
RealID IDN Lite相关数据，且IDN Lite无法再处理或访问已经被隐私删除API删除的相关数据。

证件图片采集有什么要求？

ZOLOZ对采集的证件图片的大小和质量有一定要求，按要求完成采集可以有效提升证件图片的采集成功率。

采集要求	详细描述	正确示例	错误示例
证件完整入框	确保证件的四个角点和边都在采集框内。
证件图片清晰	确保证件图片清晰可辨，没有模糊区域。
光线充足	确保采集环境光线充足，以便有效识别证件上的信息。采集环境太亮或太暗，可能会影响验证效果。
避免反光	避免灯光或环境光的反射，证件图片上的反光会干扰数据的处理和提取。
避免镭射纹干扰	避免灯光或环境光造成的镭射纹干扰，证件图片上的镭射纹会干扰数据的处理和提取。
避免遮挡	确保证件无任何遮挡物，证件上的信息完全可见。
避免倾斜	确保拍摄的证件在水平和垂直方向都保持完全平整，无任何倾斜。
距离适中	请将证件的四条边与扫描框对齐，距离太远或太近都会影响采集结果。
合适的倾斜角度（仅适用于多角度版）	请将证件的四条边与倾斜的扫描框对齐，倾斜角度通常不超过30度。

eKYC结果判定

防伪检测不通过的交易，其状态为何为Pending而非Failure？

因防伪检测不通过而被判定为Pending的交易，如果直接将其判定为Failure，极可能导致合法的交易被误拦截，因为防伪检测不通过的交易可能存在一定的误判率，例如在光线不足或者部分证件信息模糊等情况下，ZOLOZ系统难以做出精准判断。

为了确保交易判断的准确性，ZOLOZ会将此类交易标记为Pending，以便客户在自己的业务系统中，通过人工审核的方式对疑似风险的交易进行进一步核实与确认。客户可以根据ZOLOZ系统输出的防伪结果审查伪造痕迹，例如，如果ZOLOZ系统提示证件环境屏幕翻拍检测异常，客户可重点检查该笔交易的证件图片是否由屏幕翻拍伪造而成，并根据实际情况手动调整交易状态。通过人工审核，客户可最大限度降低误判率，更好地保护自身利益。

为什么RealID的Risk Control Result返回为空？

Risk Control Result返回为空，说明未触发风控策略，具体包含以下几种原因：

证件验证或人脸验证失败。
初始化失败。
用户中途取消了身份验证。

SDK&API使用相关

如何更新ZOLOZ SDK？

不同平台的SDK的更新步骤不相同，通常情况下您可以参考以下内容更新ZOLOZ SDK。

Android SDK更新

打开Gradle配置文件。在您的Android项目中找到app/build.gradle文件，可参考Android客户端接入。
更新SDK依赖。找到包含ZOLOZ SDK的代码行，并将其更新为新的版本号。例如：

copy
implementation 'com.zoloz.android.build:zolozkit:latest-version'

说明：请将latest-version替换为您希望更新到的实际版本号。建议您使用最新版SDK，可提升产品体验和安全性。版本发布说明，请参见Release Notes。

同步项目。编辑build.gradle文件后，您需要同步项目以更新Gradle文件。

iOS SDK更新

配置SDK依赖。

在Podfile中配置私有规范。

copy
source "https://github.com/zoloz-pte-ltd/zoloz-demo-ios"

在Podfile中添加SDK依赖。

copy
#zolozkit变更日志：https://docs.zoloz.com/zoloz/saas/releasenotes/

# #建议您使用最新版SDK，其包含了新功能并在安全方面进行了改进。如果您需要有关特定版本的更多信息，请查看变更日志。
pod 'zolozkit'  #核心模块
pod 'zolozkit/ZolozNfcReader' #NFC Reader模块

说明：代码pod 'zolozkit/ZolozNfcReader'对应NFC功能，如需开通该功能，请联系ZOLOZ技术支持；如果不需要使用该功能，则无需添加对应的代码。

更新Pod。运行以下命令更新SDK。

copy
pod update

处理错误。常见错误：如果您在更新过程中遇到以下错误。处理方法：使用以下任意一种命令更新本地仓库索引，然后再次尝试更新。

copy
pod install --repo-update

copy
pod repo update

完成更新。

Web SDK更新

Web SDK和Android SDK、iOS SDK的更新不同，如果系统检测到新版本，Web SDK会自动进行更新，无需您手动更改代码库。

为什么在拒绝Face Capture的传感器访问权限后，Web SDK无法打开人脸采集页面？

开启Face Capture-Deeper后，ZOLOZ会访问手机的传感器权限，由于iOS系统限制，当用户拒绝为ZOLOZ授予传感器权限后，Web SDK无法再打开人脸采集页面，客户可根据收到的返回码重启WebView或提示用户重启浏览器重新进行授权。具体返回码，请参见ZLZResponse。

RealID、Face Capture和ID Recognition的serviceLevel参数支持哪些类型？

ZOLOZ通过RealID、Face Capture和ID Recognition提供各种身份验证服务，并通过设置不同的serviceLevel参数值，为API自定义所需的服务级别。

下表列出了RealID、Face Capture和ID Recognition支持的服务级别。

产品	字段名称	描述	参考文档
RealID	serviceLevel	防伪检测和人脸活体检测的服务等级。该参数基于不同的集成模式，预设了检测等级、人脸动作、采集帧等配置，如需自定义这些配置，请使用productConfig相关字段。 serviceLevel支持的取值，详见serviceLevel配置说明。	RealID initialize
Face Capture		`FACECAPTURE0001`：ZOLOZ使用较为宽松的活体检测方式，需配合operationMode的值进行判定。 `FACECAPTURE0002`：ZOLOZ使用眨眼检测方法进行活体检测。 `FACECAPTURE0003`：ZOLOZ使用多动作检测方法进行活体检测。这些动作从以下列表中随机选择两个：眨眼、张嘴、抬头、低头、左摇头、右摇头。 `FACECAPTURE0005`：ZOLOZ使用眨眼检测方法进行活体检测。该服务等级会额外采集一张闭眼的人脸图片，且该服务等级仅支持在原生SDK模式下使用。 `FACECAPTURE0010`：ZOLOZ使用眨眼检测方法进行活体检测。该服务等级会额外采集一张闭眼的人脸图片，且该服务等级仅支持在Web SDK模式下使用。	Face Capture initialize
ID Recognition		`IDRECOGNITION0002`：基础防伪等级。 `IDRECOGNITION0003`：使用闪光交互模式的高阶防伪等级。如果设置了该值，ZOLOZ SDK会自动扫描身份证件。该等级仅支持在原生SDK模式下使用。 `IDRECOGNITION0005`：使用多角度交互模式的高阶防伪等级。该等级仅支持在Web SDK模式下使用，且目前该等级仅支持中国香港身份证。	ID Recognition initialize

注意：RealID和Face Capture已支持通过productConfig中的参数进行更灵活的配置，如果设置了下表中的参数值，将优先读取下表中的参数，不再读取serviceLevel和operationMode的值。原有的serviceLevel和operationMode将继续维护，您可以继续使用不会受任何影响。

RealID相关的productConfig参数

下表列出了RealID中productConfig相关的参数及描述，更多详情请参见RealID initialize。

字段名称	数据类型	最大长度	是否必填	默认值	描述
docUiType	String	20	否	Native SDK：2 Web SDK：1	证件照片的采集方式。取值如下： `1`：手拍版（Self-capture），用户需要手动拍摄证件照片，仅具备基础防伪能力。 `2`：Native防伪版（Deep-scan），仅适用于Native SDK。ZOLOZ SDK将自动对齐并拍摄证件照片，具备拦截彩打等高级防伪能力。 `3`：H5扫描版（Auto-scan），仅适用于Web SDK。ZOLOZ SDK将自动对齐并拍摄证件照片，仅具备基础防伪能力。建议Web SDK使用自动扫描的采集方式，因为与手拍版相比，自动扫描的用户体验更好且证件图片质量更高。 `4`：甩证版（Trace-scan），仅适用于Native SDK。当ZOLOZ SDK在摄像头范围内检测到证件时将自动拍摄。该版式可用于提升用户体验，但防伪能力较弱，仅具备基础防伪能力。 `5`：多角度版（Multi-angle），仅适用于Web SDK中的中国香港证件。用户需要分别拍摄正对证件的照片和证件倾斜30°的照片，具备拦截彩打等高级防伪能力。
spoofMode	String	10	否	STANDARD	证件防伪等级。取值如下： `CLOSED`：所有的防伪算法都未开启。该等级可用于测试场景，测试进程不受算法和风控规则的影响。 `STANDARD`：推荐的标准等级。 `LOOSE`：预留等级，暂不支持使用。 `STRICT`：预留等级，暂不支持使用。
livenessMode	String	10	否	STANDARD	人脸活体检测等级。取值如下： `CLOSED`：所有的算法和风控规则都未开启。该等级可用于测试场景，测试进程不受算法和风控规则的影响。 `STANDARD`：推荐的标准等级。 `LOOSE`：相对宽松的等级，可用于低风险场景。 `STRICT`：相对严格的等级，可用于高风险场景。
antiInjectionMode	String	10	否	CLOSED	该参数已废弃，后续不再维护，为了保证API兼容性，该参数会继续保留。防注入检测等级。防注入检测能够有效抵御使用换脸图片或视频进行的注入攻击。取值如下： `CLOSED`：所有的防注入算法都不开启。如果业务场景不需要注入攻击检测，则不需要开启。 `STANDARD`：推荐的标准等级。 `LOOSE`：预留等级，暂不支持使用。 `STRICT`：预留等级，暂不支持使用。注意：开启防注入检测会略微增加误报率和运行时间，开启前请先联系ZOLOZ技术支持。
actionCheckItems	List<String>	-	否	FACEBLINK	客户端和Web端的动作检测列表。取值如下： `FACEBLINK`：眨眼 `MOUTHOPEN`：张嘴 `HEADSHAKE`：摇头 `HEADLOWER`：低头 `HEADRAISE`：抬头说明：为了更好的用户体验，不建议使用两种及以上的动作。
actionRandom	String	1	否	N	客户端和Web端的动作检测顺序是否随机。取值如下： `Y`：随机。 `N`：不随机，则按照actionCheckItems中的顺序进行检测。
actionFrame	List<String>	-	否	空	采集其他帧图片。取值如下： `EYECLOSE`：设置此值可返回在眨眼检测过程中采集的闭眼帧。
riskMode	String	10	否	STANDARD	RealID中的多维度风控规则校验，用于拦截可疑交易。取值如下： `CLOSED`：所有有关风险检测的算法都未开启。该等级可用于测试场景，测试进程不受算法和风控规则的影响。 `STANDARD`：推荐的标准等级。 `LOOSE`：相对宽松的等级，可用于低风险场景。 `STRICT`：相对严格的等级，可用于高风险场景。
idnThreshold	Integer	-	否	3	该参数已废弃，后续不再维护，为了保证API兼容性，该参数会继续保留。指定阈值，用于拦截同一商户同脸不同证或同证不同脸的交易，当不同userId之间的关联交易笔数超过指定的阈值时将被拦截。支持传入大于等于1的任何整数，默认阈值为3。

Face Capture相关的productConfig参数

下表列出了Face Capture中productConfig相关的参数及描述，更多详情请参见Face Capture initialize。

字段名称	数据类型	最大长度	是否必填	默认值	描述
livenessMode	String	10	否	STANDARD	人脸活体检测等级。取值如下： `CLOSED`：所有的算法和风控规则都未开启。该等级可用于测试场景，测试进程不受算法和风控规则的影响。 `STANDARD`：推荐的标准等级。 `LOOSE`：相对宽松的等级，可用于低风险场景。 `STRICT`：相对严格的等级，可用于高风险场景。
antiInjectionMode	String	10	否	CLOSED	该参数已废弃，后续不再维护，为了保证API兼容性，该参数会继续保留。防注入检测等级。防注入检测能够有效抵御使用换脸图片或视频进行的注入攻击。取值如下： `CLOSED`：所有的防注入算法都不开启。如果业务场景不需要注入攻击检测，则不需要开启。 `STANDARD`：推荐的标准等级。 `LOOSE`：预留等级，暂不支持使用。 `STRICT`：预留等级，暂不支持使用。注意：开启防注入检测会略微增加误报率和运行时间，开启前请先联系ZOLOZ技术支持。
actionCheckItems	List<String>	-	否	FACEBLINK	客户端和Web端的动作检测列表。取值如下： `FACEBLINK`：眨眼 `MOUTHOPEN`：张嘴 `HEADSHAKE`：摇头 `HEADLOWER`：低头 `HEADRAISE`：抬头说明：为了更好的用户体验，不建议使用两种及以上的动作。
actionRandom	String	1	否	N	客户端和Web端的动作检测顺序是否随机。取值如下： `Y`：随机。 `N`：不随机，则按照actionCheckItems中的顺序进行检测。
actionFrame	List<String>	-	否	空	采集其他帧图片。取值如下： `EYECLOSE`：设置此值可返回在眨眼检测过程中采集的闭眼帧。

为什么通过App接入Web SDK无法打开或无法正常使用拍摄功能？

问题描述：在App中接入Web SDK，部分手机型号或操作系统会遇到无法打开或无法正常使用拍摄功能的问题。

可能原因：Web SDK必须在App的WebView容器中打开，而WebView的内核和手机操作系统相互绑定，部分手机型号或操作系统的WebView对拍摄功能有限制，从而导致拍摄功能无法打开或无法正常使用。

解决方法：

解决方法一：建议用户跳转手机浏览器后再进行操作。
解决方法二：建议您使用Native SDK接入方式，以便在App中正常使用拍摄功能。

如何隐藏Native SDK的人脸引导页标题栏？

解决方法如下：

Android SDK：将附件📎UI.json添加到项目的assets目录中，即可隐藏人脸引导页的标题栏。
iOS SDK：在人脸引导页的URL中添加hiddenTitleBar参数，并将hiddenTitleBar的取值设置为true（默认为false），例如http://url-to-face-guide-page.html?hiddenTitleBar=true。

注意：如果设置了隐藏人脸引导页的标题栏，ZOLOZ的返回按钮也将一起被隐藏，此时需要您在H5页面内添加一个自定义的返回按钮，并按要求实现事件，详细集成步骤请参见为RealID定制人脸自拍引导页。

ID Recognition SDK和API形态的主要区别是什么？

通过下表中的对比，客户可根据实际业务需求选择适合的形态。SDK形态提供更全面的服务和更优质的用户体验，适用于追求高效集成的客户；API形态则适用于需要高度定制用户界面或已有采集系统的客户。

对比项	SDK形态	API形态
采集页面	ZOLOZ提供证件采集页面，用户可根据页面指引完成证件采集。同时ZOLOZ将持续优化采集页面的能力与性能，保障用户体验。	ZOLOZ不提供证件采集页面，需要客户自行上传证件图片。
链路服务	由服务端、客户端、算法等多方配合，提供一套完整的链路服务。	专注于后端服务，客户需自行完成证件图片的上传。
接口调用响应时间	API响应时间相对较短，响应速度较快。初始化（initialize）和获取结果（checkresult）阶段不涉及较耗时的算法处理，因此响应速度较快，具体调用链路，请参见使用原生App SDK模式接入-交互流程。	API响应时间相对较长，响应速度较慢。每次调用API都要通过网络将请求发送到服务器，并等待服务器处理完成后返回响应结果。在纯API调用场景下，待校验的图片需作为入参传递给服务器。服务器接收到图片后进行算法处理，该过程耗时较长，从而增加了API接口的总响应时间。
证件防伪检测安全	具备多种采集能力，安全性相对更高。采集设备信息：支持采集用户的设备信息，有助于识别风险。图片质量检测：采集过程中实时检测图片质量，仅质量合格的图片才会被采集成功并进入后续的防伪验证流程，确保有效防伪。多维度防伪检测：采集过程中通过多种交互方式及采集多帧证件图片，从多个维度综合分析，有效识别伪造证件，提升防伪能力。	采集能力因设备而异，安全性相对更低。图片质量检测：图片的采集来源由客户自己把控，ZOLOZ无法控制图片质量。证件防伪检测：仅支持对单张图片进行基础的防伪检测，检测能力极为有限。
网络环境限制	采用异步调用方式，并结合重试机制、本地缓存及状态管理等技术手段，能够在网络环境不佳的情况下提供更灵活的解决方案，便于用户在多种网络环境下更便捷地获取结果。	采用同步调用方式，需等待服务器响应后才能继续执行下一步操作。在网络环境不佳的情况下，可能会导致请求超时、调用失败或长时间无响应等，影响用户体验。
其他方面	具备算法与页面的实时交互能力，客户可根据需要选择重拍，一定程度上提升了用户体验、节约客户成本。	无