Deploy FACE_GUARD_PRO Web SDK for Mobile & PC - ID Verification

This topic describes the integration process for the FACE_GUARD_PRO Web SDK (Mobile / PC).

Usage notes

Important

Applications that integrate FACE_GUARD_PRO 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 JavaScript (JS) SDK into the pages that you want to protect. Note: You must import the SDK only once per webpage, including for single-page applications (SPAs).

Compatibility:

PC: Chrome 60+, Firefox 60+, Edge 20+, Safari 11+, 360 Browser 10+, QQ Browser 4+, Internet Explorer 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 prevent issues that are caused by an outdated file, do not download the JS file to your local server.

<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 on page load to obtain the SDK object. The SDK only needs to be initialized once.

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

Parameter description

appKey: Identifies the user. This is the AppKey assigned by Alibaba Cloud. Contact your business manager to obtain it.
Important
Applications that integrate FACE_GUARD_PRO 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: User-defined.

endpoints: https://cloudauth-device.ap-southeast-1.aliyuncs.com

Note

The ID Verification client has a built-in Device Guard security module. To meet data collection compliance requirements in different regions, it provides different data reporting sites. You can set CustomUrl and CustomHost to specify a reporting site based on user attributes.
Note: You can specify only one reporting site within a single application session lifecycle. The server query region must match the reporting site.
Specify a reporting site:
- Singapore site (default): https://cloudauth-device.ap-southeast-1.aliyuncs.com
- Indonesia site: https://cloudauth-device.ap-southeast-5.aliyuncs.com
- US West (Silicon Valley): https://cloudauth-device.us-west-1.aliyuncs.com
- Germany (Frankfurt): https://cloudauth-device.eu-central-1.aliyuncs.com
- China (Hong Kong): https://cloudauth-device.cn-hongkong.aliyuncs.com
For more information about the regions supported by product servers, see Supported regions.

Field name	Description	Example
IPv6	Specifies whether to use an IPv6 domain name to report device information: 0 (default): No (use an IPv4 domain name) 1: Yes (use an IPv6 domain name)	"1"
DataSwitch	The timing for reporting device information. 0 (default): At initialization 1: When getting the token Note We recommend using the default configurations.	"1"
CustomUrl	Sets the data reporting server domain name.	"https://cloudauth-device.ap-southeast-1.aliyuncs.com"
CustomHost	Sets the data reporting server host.	"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 that an interval of at least 2 seconds exists between the init and getToken calls.
When you call the getToken method, pass the bizId parameter. This binds the token to a unique business authentication ID. Later, when you query the results on the server, you must also pass this ID to verify that the token has not been tampered with.

Choose one of the following three methods to call the function.

// 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 obtaining camera permissions.
// Pass the unique ID for this authentication and the mediaStream object. The mediaStream object is 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: The business ID. This ID is used to associate the business ID with the token. This parameter is optional.
- bizStr: The CameraInfo, which is used to extract camera features. You can obtain it using the getCameraInfo method.
Return value
deviceToken: The token string. Use this token to call the FaceGuardRisk API operation of FACE_GUARD_PRO.

Important

The token string is about 600 bytes long.

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

Send a request to the server with the token

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]',
        appName: '[Enter the name of your web application. This is user-defined.]',
        endpoints : ['https://cloudauth-device.ap-southeast-1.aliyuncs.com']
    }
  }
});


// Handle business functions, for example, when authentication is complete
function getToken(){
    var bizId = 'xxxxxxxx';
    // Get the deviceToken of the device fingerprint. The interval between getToken and init should be at least 2s.
    // Pass the unique ID for this authentication to bind the generated token to the bizId.
    var deviceToken = window.z_um.getToken(bizId);
    // Pass the deviceToken to the customer's service backend
    var data = {
           "deviceToken": deviceToken,
           "Other business parameters": ""
     };
    // Send a backend request... The backend queries threat information using the deviceToken
}

</script>
</body>