eKYC_Redirect page integration - ID Verification - Alibaba Cloud Documentation Center

ID Verification provides a web SDK to implement the eKYC remote identity verification feature in a browser or an embedded WebView. This topic describes how to integrate with ID Verification using an H5 page on a PC or mobile device.

Prerequisites

Operating system: Android 5 or later and iOS 11 or later.
Browser:
- iOS: Safari is recommended. iOS 14.3 and later support Google Chrome, Mozilla Firefox, Microsoft Edge, and Apple WKWebView.
- Android: Chrome 60 or later and Firefox 58 or later are recommended. The supported browsers vary based on the device.
Permission: The network and camera permissions are granted. Media collection requires HTTPS transmission.
Portrait mode: Landscape mode may cause page interaction issues. We recommend that you follow the page prompts to adjust to portrait mode for verification.

Important

During the integration process, do not perform operations on the TransactionUrl parameter, such as modifying the parameter value. If you perform any operations on TransactionUrl during the integration process, a verification exception occurs.
The URL specified by the TransactionUrl parameter can be used only once. This helps ensure secure and effective verification. Repeated access to the URL may cause verification exceptions.
Due to browser compatibility fragmentation issues, we recommend that you guide users to use the recommended browsers for verification in your process design.
- If you integrate this solution within a mobile application, compatibility issues may occur due to embedded browsers. You can refer to H5 mobile SDK compatibility configuration for in-app integration to reduce compatibility issues or integrate the Native SDK.
- If you integrate through WeChat Official Account or Mini Program, compatibility issues may occur due to WeChat operational review rules. We recommend that you use the pure server-side (API) connection method.

Start eKYC

Add the following JavaScript file to your code and call the getMetaInfo() function to obtain the value of the MetaInfo parameter:

<script type="text/javascript" src="https://hkwebcdn.yuncloudauth.com/cdn/jsvm_all.js" ></script>

Note

When you call the verification operation of ID Verification - KYC, you must pass the return value to the MetaInfo parameter.

Call the Initialize operation of ID Verification - KYC to obtain the value of the TransactionUrl parameter. Then, access the URL specified by the parameter from your browser.

Sample code

<!DOCTYPE HTML>
<html lang="en">
  <head>
    <title>Title</title>
        <!--   Add the JavaScript file and globally inject the getMetaInfo function.   -->
        <!--   Introduce this JS, inject the getMetaInfo method globally   -->
    <script type="text/javascript" src="https://hkwebcdn.yuncloudauth.com/cdn/jsvm_all.js" ></script>
  </head>
  <body>
  <div></div>
    <script>
      // Pass meta information when you call the Initialize operation.
      var MetaInfo = window.getMetaInfo();

      // Call the Initialize operation to obtain the TransactionUrl parameter.
      var TransactionUrl = ''; // The value is returned by the Initialize operation.

      // Access the URL that is specified by the TransactionUrl parameter to start verification.
      window.location.href = TransactionUrl;
    </script>
  </body>
</html>

Client-side custom configurations

The ID Verification Web SDK supports client-side custom features by passing parameters in the TransactionUrl.

You can append parameters to the TransactionUrl using the & character to apply the configurations. For example:

TransactionUrl:

https://xxxx.com?clientcfg=xxx&callbackurl=xxx&paramSign=xxx&guideFlow=ekyc

Append initTimeout:

https://xxxx.com?clientcfg=xxx&callbackurl=xxx&paramSign=xxx&guideFlow=ekyc&initTimeout=30

The supported features are listed in the following table:

