Financial Intelligence Engine:モバイル Web (H5) モード統合

モバイル Web SDK

iOS と Android の両方のブラウザで使用できるモバイル Web SDK を提供しています。

要件

• サポートされている最小 OS バージョン: Android 5 以降、iOS 11 以降

• サポートされているブラウザ:

  • iOS: Safari。Chrome/Firefox/Microsoft Edge/WKWebView は iOS 14.3 以降でサポートされています。

  • Android: 推奨: Chrome 60 以降、Firefox 68 以降。その他の Android ブラウザでは、動作はデバイスによって異なる場合があります。

• 必要な権限: ネットワークとカメラ。メディアキャプチャには HTTPS デプロイメントが必要です。

統合の概要

すべての H5 モード プロダクトには、次の 4 つの主要コンポーネントが関係します。

• 加盟店サーバー

• 加盟店の H5 ページ

• ZOLOZ SaaS サービス

• ZOLOZ モバイル Web SDK

お客様は、統合を試みる前に、インタラクションシーケンス全体を完全に理解している必要があります。

全体シーケンス

詳細な手順

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 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 の統合と同様に、ZOLOZ 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 のインスタンス化と構成H5/Web アプリケーション用 API SDK のインスタンス化と構成

// OpenApiClient を初期化します
String clientId = "<クライアント ID>";
String zolozPublicKey = "<Base64 でエンコードされた ZOLOZ の公開鍵コンテンツ>";
String merchantPrivateKey = "<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);  // 暗号化を無効にすることができます

3. H5/ Web アプリケーションのエンドポイントを公開する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;
    }
    
    

詳細については、Real Id API 仕様をご参照ください。

H5 側統合

1. ZOLOZ Web SDK を呼び出す

モバイル H5 がサーバー側から clientcfg を受信すると、モバイル H5 は次のように ZOLOZ Web SDK を呼び出すことができます。

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

// URL をリダイレクトします
window.location.href = zolozurl;

// または、フルスクリーン iframe で開きます
<iframe src="zolozurl" allow="microphone;camera;midi;encrypted-media;gyroscope;accelerometer;" allowusermedia width="100%" height="100%"></iframe>

• リダイレクトメソッドと iframe メソッドは相互排他であることに注意してください。 iframe 統合を使用する場合、ページはリダイレクトされません。ZOLOZ コールバックセクションでaddEventListenerを使用して結果を受け取ることができます。

• 横向き位置の iPad で websdk を使用する場合は、iframe を使用し、UI の互換性のために 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 については、次の表を参照してください。

• ZOLOZ サーバーは clientcfg を加盟店サーバーに返します。

• コールバック URL、顔ガイド URL、およびその他のパラメーターは加盟店初期化で構成できます。詳細については、「」をご参照ください。参照してくださいReal Id 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 が完了した場合は completeCallbackUrl、ZOLOZ Web SDK が中断された場合は interruptCallbackUrl になります。completeCallbackUrl と interruptCallbackUrl は clientcfg から解析され、加盟店初期化で構成できます。詳細については、「」をご参照ください。参照してくださいReal Id API 仕様詳細については、

• iframe モードでは、ユーザーは次のようにレスポンスを受信します。

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

3. 顔ガイド URL をカスタマイズする

デフォルトの顔ガイド URL が提供されています。UI を変更したり、言語を追加したりする場合は、顔ガイド URL をカスタマイズできます。

ZOLOZ Web SDK はフルスクリーン iframe で顔ガイド URL を開きます。

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

• iframeSrc は顔認証ガイド URL であり、clientcfg から解析されます。これは加盟店初期化で設定できます。 詳細については、Real Id API 仕様をご参照ください。

• このカスタマイズされたページは iframe でホストされているため、お客様がこのページで複雑な関数を実装しようとすると、CORS 問題または権限問題が発生する可能性が非常に高くなります。純粋な静的ページの方がはるかに推奨されます。

[次へ] をクリックしてワークフローを処理する場合は、メッセージを投稿してください。

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

例

オープンソースの例は、GitHub リポジトリで確認してください。

• H5 Real Id

• H5 ID 認識

• H5 顔のキャプチャ