ZOLOZZOLOZDOCS

H5 模式

移动 Web SDK

该 SDK 适用于 Android 和 iOS 系统中的浏览器。

使用须知

  • 操作系统版本：支持安卓 5.0及以上，iOS 11 及以上。
  • 浏览器：
    • 对于 iOS 端，支持 Safari 浏览器以及 iOS 14.3 及以后版本的 Chrome/Firefox/Microsoft Edge 浏览器。
    • 对于 Android 端，建议使用 Chrome60+ 和 Firefox58+。针对其他安卓端浏览器，不同设备情况不同。
  • 权限：需要获取网络权限和摄像头权限。

集成概览

image

所有 H5 模式产品包含 4 个关键组件：

  • 商家的服务器
  • 商家的 H5 页面
  • ZOLOZ SaaS 服务
  • ZOLOZ 移动网页 SDK

在尝试任何集成操作前，用户必须完全理解整个交互流程。

整体流程

image

详细步骤

  1. 开始事件。用户在移动 H5 开始流程（例如， eKYC 流程）。
  2. 初始化事务。移动 H5 发送初始化请求至商家服务器。
  3. 初始化事务。商家服务器调用 ZOLOZ SaaS 服务以初始化产品的事务（例如， RealId）
  4. 返回初始化结果和用户配置。ZOLOZ SaaS 服务完成事务初始化，返回初始化结果和用于调用ZOLOZ Web SDK商家服务器的用户配置。
  5. 返回初始化结果和用户配置。商家服务器返回初始化结果和用户配置到移动 H5。
  6. 使用用户配置调用 SDK。移动 H5 使用用户配置打开 ZOLOZ Web SDK URL。
  7. 获取用户数据并上传。ZOLOZ Web SDK 开始同终端交互，获取所需的用户数据然后上传。ZOLOZ Web SDK 可能会和 ZOLOZ 服务器进行多次交互。
  8. 流程结束。流程完成，ZOLOZ 服务器返回流程状态至 ZOLOZ Web SDK。
  9. 告知流程完成和流程状态。ZOLOZ Web SDK 告知移动 H5 流程完成。
  10. 告知流程完成。移动 H5 告知商家服务器流程完成。
  11. 检查事务细节。商家服务器向 ZOLOZ SaaS 服务询问事务细节。
  12. 返回事务细节。ZOLOZ 服务器向商家服务器返回细节。
  13. 确认。商家服务器确认来自移动 H5 的信息。
  14. 告知流程完成。移动H5 告知用户流程完成。

服务端接入

商家的服务器需要提供适宜的端点，用于在商家应用上创建事务以及取得事务的最终结果。您可轻松转发来自商家应用的请求至 ZOLOZ SaaS 应用程序接口。

类似于集成服务器模式产品的应用程序接口，ZOLOL API SDK 使网关协议更加易于执行。本文档仅演示如何集成 ZOLOZ API SDK。

添加 API SDK

在您项目中的 POM 文件添加以下依赖，以添加库至您的项目中。

copy
<dependency>
    <groupId>com.zoloz.api.sdk</groupId>
    <artifactId>zoloz-api-sdk</artifactId>
    <version>0.1.0</version>
</dependency>

实例化并配置 API SDK 客户端

copy
// 初始化 OpenApiClient
String clientId = "<Client ID>";
String zolozPublicKey = "<ZOLOZ's public key content encoded in base64>";
String merchantPrivateKey = "<The merchant's private key content encoded in base64>";

OpenApiClient client = new OpenApiClient();  // 用默认签名和加密构建
client.setHostUrl("https://sg-production-api.zoloz.com");
client.setClientId(clientId);
client.setMerchantPrivateKey(merchantPrivateKey);
client.setOpenApiPublicKey(zolozPublicKey);
//client.setSigned(false);     // 可关闭（应答的）签名验证
//client.setEncrypted(false);  // 可关闭加密

为客户端应用开放端点

copy
@CrossOrigin
@RestController
public class H5ClientModeController {

    private static final Logger logger = LoggerFactory.getLogger(H5ClientModeController.class);

    @Autowired
    private OpenApiClient openApiClient;

    @Autowired
    private RealIdConfig realIdConfig;

