REST Unified User Interface

https://www.bioid.com/bws/uui?access_token={token}&return_url={url}}[&state={state}]

The BWS unified user interface is an implementation based on the BWS Web API and provides a user interface where the developers can redirect their users to perform various biometric tasks like verification or enrollment.

It is currently implemented on our company web server bioid.com , but more implementations may be available soon. Anyway, the source code and the required modules (jQuery) are free to download and can be customized as needed. A project containing the sources and modules will be available on our GitHub account.

The user interface is implemented as a single HTML5 / JavaScript page. It makes use of the HTML5 Media Capture and Streams API (nowadays supported by all current browser versions) to capture images from the webcam.

When a user opens the page, access to the camera is requested by the browser. After allowing access to the camera, the user can start the recording at any time using the buttons on top. After recording has been started the first image is automatically captured and sent to the Upload Web API. Then the application tries to detect motion in the central area in front of the camera. As soon as the motion-threshold is exceeded the next image is captured and uploaded.

The upload API at the BWS server performs a quality check of the uploaded images to decide, whether to keep the image or not. If enough images are available at the server, the application invokes the BWS liveness detection, verification, identification or enrollment Web API (as prescribed by the token). These operations automatically do a liveness detection (if requested) before performing the biometric operations. If the job succeeds the user is done. Otherwise the user is shortly notified about the failure and the procedure is restarted up to a maximum number of tries.

Request Information

Typically an application redirects here (via HTTP 302 status code), using a application/x-www-form-urlencoded message with parameters as follows:

• access_token

  Required. A BWS web token that has previously been issued by the Token Web API.
• return_url

  Required. An URL to redirect the user after the task has been carried out.
• state

  Recommended. Client specific data to maintain state between request and callback. For example you might want to add some information about the user you are verifying or enrolling.
• api_url

  Optional, defaults to https://bws.bioid.com/extension/ . The full URL of the BWS Web API instance the user interface shall use to perform the biometric actions. This has to be the same URL as the one that has been used to request the access_token above.
• trait

  Optional, defaults to Face. The UUI currently supports the traits Face and Periocular. To use both traits, just specify trait=Face,Periocular in the query.
• skipintro

  Optional, defaults to false. If set to false the user gets an instruction “How it works” before the biometric process starts. If set to true, the user starts immediately with the biometric process.

Response Information

The response is sent to the BWS client application using the provided return_url by sending a application/x-www-form-urlencoded message with parameters as follows:

• access_token

  The same BWS web token that has been sent to the unified user interface.
• state

  (only if presented) Client specific data to maintain state between request and callback.
• error

  (only for error response) The user interface forwards errors from the internal BWS Web API calls to the callback method. Additionally the error user_abort might be reported in case the user aborted the operation.
• skipintro

  The user interface forwards the information whether the user wants to see the instruction again (false) or not (true).

Sample Code

• C#
• Java

// pseudo-code to verify an already registered and enrolled user
public async Task VerifyUser(string userId)
{
// obtain a BWS token for verification
var bcid = GetBcid(userId);
var token = RequestBwsToken();
// send the user to the verify user interface
var returnUrl = WebUtility.UrlEncode("https://example.com/bwsVerifyCallback");
var state = WebUtility.UrlEncode(userId);  // or whatever you need in the callback, should be encrypted!
var verifyUrl = $"https://www.bioid.com/bws/uui?access_token={token}&return_url={returnUrl}&state={state}";
RedirectTo(verifyUrl);
}

public BwsVerifyCallback(string access_token, string state, string error)
{
// Please refer to the sample in the BWS Result Web API for a sample-implementation of this method.
}

// pseudo-code to verify an already registered and enrolled user
public void verifyUser(String userId) {
// obtain a BWS token for verification
String bcid = getBcid(userId);
String token = requestBwsToken();
// send the user to the verify user interface
String returnUrl = URLEncoder.encode("https://example.com/bwsVerifyCallback", "UTF-8");
String state = URLEncoder.encode(userId, "UTF-8");  // or whatever you need in the callback, should be encrypted!
String verifyUrl = String.format("https://www.bioid.com/bws/uui?access_token=%s&return_url=%s&state=%s", token, returnUrl, state);
redirectTo(verifyUrl);
}

public void bwsVerifyCallback(String access_token, String state, String error) {
// Please refer to the sample in the BWS Result Web API for a sample-implementation of this method.
}