Parameter	Type	Required	Description	Example
initTimeout	String	No	The timeout period for client-side verification initialization, in seconds. This is the time from when the page starts loading to when the face or OCR page appears.	30
clientLivenessTimeout	String	No	The timeout period for a single face liveness detection, in seconds.	30
clientLivenessRetryCount	String	No	The number of retry attempts for face liveness detection.	5
ocrTimeout	String	No	The timeout period for a single OCR detection, in seconds.	20
ocrRetryCount	String	No	The number of retry attempts for OCR.	10
region	String	No	The region where the mobile client sends API requests to Alibaba Cloud. The following code shows the mapping between region values and regions: `{ "HK": "Hong Kong", "US": "Virginia", "US-CA": "Silicon Valley", "SG": "Singapore", "MY": "Malaysia", "ID": "Indonesia", "PH": "Philippines", "DE": "Germany", "SA": "Saudi Arabia" }` Note Pass this parameter to specify the service region for calling Alibaba Cloud APIs. If you do not specify this parameter, the nearest region is accessed by default.	HK

Response parsing

If you specify a custom value for the ReturnUrl parameter when you call the Initialize operation, the verification result is appended to the ReturnUrl parameter as the response parameter and returned after the verification process is complete. The value of the response parameter varies based on the incoming routing mode.

