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.

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

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 .

Safe

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

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.

Folder

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

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;

• 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:

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:

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.

Oz Liveness Web SDK is a module for processing data on clients' devices. With Oz Liveness Web SDK, you can take photos and videos of people via their web browsers and then analyze these media. Most browsers and devices are supported. Available languages: EN, ES, PT-BR, KK.

Please find a sample for Oz Liveness Web SDK . 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.

Web SDK requires HTTPS (with SSL encryption) to work; however, at localhost and 127.0.01, you can check the resources' availability via HTTP.

Oz Liveness Web SDK consists of two components:

1. Client side – a JavaScript file that is being loaded within the frontend part of your application. It is called .

2. Server side – a separate server module with . The module is called Liveness.

The integration guides can be found here:

This is a guide on how to start with Oz Web SDK:

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

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;

  • 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_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).

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

  • 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: "", 
    },
  },
  // ...
});

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:

OzLiveness.open({
    license: {
        'payload_b64': 'some_payload',
        'signature': 'some_data',
        'enc_public_key': 'some_key'
    },
    ...,
})

• With license path:

OzLiveness.open({
    licenseUrl: 'https://some_url',
    ...,
})

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.6.12 – October 18, 2024

• Security updates.

• Resolved the issue where a video could not be generated from a sequence of frames.

1.6.0 – June 24, 2024

• The on_complete callback now is called upon folder status change.

• Updated instructions for camera access in the Android Chrome and Facebook browsers. New keys:

  • error_no_camera_access,

  • oz_tutorial_camera_android_chrome_with_screens_title,

  • oz_tutorial_camera_android_chrome_instruction_screen_click_settings,

  • oz_tutorial_camera_android_chrome_instruction_screen_permissions,

  • oz_tutorial_camera_android_chrome_instruction_screen_allow_access,

  • try_again,

  • oz_tutorial_camera_external_browser_button,

  • oz_tutorial_camera_external_browser_manual_open_link,

  • oz_tutorial_camera_external_browser_title.

• Added the get_langs() method that returns a list of locales available in the installed Web SDK.

• Added an error for the case of setting a non-available locale.

• Added an error for the case of lacking of a necessary resource. New key: unable_load_resource.

• Changed texts for the error_connection_lost and error_service_unavailable errors.

• Uploaded new Web SDK string files.

• The crop function no longer adds borders for images smaller than 512×512.

1.5.3 – May 28, 2024

• In case of camera access timeout, we now display a page with instructions for users to enable camera access: default for all browsers and specific for Facebook.

• Added several localization records to the Web SDK strings file. New localization keys:

  • accessing_camera_switch_to_another_browser,

  • error_camera_timeout_instruction,

  • error_camera_timeout_title,

  • error_camera_timeout_android_facebook_instruction.

1.5.0 – May 05, 2024

• Improved user experience for card printer machines. Users no longer need to get that close to the screen with face frame.

• Added the disable_adaptive_aspect_ratio parameter to the Web Plugin. This parameter switches off the default video aspect ratio adjustment to the window.

• Implemented the get_user_media_timeout parameter for Web Plugin: when SDK can’t get access to the user camera, after this timeout it displays a hint on how to solve the problem.

• Added several localization records into the Web SDK strings file. New keys:

  • oz_tutorial_camera_android_edge_browser

  • oz_tutorial_camera_android_edge_instruction

  • oz_tutorial_camera_android_edge_title

  • error_camera_timeout_instruction

  • error_camera_timeout_title

• Improved the localization: when SDK can’t find a translation for a key, it displays a message in English.

• You can now distribute the serverless Web SDK via Node Package Manager.

• You can switch off the display of API errors in modal windows. Set the disable_adapter_errors_on_screen parameter in the configuration file to True.

• The mobile browsers now use the rear camera to take the documents’ photos.

• Updated samples.

• Fixed the bug with abnormal 3D mask reaction when user needs to repeat a gesture.

• Logging and security updates.

1.4.3 – Apr. 15, 2024

• Fixed the bug where the warning about incorrect device orientation was not displayed when a mobile user attempted to take a video with their face in landscape orientation.

• Some users may have experienced freezes while using WebView. Now, users can tap a button to continue working with the application. The corresponding string has been added to the string file in the localization section. Key: tap_to_continue.

1.4.2 – Mar. 14, 2024

• Debugging improvements.

1.4.1 – Feb. 27, 2024

• Major security updates: improved protection against virtual cameras and JavaScript tampering.

