Namespace: SelfieCapture

KfxWebSDK.SelfieCapture

Methods

(static) create(options, successCallBack, errorCallBack)

Creates selfie capture control based on given options. You can check your device supports selfie capture or not by using supportsSelfieCapture method. If your device supports selfie capture then you should invoke loadModels method ahead of calling this method otherwise it will return an error.
Parameters:
Name Type Description
options Object The options.
Properties
Name Type Attributes Default Description
containerId String ID of an empty element where the selfie camera preview and selfie capture guidance will be displayed. The element must exist, have no child elements, and be a div. Application developer has to properly set size & position of the container. ContainerId will not be required, if browser doesn't support MediaStreamAPI.
videoStream Boolean Boolean value representing either capture with camera option or auto capture with guidance messages. Check KfxWebSDK.Utilities.supportsSelfieCapture API before enabling this option. If the API returns true then only we can enable this option otherwise we will get an error.
preview Boolean <optional>
 false Boolean value representing whether to review the captured selfie using the SDK review control.
frameAspectRatio Number <optional>
 0 Aspect ratio of the frame.
framePadding Number <optional>
 10 Frame padding.
frameThickness Number <optional>
 10 Frame thickness.
frameColor String <optional>
 '#FF0000' Frame color.
outOfFrameTransparency Number <optional>
 1.0 Out of frame space transparency, 0 - transparent and visible, 1 - dark.
outOfFrameColor String <optional>
 '#FFFFFF' Out of frame color.
showEdges Boolean <optional>
 true Draws a border around the face during capture.
edgesColor String <optional>
 '#FFFF00' Bounding rectangle sides color.
edgesWidth Number <optional>
 4 Bounding rectangle sides width.
guidanceSize Number <optional>
 150 Size of guidance circle image.
guidanceTransparency Number <optional>
 0.5 Guidance message transparency, 0 - transparent and visible, 1 - dark.
enableAutoCapture Boolean <optional>
 true Used to enable the Auto Capture. When this option is enabled, user will get Blink Slowly instruction. Once the blink is detected then auto capture will happen. When this option is disabled, user has to tap on capture experience to capture selfie.
enableBlinkDetection Boolean <optional>
 true Used to enable the Blink Detection. When this option is enabled, user will get Blink Slowly instruction. Once the blink is detected then auto capture will happen. When this option is disabled, liveliness is not verified. Auto capture will happen once the face is detected. This option is applicable only when enableAutoCapture option is enabled. If enableAutoCapture is disabled then there will be no effect of this setting.
criteria Object The criteria options.
Properties
Name Type Attributes Default Description
captureTimeout Number <optional>
 1700 The amount of time the user must hold the device steady once the 'Hold Steady' guidance appears, after which point an image is captured. If any other guidance prompt appears during this time, no image is captured until the 'Hold Steady' guidance appears again and the device remains held steady. The duration value is in milliseconds.
centerToleranceFraction Number <optional>
 0.15 The maximum distance the face can be shifted from the target frame. The movement tolerance puts an upper bound on how far a face can be shifted from the target frame and still be considered acceptable. The tolerance is specified as a fraction of the target size, and the comparison is made between the center of the target frame and the center of the detected face bounds.
minFaceSize Number <optional>
 0.50 Number value in percentage specifies the percentage of face fits with in the target frame. Valid values are in the range [0, 1]. The default value is 0.5. If number value is negative then it will take detault value. If value is > 0.7 then there will be a difficulty in capturing selfie. If auto capture is disabled then this criteria won't applicable.
lookAndFeel Object The look and feel options.
Properties
Name Type Attributes Default Description
forceCapture Boolean | Number <optional>
 10 Boolean value specifies whether to show the force capture button. Number value in seconds specifies when to show the force capture button. If any number is set, then the button will be shown. If number value is negative or zero the button will be shown immediately. Setting boolean true is equivalent to setting number 0 value. If auto capture is disabled then Force capture button won't be displayed.
