Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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.
When result_mode
is safe
, the on_complete
callback contains the state of the analysis only:
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.
The folder
value is almost similar to the status
value, with the only difference: the folder_id
is added.
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.
The close()
method can be used to force the closing of the plugin window. All requests to server and callback functions (except on_close
) within the current session will be aborted.
An example of usage:
The hide()
method can be used to hide the plugin window without cancelling the requests for analysis results and user callback functions. Use this method, for instance, if you want to output your own upload indicator after submitting data.
An example of usage:
The plugin window is launched with open(options)
method:
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.
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 not set.
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).
In this article, you’ll learn how to capture videos and send them through your backend to Oz API.
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.
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:
The result object structure depends on whether any virtual camera is detected or not.
Here’s the list of variables with descriptions.
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:
Oz API accepts data without the base64 encoding.
Variable
Type
Description
best_frame
String
The best frame, JPEG in the data URL format
best_frame_png
String
The best frame, PNG in the data URL format, it is required for protection against virtual cameras when video is not used
best_frame_bounding_box
Array[Named_parameter: Int]
The coordinates of the bounding box where the face is located in the best frame
best_frame_landmarks
Array[Named_parameter: Array[Int, Int]]
The coordinates of the face landmarks (left eye, right eye, nose, mouth, left ear, right ear) in the best frame
frame_list
Array[String]
All frames in the data URL format
frame_bounding_box_list
Array[Array[Named_parameter: Int]]
The coordinates of the bounding boxes where the face is located in the corresponding frames
frame_landmarks
Array[Named_parameter: Array[Int, Int]]
The coordinates of the face landmarks (left eye, right eye, nose, mouth, left ear, right ear) in the corresponding frames
action
String
An action code
additional_info
String
Information about client environment
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.
When result_mode
is safe
, the on_result
callback contains the state of the analysis only:
or
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.
or
The folder
value is almost similar to the status
value, with the only difference: the folder_id
is added.
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.
A dedicated Web Adapter in our cloud or got the adapter deployed on-premise. The adapter's URL is needed for adding the plugin.
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.
For Angular and Vue, script (and files, if you use a version lower than 1.4.0) should be added in the same way. For React apps, use head
at your template's main page to load and initialize the OzLiveness plugin. Please note: if you use <React.StrictMode>
, you may experience issues with Web Liveness.
To set your own look-and-feel options, use the style
section in the Ozliveness.open
method. The options are listed below the example.
Main color settings.
Main font settings.
Title font settings.
Buttons’ settings.
Toolbar settings.
Center hint settings.
Hint animation settings.
Face frame settings.
Document capture frame settings.
Background settings.
Scam protection settings: the antiscam message warns user about their actions being recorded.
SDK version text settings.
3D mask settings. The mask has been implemented in 1.2.1.
Table of parameters' correspondence:
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.
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.
To set the SDK language, when you launch the plugin, specify the language identifier in lang
:
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.
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 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:
Mostly, license is set on the server side (Web Adapter). This article covers a rare case when you use Web Plugin only.
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.
To find the origin, in the developer mode, run window.origin
on the page you are going to embed Oz Web SDK in. At localhost / 127.0.0.1, license can work without this information.
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.
lang_id | Language |
---|
Browser | Version |
---|
Parameter
Description
textColorPrimary
Main text color
backgroundColorPrimary
Main background color
textColorSecondary
Secondary text color
backgroundColorSecondary
Secondary background color
iconColor
Icons’ color
Parameter
Description
textFont
Font
textSize
Font size
textWeight
Font weight
textStyle
Font style
Parameter
Description
textFont
Font
textSize
Font size
textWeight
Font weight
textStyle
Font style
Parameter
Description
textFont
Font
textSize
Font size
textWeight
Font weight
textStyle
Font style
textColorPrimary
Main text color
backgroundColorPrimary
Main background color
textColorSecondary
Secondary text color
backgroundColorSecondary
Secondary background color
cornerRadius
Button corner radius
Parameter
Description
closeButtonIcon
Close button icon
iconColor
Close button icon color
Parameter
Description
textFont
Font
textSize
Font size
textWeight
Font weight
textStyle
Font style
textColor
Text color
backgroundColor
Background color
backgroundOpacity
Background opacity
backgroundCornerRadius
Frame corner radius
verticalPosition
Vertical position
Parameter
Description
hideAnimation
Disable animation
hintGradientColor
Gradient color
hintGradientOpacity
Gradient opacity
animationIconSize
Animation icon size
Parameter
Description
geometryType
Frame shape: rectangle or oval
cornersRadius
Frame corner radius (for rectangle)
strokeDefaultColor
Frame color when a face is not aligned properly
strokeFaceInFrameColor
Frame color when a face is aligned properly
strokeOpacity
Stroke opacity
strokeWidth
Stroke width
strokePadding
Padding from stroke
Parameter
Description
cornersRadius
Frame corner radius
templateColor
Document template color
templateOpacity
Document template opacity
Parameter
Description
backgroundColor
Background color
backgroundOpacity
Background opacity
Parameter
Description
textMessage
Antiscam message text
textFont
Font
textSize
Font size
textWeight
Font weight
textStyle
Font style
textColor
Text color
textOpacity
Text opacity
backgroundColor
Background color
backgroundOpacity
Background opacity
backgroundCornerRadius
Frame corner radius
flashColor
Flashing indicator color
Parameter
Description
textFont
Font
textSize
Font size
textWeight
Font weight
textStyle
Font style
textColor
Text color
textOpacity
Text opacity
Parameter
Description
maskColor
The color of the mask itself
glowColor
The color of the glowing mask shape
minAlpha
Minimum mask transparency level. Implemented in 1.3.1
maxAlpha
Maximum mask transparency level. Implemented in 1.3.1
Previous design
New design
doc_color
-
face_color_success
faceFrame.faceReady
faceFrameCustomization.strokeFaceInFrameColor
face_color_fail
faceFrame.faceNotReady
faceFrameCustomization.strokeDefaultColor
centerHint.textSize
centerHintCustomization.textSize
centerHint.color
centerHintCustomization.textColor
centerHint.yPosition
centerHintCustomization.verticalPosition
centerHint.letterSpacing
-
centerHint.fontStyle
centerHintCustomization.textStyle
closeButton.image
-
backgroundOutsideFrame.color
backgroundCustomization.backgroundColor
en | English |
es | Spanish |
pt-br* | Portuguese (Brazilian) |
kz | Kazakh |
Google Chrome (and other browsers based on the Chromium engine) | 56 |
Mozilla Firefox | 55 |
Safari | 11 |
Microsoft Edge* | 17 |
Opera | 47 |
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:
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.
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.
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:
In the response, find the analysis results and folder_id
for future reference.
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".