• Improved WebView support:

  • Added camera access instructions for applications within the generic WebView browsers on Android and iOS. The corresponding events are added to telemetry.

  • Improved the React Native app integration by adding the webkit-playsinline attribute, thereby fixing the issue of the full-screen camera launch on iOS WebView.

• The iFrame using error when iframe_allowed = False is now shown properly.

• New localization keys:

  • oz_tutorial_camera_android_webview_browser

  • oz_tutorial_camera_android_webview_instruction

  • oz_tutorial_camera_android_webview_title

1.4.0 – Feb. 07, 2024

• You can now use Web SDK for the Black List analysis: to compare the face from your Liveness video with faces from your database. Create a collection (or collections) with these photos via API or Web UI, and add the corresponding ID (or IDs) to the analyses.collection_ids array in the Web Adapter configuration file.

• The iframe support is back: set the iframe_allowed parameter in the Web Adapter configuration file to True.

• The interval for polling for the analyses’ results is now configurable. Change it in the results_polling_interval parameter of the Web Adapter configuration file if necessary.

• You can now select the front or back camera via Web Plugin. In the OzLiveness.open() method, set cameraFacingMode to user for the front camera and environment for the back one. This parameter only works when the use_for_liveness option in the Web Adapter configuration file is not set.

• The plugin styles are now being added automatically. Please remove <link rel="stylesheet" href="/plugin/ozliveness.css" /> from your page to prevent style conflicts.

• Fixed some bugs and updated telemetry.

1.3.1 – Jan. 12, 2024

• Improved the protection against injection attacks.

• Replaced the code for Brazilian Portuguese from pt to pt-br to match the ISO standard.

• Removed the lang_default adapter parameter.

• The 3D mask transparency became customizable.

• Implemented the possibility of using a master license that works with any domain.

• Added the master_license_signature option into Web Adapter configuration parameters.

• Fixed some bugs.

1.2.2 – Dec. 15, 2023

• Internal SDK improvements.

1.2.1 – Nov. 04, 2023

• To enhance your clients’ experience with Web SDK, we implemented the 3D-mask that replaces the oval during face capture. To make it work, set the load_3d_mask in Configuration file settings to true.

• Updated telemetry (logging).

1.1.5 – Oct. 27, 2023

• Logging updates.

1.1.4 – Oct. 2023

• Security updates.

1.1.3 – Sept. 29, 2023

• Internal SDK improvements.

1.1.2 – Sept. 21, 2023

• Internal SDK improvements.

1.1.1 – Aug. 29, 2023

• Fixed some bugs.

1.1.0 – Aug. 24, 2023

• Changed the signature of the on_error() callback: now it returns an object with the error code, error message, and telemetry ID for logging.

• Added the configuration parameter for the debug mode. If True, the Web SDK enables access to the /debug.php page, which contains information about the current configuration and the current license.

• Fixed some bugs and improved logging.

1.0.2 – July 06, 2023

• If your device has multiple cameras, you can now choose one when launching the Web Plugin.

1.0.1 – July 01, 2023

• Implemented the new design for SDK and demo, including the scam protection option: the antiscam message warns user about their actions being recorded. Please check the new customization options here.

• Added the Portuguese, Spanish, and Kazakh locales.

• Added the combo gesture.

• Added the progress bar for media upload.

• Removed the Zoom in / Zoom out gestures.

• On tablets, you can now capture video in landscape orientation.

• Removed the lang_allow option from Web Adapter configuration file.

0.9.1 – Mar. 01, 2023

• In the capture architecture, when a virtual camera is detected, the additional_info parameter is inside the from_virtual_camera section.

• You can now crop the lossless frame without losing quality.

• Fixed face landmarks for the capture architecture.

0.9.0 – Feb. 20, 2023

• Improved the recording quality;

• Reforged licensing:

  • added detailed error descriptions;

  • now you can set the license in JS during the runtime;

  • when you set a license in OzLiveness.open(), it rewrites the previous license;

  • the license no longer requires port and protocol;

  • you can now specify subdomains in the license;

  • upon the launch of the plugin on a server, the license payload is displayed in the Docker log;

  • localhost and 127.0.0.1 no longer ask for a license;

• The on_capture_complete callback is now available on any architecture: it is called once a video is taken and returns info on actions from the video;

• Oz Web Liveness and Oz Web Adapter versions are displayed in the Docker log upon launch;