successCallBack function empty callback indicating API call is successful
errorCallBack function callback with error message to be invoked when something goes wrong
See:
Example
var options = {
    containerId: 'divId',
    videoStream: true,
    preview: false,
    frameAspectRatio: 0,
    framePadding: 10,
    frameThickness: 10,
    frameColor: '#FF0000',
    outOfFrameColor: '#FFFFFF',
    outOfFrameTransparency: 1.0,
    guidanceTransparency: 0.5,
    enableAutoCapture: true,
	   enableBlinkDetection: true,
    guidanceSize: 150,
    showEdges: false,
    edgesColor: '#FFFF00',
    edgesWidth: 4,
    criteria: {
        minFaceSize: 0.50,
        captureTimeout: 1700,
        centerToleranceFraction: 0.15
    },
    lookAndFeel: {
        forceCapture: 10
    }
};

(static) destroy(successCallBack, errorCallBack)

Releases internal allocated resources The destroy method must be called prior to calling create multiple times.
Parameters:
Name Type Description
successCallBack function callback with no data
errorCallBack function callback with error message to be invoked when something goes wrong

(static) forceTakeSelfie(successCallBack, errorCallBack)

When auto capture is disabled, this API won't work as expected. When auto capture is enabled, this API is used to capture document by ignoring capture criteria.
Parameters:
Name Type Description
successCallBack function This function returns captured selfie ImageData as parameter.
errorCallBack function callback with error message to be invoked when something goes wrong

(static) getDefaultOptions(successCallBack, errorCallBack)

Returns default selfie capture control options.
Parameters:
Name Type Description
successCallBack function callback with JSON object representing default selfie capture control options
errorCallBack function callback with error message to be invoked when something goes wrong

(static) getOptions(successCallBack, errorCallBack)

Returns current selfie capture control options.
Parameters:
Name Type Description
successCallBack function callback with JSON object representing selfie capture control options
errorCallBack function callback with error message to be invoked when something goes wrong

(static) loadModels(loadOpenCVAsWebAssemblyopt, successCallBack, errorCallBack)

This method loads the required model files for opencv to detect face and eyes respectively. In our case, we are using haarcascade_eye and lbpcascade_frontalface xmls. One should invoke this method ahead of launching selfie capture
Parameters:
Name Type Attributes Default Description
loadOpenCVAsWebAssembly Boolean <optional>
 false OpenCV can be used in 2 ways to load selfie models. 1) Use OpenCV as JavaScript 2) Use OpenCV as WebAssembly. By default, OpenCV will be loaded as JavaScript. User can set ‘loadOpenCVAsWebAssembly’ as true to use OpenCV as WebAssembly. By using WebAssembly, user can experience better performance because code can be executed at near-native speed across different platforms by taking advantage of common hardware capabilities. To use OpenCV as WebAssembly, you have to add "application/wasm" MIME Type in your web server where you are going to host your app.
successCallBack function callback with no data
errorCallBack function callback with error message to be invoked when something goes wrong

(static) setOptions(options, successCallBack, errorCallBack)

Sets selfie capture control options.
Parameters:
Name Type Description
options Object The options.
Properties
Name Type Attributes Default Description
frameAspectRatio Number <optional>
 0 Aspect ratio of the frame.
framePadding Number <optional>
 10 Frame padding. The padding has priority over frame corners, i.e. if padding zero value is set, then there is no space for frame corners left and they will not be shown.
frameThickness Number <optional>
 10 Frame thickness.
frameColor String <optional>
 '#FF0000' Frame color.
outOfFrameTransparency Number <optional>
 1.0 Out of frame space transparency, 0 - transparent and visible, 1 - dark.
outOfFrameColor String <optional>
 '#FFFFFF' Out of frame color.
showEdges Boolean <optional>
 true Draws a border around the face during capture.
