This callback is called periodically during the analysis’ processing. It retrieves an intermediate result (unavailable for the capture mode). The result content depends on the Web Adapter result_mode configuration parameter.

Safe

When result_mode is safe, the on_result callback contains the state of the analysis only:

{
 "state": "processing"
}

or

{
 "state": "finished"
}

Status

For the status value, the callback contains the state of the analysis, and for each of the analysis types, the name of the type, state, and resolution.

{
 "state": "processing",
 "analyses": {
   "quality": {
     "state": "processing",
     "resolution": ""
   }
 }
}

or

{
 "state": "finished",
 "analyses": {
   "quality": {
     "state": "finished",
     "resolution": "success"
   }
 }
}

Folder

The folder value is almost similar to the status value, with the only difference: the folder_id is added.

{
 "state": "processing",
 "folder_id": "your_folder_id",
 "analyses": {
   "quality": {
     "state": "processing",
     "resolution": ""
   }
 }
}

Full

If result_mode is set to full, you will either receive:

• while the analysis is in progress, the response similar to the status response for processing;

• once the analysis is finished, the full information on the analysis:

  • everything that you could see in the folder mode;

  • timestamps;

  • metadata;

  • analyses’, company, analysis group IDs;

  • thresholds;

  • media info;

  • and more.

Closing the Plugin

To force the closing of the plugin window, use the close() method. All requests to server and callback functions (except on_close) within the current session will be aborted.

Example:

var session_id = 123;

OzLiveness.open({
  // We transfer the arbitrary meta data, by which we can later identify the session in Oz API
  meta: {
    session_id: session_id 
  },
  // After sending the data, forcibly close the plugin window and independently request the result
  on_submit: function() {
    OzLiveness.close();
    my_result_function(session_id);
  }
});

Hiding the Plugin Window without Cancelling the Callbacks

To hide the plugin window without cancelling the requests for analysis results and user callback functions, call the hide() method. Use this method, for instance, if you want to display your own upload indicator after submitting data.

An example of usage:

OzLiveness.open({
  // When receiving an intermediate result, hide the plugin window and show your own loading indicators
  on_result: function(result) {
    OzLiveness.hide();
    if (result.state === 'processing') {
      show_my_loader();
    }
  },
  on_complete: function() {
    hide_my_loader();
  }
});

The plugin window is launched with open(options) method:

OzLiveness.open({
  lang: 'en',
  action: [
    'photo_id_front', // request photo ID picture
    'video_selfie_blank' // request passive liveness video
  ],
  meta: { 
    // Your unique identifier that you can use later to find this folder in Oz API 
    // Optional, yet recommended
    'transaction_id': '<your_transaction_id>',
    // You can add iin if you plan to group transactions by the person identifier 
    'iin': '<your_client_iin>',
    // Other meta data
    'meta_key': 'meta_value',
  },
  on_complete: function (result) {
    // This callback is invoked when the analysis is complete
    // It is recommended to commence the transaction on your backend, 
    // using transaction_id to find the folder in Oz API and get the results
    console.log('on_complete', result);
  },
  on_capture_complete: function (result) {
    // Handle captured data here if necessary
    console.log('on_capture_complete', result);
  }
});

Call GET /api/folders/?meta_data=transaction_id==<your_transaction_id> to find a folder in Oz API from your backend by your unique identifier.

Read more about Oz API.

Parameters

The full list of OzLiveness.open() parameters:

• options– an object with the following settings:

  • token – (optional) the auth token;

  • license – an object containing the license data;

  • licenseUrl – a string containing the path to the license;

  • lang – a string containing the identifier of one of the installed language packs;

  • meta– an object with names of meta fields in keys and their string values in values. Metadata is transferred to Oz API and can be used to obtain analysis results or for searching;

  • params– an object with identifiers and additional parameters:

    • extract_best_shot– true or false: run the best frame choice in the Quality analysis;

  • action– an array of strings with identifiers of actions to be performed. Available actions:

    • photo_id_front – photo of the ID front side;

    • photo_id_back – photo of the ID back side;

    • video_selfie_left – turn head to the left;

    • video_selfie_right – turn head to the right;

    • video_selfie_down – tilt head downwards;

    • video_selfie_high – raise head up;

    • video_selfie_smile – smile;

    • video_selfie_eyes – blink;

    • video_selfie_scan – scanning;

    • video_selfie_blank – no action, simple selfie;

    • video_selfie_best – special action to select the best shot from a video and perform analysis on it instead of the full video.

  • overlay_options – the document's template displaying options:

    • show_document_pattern: true/false – true by default, displays a template image, if set to false, the image is replaced by a rectangular frame;

  • on_submit– a callback function (no arguments) that is called after submitting customer data to the server (unavailable for the capture mode).

  • on_capture_complete – a callback function (with one argument) that is called after the video is captured and retrieves the information on this video. The example of the response is described here.

  • on_result– a callback function (with one argument) that is called periodically during the analysis and retrieves an intermediate result (unavailable for the capture mode). The result content depends on the Web Adapter result_mode configuration parameter and is described here.

  • on_complete– a callback function (with one argument) that is called after the check is completed and retrieves the analysis result (unavailable for the capture mode). The result content depends on the Web Adapter result_mode configuration parameter and is described here.

  • on_error – a callback function (with one argument) that is called in case of any error happened during video capturing and retrieves the error information: an object with the error code, error message, and telemetry ID for logging.

  • on_close– a callback function (no arguments) that is called after the plugin window is closed (whether manually by the user or automatically after the check is completed).

  • style – the customization section.

  • device_id – (optional) identifier of camera that is being used.

  • cameraFacingMode (since 1.4.0) – the parameter that defines which camera to use; possible values: user (front camera), environment (rear camera). This parameter only works if the use_for_liveness option in the Web Adapter configuration file is undefined. If use_for_liveness is set (with any value), cameraFacingMode gets overridden and ignored.

  • disable_adaptive_aspect_ratio (since 1.5.0) – if True, disables the video adaptive aspect ratio, so your video doesn’t automatically adjust to the window aspect ratio. The default value is False, and by default, the video adjusts to the closest ratio of 4:3, 3:4, 16:9, or 9:16. Please note: smartphones still require the portrait orientation to work.

  • get_user_media_timeout (since 1.5.0) – when Web SDK can’t get access to the user camera, after this timeout it displays a hint on how to solve the problem. The default value is 40000 (ms).

To set your own look-and-feel options, use the style section in the Ozliveness.open method. Here is what you can change:

• faceFrame – the color of the frame around a face:

  • faceReady – the frame color when the face is correctly placed within the frame;

  • faceNotReady – the frame color when the face is placed improperly and can't be analyzed.

• centerHint – the text of the hint that is displayed in the center.

  • textSize – the size of the text;

  • color – the color of the text;

  • yPosition – the vertical position measured from top;

  • letterSpacing – the spacing between letters;

  • fontStyle – the style of font (bold, italic, etc.).

• closeButton – the button that closes the plugin:

  • image – the button image, can be an image in PNG or dataURL in base64.

• backgroundOutsideFrame – the color of the overlay filling (outside the frame):

  • color – the fill color.

Example:

OzLiveness.open({
  // ...
  style: {
        // the backward compatibility block
    doc_color: "", 
    face_color_success: "",
    face_color_fail: "", 
	// the current customization block
    faceFrame: {
      faceReady: "",
      faceNotReady: "",
    },
    centerHint: {
      textSize: "",
      color: "",
      yPosition: "",
      letterSpacing: "", 
      fontStyle: "", 
    },
    closeButton: {
      image: "",
    },
    backgroundOutsideFrame: {
      color: "", 
    },
  },
  // ...
});

This callback is called after the check is completed. It retrieves the analysis result (unavailable for the capture mode). The result content depends on the Web Adapter result_mode configuration parameter.

Safe

When result_mode is safe, the on_complete callback contains the state of the analysis only:

{
  "state": "finished"
}

Status

For the status value, the callback contains the state of the analysis, and for each of the analysis types, the name of the type, state, and resolution.

{
 "state": "finished",
 "analyses": {
   "quality": {
     "state": "finished",
     "resolution": "success"
   }
 }
}

Folder

The folder value is almost similar to the status value, with the only difference: the folder_id is added.

{
 "state": "finished",
 "folder_id": "your_folder_id",
 "analyses": {
   "quality": {
     "state": "finished",
     "resolution": "success"
   }
 }
}

Full

If result_mode is set to full, you receive the full information on the analysis:

• everything that you could see in the folder mode;

• score (the value of the min_confidence or confidence_spoofing parameters; please refer to this article for details);

• timestamps;

• metadata;

• analyses’, company, analysis group IDs;

• thresholds;

• media info;

• and more.

Web Plugin is a plugin called by your web application. It works in a browser context. The Web Plugin communicates with Web Adapter, which, in turn, communicates with Oz API.

Please find a sample for Oz Liveness Web SDK here. To make it work, replace <web-adapter-url> with the Web Adapter URL you've received from us.

For Angular and React, replace https://web-sdk.sandbox.ohio.ozforensics.com in index.html.

• Angular sample

• React sample

The add_lang(lang_id, lang_obj) method allows adding a new or customized language pack.

Parameters:

• lang_id: a string value that can be subsequently used as lang parameter for the open() method;