• Deleted the deprecated adapter_version field from order metadata;

• Added the parameters to pass the information about the bounding box – landmarks that define where the face in the frame is;

• Fixed the Switch camera button in Google Chrome;

• Upon the start of Web SDK, the actual configuration parameters are displayed in the Docker log.

0.7.6 – Sept. 27, 2022

• Changed the extension of some Oz system files from .bin to .dat.

0.7.5

• Additional scripts are now called using the main script's address.

0.7.4

• Web SDK now can be installed via static files only (works for the capture type of architecture).

• Web SDK can now work with CDN.

• Now, you can launch several Oz Liveness plugins on different pages. In this case, you need to specify the path to scripts in head of these pages.

0.4.1

• Fixed a bug with the shooting screen.

0.4.0

• Added licensing (requires origin).

• You can now customize the look-and-feel of Web SDK.

0.3.2044

• Fixed Angular integration.

0.3.2043

• Fixed the bug where the IMAGE_FOLDER section was missed in the JSON response with the lossless frame enabled.

0.3.2042

• Fixed issues with the ravenjs library.

0.3.2041

• A frame for taking a documents photo is now customizable.

0.3.2012

• Implemented security updates.

0.3.2009 (0.4.8)

• Metadata now contains names of all cameras you can use.

0.3.2005 (0.4.8)

• Video and zip formats now allow loading a lossless image.

• Fixed Best Shot.

0.3.2004 (0.4.8)

• Separated the error code and error description in server responses.

0.3.2001 (0.4.6)

• If the SDK mode is set in the environment variables architecture, api_url, it is passed to settings automatically.

• In the Lite mode, you can select the best frame for any action.

• In the Lite mode, an image sent via API gets the on_complete status only after a successful liveness.

• You can manage CORS using the environment variables (CORS headers are not added by default).

0.3.1999

• Added the folder value for result_mode: it returns the same value as status but with folder_id.

0.3.1997 (0.4.5)

• Updated encryption: now only metadata required to decrypt an object is encrypted.

• Updated data transfer: images are being sent in separate form fields.

• Added the camera parameters check.

0.3.1992 (0.4.4)

• Enabled a new method for image encryption.

• Optimized image transfer format.

0.3.1991

• Added the use_for_liveness option: mobile devices use back camera by default, on desktop, flip and oval circling are off. By default, the option is switched off.

0.3.1990 (0.4.3)

• Decreased video length for video_selfie_best (the Selfie gesture) from 1 to 0,2 sec.

• Loading scripts is now customizable.

• Improved UX.

0.3.1988 (0.4.2)

• Added the Kazakh locale.

• Added a guide for accessing the camera on a desktop.

• Improved logging: plugin_liveness.php requests and recording user-agent to the server log.

• Added the Lite mode.

0.3.1987 (0.4.1)

• Added encryption.

• Updated libraries.

0.3.1986 (0.3.91)

• You can now hide the Oz Forensics logo.

0.3.1984

• Updated a guide for Facebook, Instagram, Samsung, Opera.

• Added handlers for unknown variables and a guide for “unknown” browsers.

0.3.1983

• Optimized memory usage for a frame.

• Added a guide on how to switch cameras on using Android browsers.

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