Routing mode	ReturnUrl (specified value)	ReturnUrl (returned value after verification)
Common web page	https://aliyundoc.com	https://aliyundoc.com/? response=%7B%22resultCode%22%3A%22%22%2C%22resultMessage%22%3A%22%22%2C%22ocrResult%22%3A%7B%22code%22%3A%22%22%2C%22reason%22%3A%22%22%2C%22extInfo%22%3A%7B%22certifyId%22%3A%22%22%7D%7D%2C%22faceResult%22%3A%7B%22code%22%3A%22%22%2C%22subCode%22%3A%22%22%2C%22reason%22%3A%22%22%2C%22extInfo%22%3A%7B%22certifyId%22%3A%22%22%7D%7D%7D
Common web page	https://aliyundoc.com/index.html	https://aliyundoc.com/index.html?response=%7B%22resultCode%22%3A%22%22%2C%22resultMessage%22%3A%22%22%2C%22ocrResult%22%3A%7B%22code%22%3A%22%22%2C%22reason%22%3A%22%22%2C%22extInfo%22%3A%7B%22certifyId%22%3A%22%22%7D%7D%2C%22faceResult%22%3A%7B%22code%22%3A%22%22%2C%22subCode%22%3A%22%22%2C%22reason%22%3A%22%22%2C%22extInfo%22%3A%7B%22certifyId%22%3A%22%22%7D%7D%7D
History routing without a page anchor (#)	https://aliyundoc.com/xxx/	https://aliyundoc.com/xxx?response=%7B%22resultCode%22%3A%22%22%2C%22resultMessage%22%3A%22%22%2C%22ocrResult%22%3A%7B%22code%22%3A%22%22%2C%22reason%22%3A%22%22%2C%22extInfo%22%3A%7B%22certifyId%22%3A%22%22%7D%7D%2C%22faceResult%22%3A%7B%22code%22%3A%22%22%2C%22subCode%22%3A%22%22%2C%22reason%22%3A%22%22%2C%22extInfo%22%3A%7B%22certifyId%22%3A%22%22%7D%7D%7D
History routing with a page anchor (#)	https://aliyundoc.com/xxx/#xxx	https://aliyundoc.com/xxx?response=%257B%2522resultCode%2522%253A%2522%2522%252C%2522resultMessage%2522%253A%2522%2522%252C%2522ocrResult%2522%253A%257B%2522code%2522%253A%2522%2522%252C%2522reason%2522%253A%2522%2522%252C%2522extInfo%2522%253A%257B%2522certifyId%2522%253A%2522%2522%257D%257D%252C%2522faceResult%2522%253A%257B%2522code%2522%253A%2522%2522%252C%2522subCode%2522%253A%2522%2522%252C%2522reason%2522%253A%2522%2522%252C%2522extInfo%2522%253A%257B%2522certifyId%2522%253A%2522%2522%257D%257D%257D#xxx
Hash routing	https://aliyundoc.com/#/aaa/bbb	https://aliyundoc.com/?response=%257B%2522resultCode%2522%253A%2522%2522%252C%2522resultMessage%2522%253A%2522%2522%252C%2522ocrResult%2522%253A%257B%2522code%2522%253A%2522%2522%252C%2522reason%2522%253A%2522%2522%252C%2522extInfo%2522%253A%257B%2522certifyId%2522%253A%2522%2522%257D%257D%252C%2522faceResult%2522%253A%257B%2522code%2522%253A%2522%2522%252C%2522subCode%2522%253A%2522%2522%252C%2522reason%2522%253A%2522%2522%252C%2522extInfo%2522%253A%257B%2522certifyId%2522%253A%2522%2522%257D%257D%257D/#/aaa/bbb

Sample code for parsing a response

Common web page

<!DOCTYPE HTML>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <title>Title</title>
    </head>
    <body>
        <script>
            // Configure window.location.href.
            // window.location.href = https://aliyundoc.com
            // Or
            // window.location.href = https://aliyundoc.com/index.html

            // Initialize the URL object.
            var url = new URL(window.location.href);
            // Parse the response.
            var response = JSON.parse(url.searchParams.get('response'));
            // response = {
            //     resultCode: '',
            //     extInfo: {certifyId: ''}
            // }
        </script>
    </body>
</html>

History routing without a page anchor (#)

<!DOCTYPE HTML>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <title>Title</title>
    </head>
    <body>
        <script>
            // Configure window.location.href.
            // window.location.href = https://aliyundoc.com/xxx

            // Initialize the URL object. 
            var url = new URL(window.location.href);
            // Parse the response.
            var response = JSON.parse(url.searchParams.get('response'));
            // response = {
            //     resultCode: '',
            //     extInfo: {certifyId: ''}
            // }
        </script>
    </body>
</html>

History routing with a page anchor (#)

<!DOCTYPE HTML>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <title>Title</title>
    </head>
    <body>
        <script>
            // Configure window.location.href.
            // window.location.href = https://aliyundoc.com/xxx/#xxx

            // Initialize the URL object.
            var url = new URL(window.location.href);
            // Parse the response.
            var response = JSON.parse(
                decodeURIComponent(url.searchParams.get('response'))
            );
            // response = {
            //     resultCode: '',
            //     extInfo: {certifyId: ''}
            // }
        </script>
    </body>
</html>

Hash routing

<!DOCTYPE HTML>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <title>Title</title>
    </head>
    <body>
        <script>
            // Configure window.location.href.
            // window.location.href = https://aliyundoc.com/#/aaa/bbb

            // Initialize the URL object.
            var url = new URL(window.location.href);
            // Parse the response.
            var response = JSON.parse(
                decodeURIComponent(url.searchParams.get('response'))
            );
            // response = {
            //     resultCode: '',
            //     extInfo: {certifyId: ''}
            // }
        </script>
    </body>
</html>

Client-side result codes

Result code	Billed	Description
1000	Yes	The customer completed the face verification process and passed the verification. The result is for reference only. You can obtain the final verification result and perform the next operation by calling the CheckResult operation.
1001	Yes	The customer completed the face verification process but failed to pass the verification. The result is for reference only. You can obtain the final verification result and perform the next operation by calling the CheckResult operation.
1002	No	A system error occurred.
1003	No	The SDK failed to be initialized. Check whether the client time is valid.
1004	No	A camera error occurred. To fix the error, perform the following operations: Check whether your app has camera permissions before verification. If your app has camera permissions but the no-permission error persists, clear the cache of the app and try again.
1005	No	A network error occurred.
1006	No	The customer unexpectedly exited.
1007	No	The transaction ID is invalid.
1009	No	The timestamp of the client is invalid.
1011	No	The specified document type does not match the type of the submitted document.
1012	No	The critical information is missing after the document verification or the format verification failed.
1013	No	The image quality does not meet the requirements.
1014	No	The number of errors exceeds the upper limit.