Oz Liveness WEB Plugin

Adding OzLiveness plugin to the client’s web page.

In order to embed the plugin on your page you have to add the file with styles (ozliveness.css) and the primary script of the plugin (plugin_liveness.php) to the HTML code of that page. Required language packs can be specified additionally when you activate the plugin. If no language pack is specified, default language will be used. Example of code to be added:

Launching OzLiveness plugin.

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

options: an object with the following settings:
- lang: a string containing identifier of one of installed language packs;
- meta: an object with names of meta fields in keys and their string values in values. Metadata are transferred to Oz API and can be used to obtain analysis results (example of interaction with Oz API);
- params: an object with identifiers and additional parameters:
  - extract_best_shot: true/false: run the best frame choice in Quality analysis;
- action: 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: head turn to the left;
  - video_selfie_right: head turn to the right;
  - video_selfie_down: head tilt downwards;
  - video_selfie_high: head raise up;
  - video_selfie_zoom_in: face movement towards the camera;
  - video_selfie_zoom_out: face movement away from the camera;
  - video_selfie_scan: scanning.
- on_submit(): callback function that is called after submitting customer data to the server.
- on_result(result): callback function that is called several times during an analysis and retrieves an intermediate result.
- on_complete(result): callback function that is called after the check is completed.
- on_close(): callback function that is called after the plugin window is closed (whether manually by the user or automatically after the check is completed).

IMPORTANT: Recommendations on the safe use of the module.

In order to improve the defense against attacks with a substituted ‘action’ parameter on the browser side and to prevent leakage of verification results it is recommended to use the Oz Liveness WEB SDK module in real-life conditions with the following settings only:

Parameter ‘actions_default_importance’ (provide a link to the subsection “Oz Liveness WEB SDK/Oz Liveness WEB Adapter” here) of the Oz Liveness WEB Adapter configuration file: set to ‘true’
Parameter ‘result_mode’ (provide a link to the subsection “Oz Liveness WEB SDK/Oz Liveness WEB Adapter” here) of the Oz Liveness WEB Adapter configuration file: set to ‘safe
Retrieving the results of analyses with the Oz API method Folder [SINGLE] (GET)

With these settings the launch parameters of the Oz Liveness WEB Plugin module and verification results will be stored on secured servers only, beyond access of cybercriminals.

Example of secure calling a method with default settings.

                
OzLiveness.open({
    lang: 'ru',
    meta: {
        'client_id': '123',
        'session_id': '321'
    },
    on_complete: function()
    {
        // your code
    }
});

If no “action” parameter is specified at the plugin launch, by default Liveness verification form (taking video of one random action) will be called and then the QUALITY analysis will be launched by Oz API. Default settings can be configured on the server side.

Example of calling a method with taking photos of an ID card and a specified Liveness action

                
OzLiveness.open({
    lang: 'ru',
    meta: {
        'client_id': '123',
        'session_id': '321'
    },
    action: ['photo_id_front', 'photo_id_back', 'video_selfie_scan'],
    on_complete: function(result)
    {
        // your code
    }
});

If actions “photo_id_front” and “photo_id_back” are specified, capture forms for the face and back sides of an ID card will be called, and analyses DOCUMENTS and BIOMETRY will be launched by Oz API. Specification of one or several actions “video_selfie_*” calls a form that will take video of the user’s face and then launch the QUALITY analysis. As soon as the analyses are completed their result is returned to the function specified in “on_complete” parameter.

Use of the module in implementation and test mode.

During implementation and testing the Oz Liveness WEB SDK module it can be used with the following settings to accelerate the process:

Parameter ‘actions_default_importance’ (provide a link to the subsection “Oz Liveness WEB SDK/Oz Liveness WEB Adapter” here) of the Oz Liveness WEB Adapter configuration file: set to ‘false’
Parameter ‘result_mode’ (provide a link to the subsection “Oz Liveness WEB SDK/Oz Liveness WEB Adapter” here) of the Oz Liveness WEB Adapter configuration: set to ‘full’

Important: To improve the defense against attacks with a substituted ‘action’ parameter on the browser side and to prevent leakage of verification results it is strongly advised AGAINST using these settings in real-life conditions.

The result of verification in this mode can be obtained in the plug-in in JSON format. Also these settings allow to override the ‘action’ parameter when the plug-in runs in a browser. Examples of using a module with overridden ‘action’ parameter:

Example of calling a method with specified Liveness actions without taking photos of an ID card

                
OzLiveness.open({
    lang: 'ru',
    meta: {
        'client_id': '123',
        'session_id': '321'
    },
    action: ['video_selfie_scan', 'video_selfie_left'],
    on_complete: function(result)
    {
        // your code
    }
});

Specification of one or several actions “video_selfie_*” calls a form that will take video of the user’s face and then launch the QUALITY analysis on the Oz API side. As soon as the analyses are completed their result is returned to the function specified in “on_complete” parameter.

Closing OzLiveness plugin.

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.

Example of use:

                
var session_id = 123;

OzLiveness.open({
    // We transfer arbitrary meta data, by which we can later identify the session in the 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 OzLiveness plugin window without canceling callback functions.

Hide() method can be used to hide the plugin window without canceling the requests for analysis results and user callback functions. This method may be useful eg. if you want to output an own upload indicator after submitting data.

Example of use:

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

Adding a custom language pack.

Method add_lang(lang_id, lang_obj) allows to add a new or customized language pack.

Parameters:

lang_id: a string value that can be subsequently used as lang parameter for open() method;
lang_obj: an object that includes identifiers of translation strings as keys and translation strings themselves as values.

Example of use:

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