OzLiveness.open({
style: {
    baseColorCustomization: {
        textColorPrimary: "#000000",
        backgroundColorPrimary: "#FFFFFF",
        textColorSecondary: "#8E8E93",
        backgroundColorSecondary: "#F2F2F7",
        iconColor: "#00A5BA"
    },
    baseFontCustomization: {
        textFont: "Roboto, sans-serif",
        textSize: "16px",
        textWeight: "400",
        textStyle: "normal"
    },
    titleFontCustomization: {
        textFont: "inherit",
        textSize: "36px",
        textWeight: "500",
        textStyle: "normal"
    },
    buttonCustomization: {
        textFont: "inherit",
        textSize: "14px",
        textWeight: "500",
        textStyle: "normal",
        textColorPrimary: "#FFFFFF",
        backgroundColorPrimary: "#00A5BA",
        textColorSecondary: "#00A5BA",
        backgroundColorSecondary: "#DBF2F5",
        cornerRadius: "10px"
    },
    toolbarCustomization: {
        closeButtonIcon: "cross",
        iconColor: "#707070"
    },
    centerHintCustomization: {
        textFont: "inherit",
        textSize: "24px",
        textWeight: "500",
        textStyle: "normal",
        textColor: "#FFFFFF",
        backgroundColor: "#1C1C1E",
        backgroundOpacity: "56%",
        backgroundCornerRadius: "14px",
        verticalPosition: "38%"
    },
    hintAnimation: {
        hideAnimation: false,
        hintGradientColor: "#00BCD5",
        hintGradientOpacity: "100%",
        animationIconSize: "80px"
    },
    faceFrameCustomization: {
        geometryType: "oval",
        cornersRadius: "0px",
        strokeDefaultColor: "#D51900",
        strokeFaceInFrameColor: "#00BCD5",
        strokeOpacity: "100%",
        strokeWidth: "6px",
        strokePadding: "4px"
    },
    documentFrameCustomization: {
        cornersRadius: "20px",
        templateColor: "#FFFFFF",
        templateOpacity: "100%"
    },
    backgroundCustomization: {
        backgroundColor: "#FFFFFF",
        backgroundOpacity: "88%"
    },
    antiscamCustomization: {
        enableAntiscam: false,
        textMessage: "",
        textFont: "inherit",
        textSize: "14px",
        textWeight: "500",
        textStyle: "normal",
        textColor: "#000000",
        textOpacity: "100%",
        backgroundColor: "#F2F2F7",
        backgroundOpacity: "100%",
        backgroundCornerRadius: "20px",
        flashColor: "#FF453A"
    },
    versionTextCustomization: {
        textFont: "inherit",
        textSize: "16px",
        textWeight: "500",
        textStyle: "normal",
        textColor: "#000000",
        textOpacity: "56%"
    },
    maskCustomization: {
            maskColor: "#008700",
            glowColor: "#000102",
            minAlpha: "30%", // 0 to 1 or 0% to 100%
            maxAlpha: "100%" // 0 to 1 or 0% to 100%

    }

}
});

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:

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.

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 architecture parameter must be set to capture in the app_config.json file.

In your Web app, add a callback to process captured media when opening the Web SDK plugin:

OZLiveness.open({
  ... // other parameters
  on_capture_complete: function(result) {
         // Your code to process media/send it to your API, this is STEP #2
  }
})

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

No Virtual Camera Detected

{
	"action": <action>,
	"best_frame": <bestframe>,
	"best_frame_png": <bestframe_png>,
	"best_frame_bounding_box": {
		"left": <bestframe_bb_left>,
		"top": <bestframe_bb_top>,
		"right": <bestframe_bb_right>,
		"bottom": <bestframe_bb_bottom>
		},
	"best_frame_landmarks": {
		"left_eye": [bestframe_x_left_eye, bestframe_y_left_eye],
		"right_eye": [bestframe_x_right_eye, bestframe_y_right_eye],
		"nose_base": [bestframe_x_nose_base, bestframe_y_nose_base],
		"mouth_bottom": [bestframe_x_mouth_bottom, bestframe_y_mouth_bottom],
		"left_ear": [bestframe_x_left_ear, bestframe_y_left_ear],
		"right_ear": [bestframe_x_right_ear, bestframe_y_right_ear]
		},
	"frame_list": [<frame1>, <frame2>],
	"frame_bounding_box_list": [
		{
		"left": <frame1_bb_left>,
		"top": <frame1_bb_top>,
		"right": <frame1_bb_right>,
		"bottom": <frame1_bb_bottom>
		},
		{
		"left": <frame2_bb_left>,
		"top": <frame2_bb_top>,
		"right": <frame2_bb_right>,
		"bottom": <frame2_bb_bottom>
		},
	],
	"frame_landmarks": [
		{
		"left_eye": [frame1_x_left_eye, frame1_y_left_eye],
		"right_eye": [frame1_x_right_eye, frame1_y_right_eye],
		"nose_base": [frame1_x_nose_base, frame1_y_nose_base],
		"mouth_bottom": [frame1_x_mouth_bottom, frame1_y_mouth_bottom],
		"left_ear": [frame1_x_left_ear, frame1_y_left_ear],
		"right_ear": [frame1_x_right_ear, frame1_y_right_ear]
		},
		{
		"left_eye": [frame2_x_left_eye, frame2_y_left_eye],
		"right_eye": [frame2_x_right_eye, frame2_y_right_eye],
		"nose_base": [frame2_x_nose_base, frame2_y_nose_base],
		"mouth_bottom": [frame2_x_mouth_bottom, frame2_y_mouth_bottom],
		"left_ear": [frame2_x_left_ear, frame2_y_left_ear],
		"right_ear": [frame2_x_right_ear, frame2_y_right_ear]
		}
	],
"from_virtual_camera": null,
"additional_info": <additional_info>
}

Any Virtual Camera Detected

{
	"action": <action>,
	"best_frame": null,
	"best_frame_png": null,
	"best_frame_bounding_box": null,
	"best_frame_landmarks": null
	"frame_list": null,
	"frame_bounding_box_list": null,
	"frame_landmarks": null,
	"from_virtual_camera": {
	"additional_info": <additional_info>,
		"best_frame": <bestframe>,
		"best_frame_png": <best_frame_png>,
		"best_frame_bounding_box": {
			"left": <bestframe_bb_left>,
			"top": <bestframe_bb_top>,
			"right": <bestframe_bb_right>,
			"bottom": <bestframe_bb_bottom>
			},
		"best_frame_landmarks": {
			"left_eye": [bestframe_x_left_eye, bestframe_y_left_eye],
			"right_eye": [bestframe_x_right_eye, bestframe_y_right_eye],
			"nose_base": [bestframe_x_nose_base, bestframe_y_nose_base],
			"mouth_bottom": [bestframe_x_mouth_bottom, bestframe_y_mouth_bottom],
			"left_ear": [bestframe_x_left_ear, bestframe_y_left_ear],
			"right_ear": [bestframe_x_right_ear, bestframe_y_right_ear]
			},
		"frame_list": [<frame1>, <frame2>],
		"frame_bounding_box_list": [
			{
			"left": <frame1_bb_left>,
			"top": <frame1_bb_top>,
			"right": <frame1_bb_right>,
			"bottom": <frame1_bb_bottom>
			},
			{
			"left": <frame2_bb_left>,
			"top": <frame2_bb_top>,
			"right": <frame2_bb_right>,
			"bottom": <frame2_bb_bottom>
			},
			],
		"frame_landmarks": [
			{
			"left_eye": [frame1_x_left_eye, frame1_y_left_eye],
			"right_eye": [frame1_x_right_eye, frame1_y_right_eye],
			"nose_base": [frame1_x_nose_base, frame1_y_nose_base],
			"mouth_bottom": [frame1_x_mouth_bottom, frame1_y_mouth_bottom],
			"left_ear": [frame1_x_left_ear, frame1_y_left_ear],
			"right_ear": [frame1_x_right_ear, frame1_y_right_ear]
			},
			{
			"left_eye": [frame2_x_left_eye, frame2_y_left_eye],
			"right_eye": [frame2_x_right_eye, frame2_y_right_eye],
			"nose_base": [frame2_x_nose_base, frame2_y_nose_base],
			"mouth_bottom": [frame2_x_mouth_bottom, frame2_y_mouth_bottom],
			"left_ear": [frame2_x_left_ear, frame2_y_left_ear],
			"right_ear": [frame2_x_right_ear, frame2_y_right_ear]
			}
		]
	}
}

Here’s the list of variables with descriptions.

Please note:

• The video from Oz Web SDK is a frame sequence, so, to send it to Oz API, you’ll need to archive the frames and transmit them as a ZIP file via the POST /api/folders request (check our Postman collections).

• 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:

"VIDEO_FILE_KEY": VIDEO_FILE_ZIP_BINARY
"payload": "{
        "media:meta_data": {
           "VIDEO_FILE_KEY": {
              "additional_info": <additional_info>
              }
           }
}"

• Oz API accepts data without the base64 encoding.

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.

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.

OzLiveness.open({
  ...
  meta: { 
  // the user or lead ID from an external lead generator 
  // that you can pass to keep track of multiple attempts made by the same user
    'user_id': '<user_or_lead_id>',
  // the unique attempt ID
    'transaction_id': '<unique_transaction_id>'
  }
});

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.

/api/folders/?meta_data=transaction_id==unique_id1&with_analyses=true

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:

   Copy

   /api/folders/?meta_data=transaction_id==unique_id1&with_analyses=true

   To speed up the processing of your request, we recommend adding the time filter as well:

   Copy

   /api/folders/?meta_data=transaction_id==unique_id1&with_analyses=true&time_created.min=([CURRENT_TIME]-1hour)

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

Web Adapter may send analysis results to the Web Plugin with various levels of verbosity. It is recommended that, in production, the level of verbosity is set to minimum. In the Web Adapter configuration file, set the result_mode parameter to "safe".

"result_mode": "safe"