BWS Unified User Interface Documentation

https://www.bioid.com/bws/performtask?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 https://www.bioid.com, but more implementations may be available soon. Anyway, the source code and the required modules (jQuery, Silverlight) 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 (supported by the current versions of Opera, Firefox, Chrome and Edge) to capture images from the webcam. In case the browser does not support the HTML5 Media Capture API, an alternative Silverlight module can be used to access the video capture device.

When a user opens the page, access to the camera is requested by the browser. After allowing access to the camera, the user can mirror the camera preview image if needed and 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 BWS 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 verification, identification or enrollment web API (as prescribed by the token). These operations automatically do a live 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.
bws_host
Obsolete. The BWS host the user interface shall use to perform the biometric actions. This parameter is superseeded by the api_url parameter, i.e. it is ignored if an api_url is found.
autostart
Optional, defaults to false. A boolean parameter that indicates whether to start the verification- or enrollment-procedure automatically as soon as the camera has been started. If set to false, the user has to press the start button to start recording, if set to true recording starts automatically.

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.

Intentionally the result of the biometric operation is not directly sent to the callback method. The result needs to be fetched explicitely with the Result Web API and interpreted accordingly.

Sample code

ASP.NET MVC 4 C# sample code that redirects to the BWS unified user interface to verify a user:
public async Task<ActionResult> VerifyUser(string userId)
{
  // pseudo-code to fetch the BCID of an already registerd and enrolled user
  string bcid = GetUserBCID(userId);
  // now request a BWS token
  var httpClient = new HttpClient();
  // requires Basic Authentication
  httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", 
      Convert.ToBase64String(Encoding.GetEncoding("iso-8859-1").GetBytes("sample.app.bioid.com:Sample-App-Secret")));
  // call the BWS Token Web API at bws.bioid.com
  var apiUrl = new Uri("https://bws.bioid.com/extension/");
  var uri = new Uri(apiUrl, $"token?id={sample.app.bioid.com}&bcid={bcid}&task=verify&livedetection=true&autoenroll=true");
  var response = await httpClient.GetAsync(uri);
  // the issued token is in the response body
  string token = await response.Content.ReadAsStringAsync();
  // send the user to the verify user interface
  string returnUrl = HttpUtility.UrlEncode($"https://{Request.Url.Host}/BWSVerifyCallback");
  string state = userId; // or whatever you need in the callback, should be encrypted!
  string verifyUrl = $"https://www.bioid.com/bws/performtask?access_token={token}&return_url={returnUrl}&state={state}&api_url={apiUrl}";
  return Redirect(verifyUrl);
}
// the rest is done in this callback method
public ActionResult 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.
}