    @RequestMapping(value = "/api/realid/h5initialize", method = RequestMethod.POST)
    public JSONObject h5RealIdInit(@RequestBody JSONObject request) {

        logger.info("request=" + request);

        String metaInfo = "MOB_H5";

        String businessId = "dummy_bizid_" + System.currentTimeMillis();
        String userId = "dummy_userid_" + System.currentTimeMillis();

        JSONObject apiReq = new JSONObject();
        apiReq.put("bizId", businessId);
        apiReq.put("flowType", "H5_REALIDLITE_KYC");

        if(request.getString("docType")==null){
            apiReq.put("docType", realIdConfig.getDocType());
        }else{
            apiReq.put("docType", request.getString("docType"));
        }

        Map<String, String> h5ModeConfig = new HashMap<>();
        if (request.getJSONObject("h5ModeConfig") != null) {
            h5ModeConfig.put("completeCallbackUrl", request.getJSONObject("h5ModeConfig").getString("completeCallbackUrl"));
            h5ModeConfig.put("interruptCallbackUrl", request.getJSONObject("h5ModeConfig").getString("interruptCallbackUrl"));
        } else {
            h5ModeConfig.put("completeCallbackUrl", "https://zasia.oss-cn-beijing.aliyuncs.com/dev/web-ekyc-realid/index.html#/result");
            h5ModeConfig.put("interruptCallbackUrl", "https://zasia.oss-cn-beijing.aliyuncs.com/dev/web-ekyc-realid/index.html#/result");
        }

        Map<String, String> pageConfig = new HashMap<>();
        if (request.getJSONObject("pageConfig") != null && request.getJSONObject("pageConfig").getString("urlFaceGuide") != null) {
            pageConfig.put("urlFaceGuide", request.getJSONObject("pageConfig").getString("urlFaceGuide"));
        }

        //apiReq.put("pages", "1");
        apiReq.put("metaInfo", metaInfo);
        apiReq.put("userId", userId);
        if(StringUtils.isNotBlank(realIdConfig.getServiceLevel())){
            apiReq.put("serviceLevel",realIdConfig.getServiceLevel());
        }

        apiReq.put("h5ModeConfig",h5ModeConfig);
        apiReq.put("pageConfig",pageConfig);

        String apiRespStr = openApiClient.callOpenApi(
                "v1.zoloz.realid.initialize",
                JSON.toJSONString(apiReq)
        );
        JSONObject apiResp = JSON.parseObject(apiRespStr);
        JSONObject response = new JSONObject(apiResp);
        response.put("transactionId", apiResp.getString("transactionId"));
        response.put("clientCfg", apiResp.getString("clientCfg"));
        logger.info("response=" + apiRespStr);

        return response;
    }
    
    @RequestMapping(value = "/api/realid/checkresult", method = RequestMethod.POST)
    public JSONObject realIdCheck(@RequestBody JSONObject request) {

        logger.info("request=" + request);

        String businessId = "dummy_bizid_" + System.currentTimeMillis();
        String transactionId = request.getString("transactionId");
        String isReturnImage = request.getString("isReturnImage");

        JSONObject apiReq = new JSONObject();
        apiReq.put("bizId", businessId);
        apiReq.put("transactionId", transactionId);
        apiReq.put("isReturnImage", isReturnImage);

        String apiRespStr = openApiClient.callOpenApi(
                "v1.zoloz.realid.checkresult",
                JSON.toJSONString(apiReq)
        );

        JSONObject apiResp = JSON.parseObject(apiRespStr);

        JSONObject response = new JSONObject(apiResp);
        return response;
    }

更多详情，请参见RealId API 规格说明书。

H5 端接入

调用 ZOLOZ Web SDK

移动 H5 从服务端获取到 clientcfg后，可以调用ZOLOZ Web SDK，如下所示：

copy
var baseurl = "https://*****.html";
var zolozurl = baseurl + "?clientcfg=encodeURIComponent(clientcfg)";

// 重定向此 url 
window.location.href = zolozurl;

// 或者以全屏iframe模式打开url
<iframe src="zolozurl" allow="microphone;camera;midi;encrypted-media;" allowusermedia width="100%" height="100%"></iframe>
  • baseurl 即为 ZOLOZ Web SDK URL. 对于不同环境和不同 ZOLOZ 产品，WEB SDK URL 不同。请参见下表所示不同情况下对应的正确 WEB SDK URL。
  • ZOLOZ 服务器会返回 clientcfg 至商家服务器。
  • 回调 URL，人脸识别指引 URL 和其他参数可在商家应用初始化过程中配置。更多信息，请参见 RealId API 规格说明书。

ZOLOZ 回调

当 ZOLOZ Web SDK 完成调用后，callbackurl 或 postMessage 会给予应答，如下所示：

copy
var callbackurl = "https://*****.html";
var response = {
  state:'*****',        // 解析自 clientcfg 的业务状态
  code:1000,                // 1000 – 完成, 1003 – 中断
  subCode:'Z****',  // Z 码
  extInfo:{}                // 扩展参数
};

//如果用户通过重定向方式打开此 Web SDK，回调此 URL
window.location.replace = callbackurl+'?response=encodeURICompnent(JSON.stringfy(response))';

// 如果用户在 iframe模式下打开此 Web SDK，使用postmessage 方法
window.parent.postMessage(response, '*');
  • 如果 ZOLOZ Web SDK 是完成状态，callbackurl 将为 completeCallbackUrl；如果 ZOLOZ Web SDK 是中断状态，callbackurl 将为 interruptCallbackUrl。completeCallbackUrl 和 interruptCallbackUrl 解析自 clientcfg，可在商家应用初始化过程中配置。更多信息，请参见 RealId API 规格说明书。
  • 在 iframe 模式下，用户可收到如下所示的应答：
copy
window.addEventListener('message', (event) => {
      const response = event.data;
      console.log('response:', response);
    });

定制人脸识别指引 URL

ZOLOZ SaaS 服务提供默认的人脸识别指引 URL。如果要更改 UI 或添加更多语言，您可定制人脸识别指引 URL。

ZOLOZ Web SDK会以全屏 iframe 模式打开人脸识别指引 URL:

copy
<iframe src="iframeSrc" width='100%' height='100%'/>
  • iframeSrc 将为面部识别指引URL，解析自 clientcfg，可在商家应用初始化过程中配置。更多信息，请参见 RealId API 规格说明书。

点击 next 以处理工作流时，请留信息如下:

copy
window.parent.postMessage('next','*');

代码示例

在我们的 Github 代码库中获取开源的代码示例: