Mobile web (H5)-mode integration
The Mobile Web SDK
We provide a mobile Web SDK, which be used in both iOS and Android browsers.
- Minimum OS version supported: Android 5+, iOS 11+
- Browsers supported:
- iOS: Safari. Chrome/Firefox/Microsoft Edge/WKWebView are supported since iOS 14.3.
- Android: Recommended: Chrome60+, Firefox68+. For other Android browsers, the behavior can vary depending on different devices.
- Permissions required: Network and camera; HTTPS deployment is required for media capture.
All h5-mode products involve 4 key components:
- The merchant's server
- The merchant's h5 page
- ZOLOZ SaaS service
- ZOLOZ mobile Web SDK
The customer must fully understand the whole interaction sequence before any integration attempts.
- Start business. A user starts the process (e.g. eKYC process) in mobile h5.
- Initialize transaction. The mobile H5 sends initialization request to the merchant server.
- Initialize transaction. The merchant server calls ZOLOZ SaaS service to initialize the transaction of the product (such as RealId).
- Return initialize result and client config. ZOLOZ SaaS service completes transaction initialization and returns result as well as corresponding client configuration prepared for ZOLOZ Web SDK to the merchant server.
- Return initialize result and client config. The merchant server returns the initialization result and client configuration to mobile h5.
- Invoke with client config. The mobile h5 open ZOLOZ Web SDK url with client configuration.
- Capture user data and upload. ZOLOZ Web SDK starts to interact with the end-user, capture required data and then upload. There might be multiple rounds of interaction between ZOLOZ Web SDK and ZOLOZ server.
- Process complete. The process is completed and ZOLOZ server returns the process status to ZOLOZ Web SDK.
- Inform completion with status. ZOLOZ Web SDK informs the completion of the process to the mobile h5.
- Inform completion. The mobile h5 informs the merchant server about the process completion.
- Check transaction details. The merchant server asks ZOLOZ SaaS service for transaction details.
- Return transaction details. ZOLOZ server returns details to the merchant server.
- Confirmed. The information from the mobile h5 is confirmed by the merchant server.
- Inform completion. The mobile h5 tells user that the process is completed.
The merchant's server need to provide proper endpoint for the merchant application to create a transaction, as well as fetch the final result of transaction. The request from the merchant application could be simply forwarded to ZOLOZ SaaS APIs.
Similar with integrating APIs of server-mode products, ZOLOL API SDK helps a lot by easing the gateway protocol implementation. In this document we only demonstrate how to integrate with the ZOLOZ API SDK.
1. Introduce API SDK
Introduce the library into your project by adding following dependency in the POM file of your project.
2. Instantiate and Configure API SDK Client
3. Expose Endpoint for Client Application
Refer to RealId API specification for more information.
1. Invoke ZOLOZ Web SDK
When mobile h5 receives the clientcfg from server side, mobile h5 can invoke the ZOLOZ Web SDK as followed:
- Please note that redirect method and iframe method are mutually exclusive. The page will not redirect if you use the iframe integration, you can receive the result by
addEventListenerin ZOLOZ callback section.
- baseurl is the ZOLOZ Web SDK url. It depends on environment and ZOLOZ product. Please refer to the following table for the correct WEB SDK URLs:
WEB SDK URL
Hong Kong Production/Sandbox
- ZOLOZ server will return clientcfg to merchant server;
- Callback url, face guide url and other parameters could be configured in merchant init, please refer to RealId API specification for more information.
2. ZOLOZ Callback
When ZOLOZ Web SDK finished, a response will be given by callbackurl or postMessage as followed:
- callbackurl will be completeCallbackUrl if ZOLOZ Web SDK is completed, it will be interruptCallbackUrl if ZOLOZ Web SDK is interrupted. completeCallbackUrl and interruptCallbackUrl are parsed from clientcfg and they could be configed in merchant init, please refer to RealId API specification for more information.
- In iframe mode, user receives the response as followed:
3. Customize face guide url
A default face guide url is provided. If you would like to change the UI or add more languages, the face guide url can be customized.
ZOLOZ Web SDK will open the face guide url in fullscreen iframe:
- iframeSrc will be the face guide url, which is parsed from clientcfg and it could be configed in merchant init. Please refer to RealId API specification for more information.
- Since this customized page is hosted in iframe, it is very likely to encounter CORS issue or privilege issue if the customer tries to implement some complex function in this page. A pure STATIC page is much more recommended.
Please post a message when click next to process the workflow:
Check open-sourced examples in our Github repository: