Frontend Integration

Overview

In order for users to go through the Document Verification process , H5 Document Verification UI needs to be embedded into your frontend.

1. Choose embedding method

There are 2 methods available.

Embed Method	Advantages
Load H5 IDV URL in iframe	The user does not have to leave the current page.
Open H5 IDV URL directly	- Support navigation - Resource isolation from your page

2. Give Camera Permission

iframe

To allow iframe to visit camera, you need to add allow attribute with "autoplay; camera;" value. Following is an example:

HTML

<iframe src="h5-idv-url-here" allow="autoplay; camera;"></iframe>

Please note that:

1. The integration only works with HTTPs. To ensure the best security was held, please make sure only trusted websites were allowed here.
2. The srcattribute should be URL encoded. In Javascript, you can use encodeURIComponent method to achieve that. Following is an example:

HTML

const url = "h5-idv-url-here";
const encodedUrl = encodeURIComponent(url);
<iframe src=encodedUrl allow="autoplay; camera;"></iframe>

Android Webview

To allow Android Webview to visit camera, you need to override the onPermissionRequest method in your app:

Java

private var mWebChromeClient: WebChromeClient = object : WebChromeClient() {

    override fun onPermissionRequest(request: PermissionRequest?) {

        //  IMPORTANT: Check host and adapt filter to allow camera access
        // e.g. if (request?.origin?.host == "xxx") {...}

        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
            if (context is BaseActivity) {
                if (ContextCompat.checkSelfPermission(
                        context,
                        Manifest.permission.CAMERA
                    ) == PackageManager.PERMISSION_GRANTED
                ) {
                    request?.grant(request.resources)
                } else {
                    context.requestPermission(Manifest.permission.CAMERA) { granted ->
                        if (granted) {
                            request?.grant(request.resources)
                        } else {
                            request?.deny()
                        }
                    }
                }
            }
        }
    }
}   

iOS Webview

To enable iOS Webview camera permission, you need the following adjustment:

1. Inside info.plist file, set NSCameraUsageDescription to allow the app to access camera.

XML

<key>NSCameraUsageDescription</key> 
<string>$(PRODUCT_NAME) need to use your rear camera</string>  

2. Config Webview instance to allow inline media playback, disable user action for playback, enable JavaScript, and enable JavaScript to automatically open windows.

Objective-C

let configuration = WKWebViewConfiguration()
configuration.allowsInlineMediaPlayback = true
configuration.mediaTypesRequiringUserActionForPlayback = []
configuration.preferences.javaScriptEnabled = true
configuration.preferences.javaScriptCanOpenWindowsAutomatically = true
self.webView = WKWebView(frame: self.view.bounds, configuration: configuration)

3. Before entering H5 Document Verfication, check and request for camera access first.

Swift

// 请求相机权限(swift 样例代码)
// Request camera permission (in Swift)
func checkAVAuthorizationStatus(with block: @escaping((_ authed: Bool) -> Void)) {
    let authStatus = AVCaptureDevice.authorizationStatus(for: .video)
    if authStatus == .authorized {
        block(true)
    } else if authStatus == .denied || authStatus == .restricted {
        block(false)
    } else {
        AVCaptureDevice.requestAccess(for: .video) { (result) in
            DispatchQueue.main.async {
                block(result)
            }
        }
    }
}

// Usage
// Check auth status before entering H5 idv webpage.
self.checkAVAuthorizationStatus { authed in
  if authed {
    // Enter H5 webpage directly
  } else {
    // Logic to handle camera unauthorised.
  }
}

4. (Optional) To avoid camera permission prompt in H5 every time.

Swift

// Make sure your ViewController inherits WKUIDelegate.
class ViewController: UIViewController, WKUIDelegate {
    ...

    // Only verified for iOS 15+
    @available(iOS 15.0, *)
    func webView(_ webView: WKWebView, requestMediaCapturePermissionFor origin: WKSecurityOrigin, initiatedByFrame frame: WKFrameInfo, type: WKMediaCaptureType, decisionHandler: @escaping (WKPermissionDecision) -> Void) {
        // NOTE: please add necessary security check like domain filter if needed.
        decisionHandler(.grant)
    }
}

self.webView.uiDelegate = self

---

Error handling

When the image upload fails, Frontend will jump to failReturnUrl with code=FAIL&errorCode=XXX
errorCode is an enumer:

errorCode	Description
NO_PERMISSION	the user didn't give camera permissions.
CAMERA_ISSUE	our Frontend failed to start camera.
PARAMETER_ERROR	Server report frontend parameter exist mistake
TIMEOUT	1 minute has passed since the upload, and there has been no response from the server
TRY_COUNT_EXCEED	The user attempted to submit more than three times, exceeding the maximum retry limit allowed by the backend.
SERVICE_BUSY	When the QPS (Queries Per Second) limit is exceeded, a response will be returned.
IAM_FAILED	The token used for authentication has expired (valid for one hour).
SIGNATUREID_NOT_EXIST	The SIGNATUREID does not exist (this should not occur with a correctly generated link).

Compatible Matrices

Supported browsers

Minimal browser versions with support for all features required by H5 Document Verification.

Chrome	Safari	Edge	Firefox	Opera	iOS Safari	Android Browser	Chrome for Android	Firefox for Android	Internet Explorer
96	15	93	79	82	15	81	96	79	Not supported

Sources: caniuse and WebAssembly Roadmap