FACE_GUARD H5 web page integration, DEVICE_GUARD H5 web page integration - ID Verification

This topic describes the integration flow for FACE_GUARD.

Usage notes

Important

Applications that integrate FACE_GUARD require a mature facial recognition algorithm and a system for managing threat policies. We recommend that you first consult with your business manager to assess whether this is suitable for your business scenario.

Import the JS SDK into the pages that you want to protect. Note: Import the SDK only once per web page, including for single-page applications.

Compatibility:

PC: Chrome 60+, Firefox 60+, Edge 20+, Safari 11+, 360 Browser 10+, QQ Browser 4+, IE 9+, and more.
Mobile: Chrome 60+, UC Browser 12+, Safari 11+, Quark Browser, default browsers from major phone manufacturers, native WebView (Android 4+), and more.

Integration steps

Import the JS SDK

Important

The web SDK is a JS file that is updated regularly. To avoid issues caused using an outdated file, do not download the JS file to a local server for import.

<script src="https://o.alicdn.com/captcha-frontend/aliyunFP/fp.min.js"></script>

Initialize the SDK (init)

After you import the JS SDK, initialize it immediately when the page loads to obtain the SDK object. You only need to initialize the SDK once.

ALIYUN_FP.use('um', (state, um) => {
  if (state === 'loaded') {
    um.init({
        appKey: '[Enter the AppKey assigned by Alibaba Cloud here]',
        appName: '[Enter your custom web application name here]',
        endpoints : ['https://cloudauth-device.ap-southeast-1.aliyuncs.com']
    })
  }
});

Parameter description

appKey: The AppKey assigned by Alibaba Cloud to identify the user. Contact your business manager to obtain the AppKey.
Important
Applications that integrate FACE_GUARD require a mature facial recognition algorithm and a system for managing threat policies. We recommend that you first consult with your business manager to assess whether this is suitable for your business scenario.
appName: A custom name for your application.
endpoints: https://cloudauth-device.ap-southeast-1.aliyuncs.com

Get the client token (getToken)

After facial recognition is complete, call getToken to obtain the device fingerprint, deviceToken. For more information, see Integration flow. Call getToken at [Timing 1].

Important

Data reporting can have latency. Ensure an interval of at least 2 seconds between the init and getToken calls.
When you call the getToken method, pass the bizId parameter. This binds the token to your unique business authentication ID. Later, when you query the results on the server, you must also pass the ID to verify that the token has not been tampered with.

Use one of the following three methods.

// 1. Call the getToken operation directly.
window.z_um.getToken();

// 2. Pass the unique ID for this authentication.
let bizId = '<Your bizId>';
let deviceToken = window.z_um.getToken(bizId);

// 3. Recommended method: Pass the video stream.
// For this method, call getToken after you obtain camera permissions.
// Pass the unique ID for this authentication and the mediaStream. The mediaStream is a video stream object used to get camera features. You can use the return value of the navigator.mediaDevices.getUserMedia method.
let bizStr = await window.z_um.getCameraInfo(mediaStream);
window.z_um.getToken(bizId, bizStr);

Parameters
- bizId: Your business ID. This parameter is used to associate the business ID with the token. This parameter is optional.
- bizStr: CameraInfo. Obtain this by calling the getCameraInfo method. It is used to extract camera features.
Return value
deviceToken: The returned token string. You can use this token to call the FaceGuardRisk API operation of FACE_GUARD.

Important

The token string is about 600 bytes long.

If you receive many long tokens, first, ensure that the client has a stable network connection. Second, ensure that the interval between the init and getToken calls is at least 2 seconds.

Send the token in a request to the server

After you obtain the deviceToken (FaceSecToken.token), include this parameter in the request to your business server. The server then queries and verifies the result. For more information, see Server-side API operations.

Complete code example

<body>
<button type="button" id='register' onclick="getToken();">Get Token</button>
<script type="text/javascript" src="https://o.alicdn.com/captcha-frontend/aliyunFP/fp.min.js"></script>
<script>
ALIYUN_FP.use('um', (state, um) => {
  if (state === 'loaded') {
    um.init({
        appKey: '[Enter the AppKey assigned by Alibaba Cloud here]',
        appName: '[Enter your custom web application name here]',
        endpoints : ['https://cloudauth-device.ap-southeast-1.aliyuncs.com']
    }
  }
});


// Process the business function, for example, when authentication is complete.
function getToken(){
    var bizId = 'xxxxxxxx';
    // Get the device fingerprint deviceToken. The interval between getToken and init should be at least 2s.
    // Pass the unique ID for this authentication. The generated token can be bound to bizId.
    var deviceToken = window.z_um.getToken(bizId);
    // Pass the deviceToken to your service backend.
    var data = {
           "deviceToken": deviceToken,
           "Other business parameters": ""
     };
    // Send a backend request. The backend uses the deviceToken to query risk information.
}

</script>
</body>