• lang_obj: an object that includes identifiers of translation strings as keys and translation strings themselves as values.

A list of language identifiers:

*Formerly pt, changed in 1.3.1.

An example of usage:

OzLiveness.add_lang('en', enTranslation), where enTranslation is a JSON object.

// Editing the button text
OzLiveness.add_lang('en', {
  action_photo_button: 'Take a photo'
});

To set the SDK language, when you launch the plugin, specify the language identifier in lang:

OzLiveness.open({
    lang: 'es', // the identifier of the needed language
    ...
});

You can check which locales are installed in Web SDK: use the ozLiveness.get_langs() method. If you have added a locale manually, it will also be shown.

A list of all language identifiers:

The keys oz_action_*_go refer to the appropriate gestures. oz_tutorial_camera_* – to the hints on how to enable camera in different browsers. Others refer to the hints for any gesture, info messages, or errors.

Since 1.5.0, if your language pack doesn't include a key, the message for this key will be shown in English.

Requirements

A dedicated Web Adapter in our cloud or the adapter deployed on-premise. The adapter's URL is required for adding the plugin.

Processing Steps

To embed the plugin in your page, add a reference to the primary script of the plugin (plugin_liveness.php) that you received from Oz Forensics to the HTML code of the page. web-sdk-root-url is the Web Adapter link you've received from us.

Please note: for the plugin to work, your browser version should support JavaScript ES6 and be the one as follows or newer.

*Web SDK doesn't work in Internet Explorer compatibility mode due to lack of important functions.

To generate the license, we need the domain name of the website where you are going to use Oz Forensics Web SDK, for instance, your-website.com. You can also define subdomains.

Set the license as shown below:

• With license data:

• With license path:

Check whether the license is updated properly.

Example

Proceed to your website origin and launch Liveness -> Simple selfie.

Once the license is added, the system will check its validity on launch.

1. Overview

Here is the data flow for your scenario:

1. Oz Web SDK takes a video and makes it available for the host application as a frame sequence.

2. The host application calls your backend using an archive of these frames.

3. After the necessary preprocessing steps, your backend calls Oz API, which performs all necessary analyses and returns the analyses’ results.

4. Your backend responds back to the host application if needed.

2. Implementation

On the server side, Web SDK must be configured to operate in the Capture mode:

The result object structure depends on whether any virtual camera is detected or not.

No Virtual Camera Detected

Any Virtual Camera Detected

Here’s the list of variables with descriptions.

Please note:

• You can retrieve the MP4 video from a folder using the /api/folders/{{folder_id}} request with this folder's ID. In the JSON that you receive, look for the preview_url in source_media. The preview_url parameter contains the link to the video. From the plugin, MP4 videos are unavailable (only as frame sequences).

• Also, in the POST {{host}}/api/folders request, you need to add the additional_info field. It is required for the capture architecture mode to gather the necessary information about client environment. Here’s the example of filling in the request’s body:

• Oz API accepts data without the base64 encoding.

Retrieve the analysis response and process it on the back end

Even though the analysis result is available to the host application via Web Plugin callbacks, it is recommended that the application back end receives it directly from Oz API. All decisions of the further process flow should be made on the back end as well. This eliminates any possibility of malicious manipulation with analysis results within the browser context.

To find your folder from the back end, you can follow these steps:

1. On the front end, add your unique identifier to the folder metadata.

You can add your own key-value pairs to attach user document numbers, phone numbers, or any other textual information. However, ensure that tracking personally identifiable information (PII) complies with relevant regulatory requirements.

1. Use the on_complete callback of the plugin to be notified when the analysis is done. Once used, call your back end and pass the transaction_id value.

2. On the back end side, find the folder by the identifier you've specified using the Oz API Folder LIST method:

   To speed up the processing of your request, we recommend adding the time filter as well:
3. In the response, find the analysis results and folder_id for future reference.

Limit amount of the information sent to Web Plugin from the server

To set your own look-and-feel options, use the style section in the Ozliveness.open method. The options are listed below the example.

baseColorCustomization

Main color settings.

baseFontCustomization

Main font settings.

titleFontCustomization

Title font settings.

buttonCustomization

Buttons’ settings.

toolbarCustomization

Toolbar settings.

centerHintCustomization

Center hint settings.

hintAnimation

Hint animation settings.

faceFrameCustomization

Face frame settings.

documentFrameCustomization

Document capture frame settings.

backgroundCustomization

Background settings.

antiscamCustomization

Scam protection settings: the antiscam message warns user about their actions being recorded.

versionTextCustomization

SDK version text settings.

maskCustomization

3D mask settings. The mask has been implemented in 1.2.1.

Migrating to the New Design from the Previous Versions (before 1.0.1)

Table of parameters' correspondence: