Launching the Plugin

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

OzLiveness.open({
// omit session_token if your SDK version is older than 1.9.2
  session_token, 
  lang: 'en',
  action: [
    'photo_id_front', // request photo ID picture
    // you can add several gestures here for the multi-gesture scenario
    // 'video_selfie_smile',
    // 'video_selfie_eyes',
    'video_selfie_blank' // request passive liveness video
  ],
  meta: { 
    // an ID of user undergoing the check
    // add for easier conversion calculation
    'end_user_id': '<user_or_lead_id>',
    // 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_error: function (result) {
  // error details
  console.error('on_error', result);
  },
  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

Please note: license and token must be added on the backend, except for specific cases.

The full list of OzLiveness.open() parameters:

• options – an object with the following settings:

  • session_token – a specific token required to use OzCapsula data container.

  • token – (optional) the auth token;

  • license – an object containing the license data;

  • licenseUrl – a string containing the path to the license; _{Warning: The license and licenseUrl parameters override the server-side license, including its expiration date. If you use a server-side license, omit these parameters from OzLiveness.open(), otherwise, you might be getting a license error.}

  • 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. _{On January 1, 2027, the One Shot gesture will become unavailable. Please plan your migration.}

  • 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. A passed device_id is now always respected: if that camera is unavailable, the Web SDK returns an error. Without device_id, it tries all available cameras. use_for_liveness in the Web Adapter configuration parameters takes priority over device_id.

  • enable_3d_mask – enables the 3D mask as the default face capture behavior. This parameter works only if load_3d_mask in the Web Adapter configuration parameters is set to true; the default value is false. _{On January 1, 2027, 3D Mask will become unavailable. Please plan your migration.}

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