支援的產品

H5接入模式支援以下產品：

• RealID

• Connect

• Face Capture

• ID Recognition

整合架構

所有通過H5模式接入的產品都包含四個關鍵組件：

• 商戶服務端

• 商戶H5頁面

• ZOLOZ SaaS服務

• ZOLOZ移動Web SDK

互動流程

下圖介紹了通過H5啟動ZOLOZ服務的完整互動流程。

1. 使用者通過移動H5發起商務程序，例如eKYC流程。

2. 移動H5向商戶服務端發送初始化請求。

3. 商戶服務端調用ZOLOZ SaaS服務初始化產品的事務，例如RealID。

4. ZOLOZ SaaS服務完成事務初始化，並將初始化結果和用於調用ZOLOZ Web SDK商戶服務端的用戶端配置返回給商戶服務端。

5. 商戶服務端將初始化結果和用戶端配置返回給移動H5。

6. 移動H5使用用戶端配置開啟ZOLOZ Web SDK URL。

7. 採集使用者資料並上傳。

   ZOLOZ Web SDK與終端使用者互動，採集所需的使用者資料並上傳到ZOLOZ伺服器。期間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 API。

與整合服務器模式產品的API類似，ZOLOL API SDK使網關協議更加易於執行。本文僅示範如何整合ZOLOZ API SDK。

操作步驟

1.引入API SDK

在專案的POM檔案中添加以下依賴項，將庫引入專案中。

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

2.對H5或Web應用進行執行個體化並配置API SDK

// 初始化 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);  // 可關閉加密

您需要將代碼中的以下欄位替換成您的真實資訊。如需擷取clientId、zolozPublicKey、merchantPrivateKey，請參見擷取API憑證。

• clientId：客戶ID。

• zolozPublicKey：ZOLOZ交易公開金鑰，採用Base64編碼格式。

• merchantPrivateKey：商戶交易私密金鑰，採用Base64編碼格式。

• setHostUrl：ZOLOZ網關URL，如需擷取ZOLOZ網關URL，請參見選擇網站和環境。

3.為H5或Web應用開放端點

@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。

相關API

單擊下方連結，可查看ZOLOZ相關產品的服務端API。

• RealID

• ID Recognition

• Face Capture

H5端接入流程

前提條件

ZOLOZ提供了移動Web SDK，該SDK可用於Android和iOS系統的瀏覽器，但必須滿足以下要求：

• 作業系統版本：必須為Android 5.0及以上版本，iOS 11及以上版本。

• 支援的瀏覽器：

  • iOS用戶端支援Safari瀏覽器和iOS 14.3及以上版本的Chrome、Firefox、Microsoft Edge、WKWebView瀏覽器。

  • Android用戶端建議使用Chrome60+、Firefox68+瀏覽器，針對其他Android端瀏覽器，不同裝置支援的情況不同。

• 許可權配置：需要擷取網路許可權和網路攝影機許可權。

操作步驟

1.調用ZOLOZ Web SDK

移動H5從服務端擷取到用戶端配置後，即可調用ZOLOZ Web SDK。代碼如下：

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;gyroscope;accelerometer;" allowusermedia width="100%" height="100%"></iframe>

說明：

• 重新導向方法和iframe方法互斥。如果您使用的是iframe方法整合，頁面將不會重新導向，您可以在ZOLOZ回調時通過addEventListener接收結果。

• 支援平板電腦調用ZOLOZ Web SDK，橫屏使用平板時需通過iframe將寬度設定為500px，以確保使用者介面的相容性。代碼如下：

<iframe src="zolozurl" width="500" allow="microphone;camera;midi;encrypted-media;gyroscope;accelerometer;" allowusermedia height="100%"></iframe>

• baseurl指ZOLOZ Web SDK URL，不同環境不同ZOLOZ產品對應的Web SDK URL不同，具體見下表。

• clientcfg指用戶端配置，ZOLOZ伺服器會將用戶端配置返回給商戶服務端。

• 回調URL、人臉自拍引導頁和其他參數可以在商戶應用初始化過程中配置。更多資訊，請參見RealID API。

2.ZOLOZ回調

當ZOLOZ Web SDK完成調用後，callbackurl或postMessage會給予響應，代碼如下所示。

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, '*');

• 如果使用的是重新導向方法，callbackurl會給出以下響應。

  • 如果ZOLOZ Web SDK是完成狀態，callbackurl將為completeCallbackUrl。

  • 如果ZOLOZ Web SDK是中斷狀態，callbackurl將為interruptCallbackUrl。

    說明：completeCallbackUrl和interruptCallbackUrl解析自clientcfg，您可以在商戶應用初始化過程中配置。更多資訊，請參見RealID API。

• 如果使用的是iframe方法，使用者會收到如下所示的響應。

window.addEventListener('message', (event) => {
      const response = event.data;
      console.log('response:', response);
    });

3.定製人臉自拍引導頁

ZOLOZ SaaS服務提供預設的人臉自拍引導頁，如果您想修改UI或添加更多語言，可以自訂人臉自拍引導頁。

ZOLOZ Web SDK會以全屏iframe模式開啟人臉自拍引導頁：

<iframe src="iframeSrc" width='100%' height='100%'/>

• iframeSrc是人臉自拍引導頁，解析自clientcfg，您可以在商戶應用初始化過程中配置。更多資訊，請參見RealID API。

• 由於該自訂頁面託管在iframe中，如果希望在頁面中實現複雜的功能，可能會遇到跨域、許可權等問題，建議您使用純靜態頁面。

在人臉自拍引導頁，單擊next處理工作流程時，請通過以下代碼留訊息：

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

程式碼範例

您可以在Github中擷取開源的程式碼範例：

• H5 RealId

• H5 IdRecognize

• H5 FaceCapture