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 or you have set api_use_session_token to api
  session_token, 
  lang: 'en',
  action: [
    'photo_id_front', // request photo ID picture
    '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

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;

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

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

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

  • if the getUserMedia() function hangs, you can manage the SDK behavior using the following parameters (since 1.7.15):

    • get_user_media_promise_timeout_ms – set the timeout (in ms) after which SDK will throw an error or display an instruction. This parameter is an object with the following keys: "platform_browser", "browser", "platform", "default"(the priority matches the sequence).

    • get_user_media_promise_timeout_throw_error – defines whether, after the time period defined in the parameter above, SDK should call an error (if true) or display a user instruction (if false).