edgesColor String <optional>
 '#FFFF00' Bounding rectangle sides color.
edgesWidth Number <optional>
 4 Bounding rectangle sides width.
guidanceSize Number <optional>
 150 Size of guidance circle image.
guidanceTransparency Number <optional>
 0.5 Guidance message transparency, 0 - transparent and visible, 1 - dark.
enableAutoCapture Boolean <optional>
 true Used to enable the Auto Capture. When this option is enabled, user will get Blink Slowly instruction. Once the blink is detected then auto capture will happen. When this option is disabled, user has to tap on capture experience to capture selfie.
enableBlinkDetection Boolean <optional>
 true Used to enable the Blink Detection. When this option is enabled, user will get Blink Slowly instruction. Once the blink is detected then auto capture will happen. When this option is disabled, liveliness is not verified. Auto capture will happen once the face is detected. This option is applicable only when enableAutoCapture option is enabled. If enableAutoCapture is disabled then there will be no effect of this setting.
criteria Object The criteria options.
Properties
Name Type Attributes Default Description
captureTimeout Number <optional>
 1700 The amount of time the user must hold the device steady once the 'Hold Steady' guidance appears, after which point an image is captured. If any other guidance prompt appears during this time, no image is captured until the 'Hold Steady' guidance appears again and the device remains held steady. The duration value is in milliseconds.
centerToleranceFraction Number <optional>
 0.15 The maximum distance the face can be shifted from the target frame. The movement tolerance puts an upper bound on how far a face can be shifted from the target frame and still be considered acceptable. The tolerance is specified as a fraction of the target size, and the comparison is made between the center of the target frame and the center of the detected face bounds.
minFaceSize Number <optional>
 0.50 Number value in percentage specifies the percentage of face fits with in the target frame Valid values are in the range [0, 1]. The default value is 0.5. If number value is negative then it will take detault value.
lookAndFeel Object The look and feel options.
Properties
Name Type Attributes Default Description
forceCapture Boolean | Number <optional>
 10 Boolean value specifies whether to show the force capture button. Number value in seconds specifies when to show the force capture button. If any number is set, then the button will be shown. If number value is negative or zero the button will be shown immediately. Setting boolean true is equivalent to setting number 0 value. If auto capture is disabled then Force capture button won't be displayed.
successCallBack function empty callback indicating API call is successful
errorCallBack function callback with error message to be invoked when something goes wrong
Example
var options = {
    containerId: 'divId',
    videoStream: true,
    preview: false,
    frameAspectRatio: 0,
    framePadding: 10,
    frameThickness: 10,
    frameColor: '#FF0000',
    outOfFrameColor: '#FFFFFF',
    outOfFrameTransparency: 1.0,
    guidanceTransparency: 0.5,
    enableAutoCapture: true,
	   enableBlinkDetection: true,
    guidanceSize: 150,
    showEdges: false,
    edgesColor: '#FFFF00',
    edgesWidth: 4,
    criteria: {
        minFaceSize: 0.50,
        captureTimeout: 1700,
        centerToleranceFraction: 0.15
    },
    lookAndFeel: {
        forceCapture: 10
    }
};

(static) stopCapture(successCallBack, errorCallBack)

Stops Auto capture.
Parameters:
Name Type Description
successCallBack function callback with no data
errorCallBack function callback with error message to be invoked when something goes wrong

(static) takeSelfie(successCallBack, errorCallBack)

Starts Auto capture process.
Parameters:
Name Type Description
successCallBack function When auto capture is enabled, this function returns captured selfie ImageData as parameter. When auto capture is disabled, this function returns close selfie ImageData and far selfie ImageData as parameters. When auto capture is disabled, to check the liveliness we have to send the close selfie and far selfie images to the server.
errorCallBack function callback with error message to be invoked when something goes wrong
See:
  • It is recommended to call/bind this method in some button click events instead of jquery page events or window load events to get full support from most of the browsers.