JSDoc: Namespace: 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,Range 0 - 1, 0 - transparent and visible, 1 - dark.

outOfFrameColor String <optional> '#FFFFFF' Out of frame color.

instructionsBackgroundColor String <optional> '#000000' Instruction background 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, Range 0 - 1, 0 - transparent and visible, 1 - dark.

drawInstructionsAsText Boolean <optional> false Enable this option to show instructions as text. Disable this option to show instructions as images.

instructionsTextColor String <optional> '#FFFFFF' Instructions text color. This option is applicable when drawInstructionsAsText is enabled.

forceCaptureButtonAccessibilityText String <optional> "Force capture" Screen reader will read this text when voice over or talk back is enabled and user click on force capture button.

centerFaceInstruction

Object

To configure Center Face Instruction options.

Properties

Name	Type	Attributes	Default	Description
`visible`	Boolean	<optional>	true	Boolean value specifies whether to show the Center Face Instruction or not. By default is is true means Center Face Instruction will be displayed. If user want to hide the Center Face Instruction then pass this value as false.
`text`	String	<optional>	"Center face"	To change the Center Face Instruction text. This text is used when user enables drawInstructionsAsText option. The maximum length of the string is 60 characters. If user set more than 60 characters then SDK will trim the string to 60 characters and display it on screen.
`accessibilityText`	String	<optional>	"Center face"	Screen reader will read this text when voice over or talk back is enabled and Center Face Instruction is displayed on screen.

moveCloserInstruction

Object

To configure Move Closer Instruction options.

Properties

Name	Type	Attributes	Default	Description
`visible`	Boolean	<optional>	true	Boolean value specifies whether to show the Move Closer Instruction or not. By default is is true means Move Closer Instruction will be displayed. If user want to hide the Move Closer Instruction then pass this value as false.
`text`	String	<optional>	"Move closer"	To change the Move Closer Instruction text. This text is used when user enables drawInstructionsAsText option. The maximum length of the string is 60 characters. If user set more than 60 characters then SDK will trim the string to 60 characters and display it on screen.
`accessibilityText`	String	<optional>	"Move closer"	Screen reader will read this text when voice over or talk back is enabled and Move Closer Instruction is displayed on screen.

moveBackInstruction

Object

To configure Move Back Instruction options.

Properties

Name	Type	Attributes	Default	Description
`visible`	Boolean	<optional>	true	Boolean value specifies whether to show the Move Back Instruction or not. By default is is true means Move Back Instruction will be displayed. If user want to hide the Move Back Instruction then pass this value as false.
`text`	String	<optional>	"Move back"	To change the Move Back Instruction text. This text is used when user enables drawInstructionsAsText option. The maximum length of the string is 60 characters. If user set more than 60 characters then SDK will trim the string to 60 characters and display it on screen.
`accessibilityText`	String	<optional>	"Move back"	Screen reader will read this text when voice over or talk back is enabled and Move Back Instruction is displayed on screen.

blinkSlowlyInstruction

Object

To configure Blink Slowly Instruction options.

Properties

Name	Type	Attributes	Default	Description
`visible`	Boolean	<optional>	true	Boolean value specifies whether to show the Blink Slowly Instruction or not. By default is is true means Blink Slowly Instruction will be displayed. If user want to hide the Blink Slowly Instruction then pass this value as false.
`text`	String	<optional>	"Blink slowly"	To change the Blink Slowly Instruction text. This text is used when user enables drawInstructionsAsText option. The maximum length of the string is 30 characters. If user set more than 30 characters then SDK will trim the string to 30 characters and display it on screen.
`accessibilityText`	String	<optional>	"Blink slowly"	Screen reader will read this text when voice over or talk back is enabled and Blink Slowly Instruction is displayed on screen.

tapToCaptureInstruction

Object

To configure Tap To Capture Instruction options.

Properties

Name	Type	Attributes	Default	Description
`visible`	Boolean	<optional>	true	Boolean value specifies whether to show the Tap To Capture Instruction or not. By default is is true means Tap To Capture Instruction will be displayed. If user want to hide the Tap To Capture Instruction then pass this value as false.
`text`	String	<optional>	"Tap to capture"	To change the Tap To Capture Instruction text. This text is used when user enables drawInstructionsAsText option. The maximum length of the string is 30 characters. If user set more than 30 characters then SDK will trim the string to 30 characters and display it on screen.
`accessibilityText`	String	<optional>	"Tap to capture"	Screen reader will read this text when voice over or talk back is enabled and Tap To Capture Instruction is displayed on screen.

holdSteadyInstruction

Object

To configure Hold Steady Instruction options.

Properties

Name	Type	Attributes	Default	Description
`visible`	Boolean	<optional>	true	Boolean value specifies whether to show the Hold Steady Instruction or not. By default is is true means Hold Steady Instruction will be displayed. If user want to hide the Hold Steady Instruction then pass this value as false.
`text`	String	<optional>	"Hold steady"	To change the Hold Steady Instruction text. This text is used when user enables drawInstructionsAsText option. The maximum length of the string is 60 characters. If user set more than 60 characters then SDK will trim the string to 60 characters and display it on screen.
`accessibilityText`	String	<optional>	"Hold steady"	Screen reader will read this text when voice over or talk back is enabled and Hold Steady Instruction is displayed on screen.

doneInstruction

Object

To configure Done Instruction options.

Properties

Name	Type	Attributes	Default	Description
`visible`	Boolean	<optional>	true	Boolean value specifies whether to show the Done Instruction or not. By default is is true means Done Instruction will be displayed. If user want to hide the Done Instruction then pass this value as false.
`text`	String	<optional>	"Done"	To change the Done Instruction text. This text is used when user enables drawInstructionsAsText option. The maximum length of the string is 60 characters. If user set more than 60 characters then SDK will trim the string to 60 characters and display it on screen.
`accessibilityText`	String	<optional>	"Done"	Screen reader will read this text when voice over or talk back is enabled and Done Instruction is displayed on screen.

capturePauseInstruction

Object

To configure Capture Pause Instruction options.

Properties

Name	Type	Attributes	Default	Description
`visible`	Boolean	<optional>	true	Boolean value specifies whether to show the Capture Pause Instruction or not. By default is is true means Capture Pause Instruction will be displayed. If user want to hide the Capture Pause Instruction then pass this value as false.
`text`	String	<optional>	"Capture is paused. Tap to continue."	To change the Capture Pause Instruction text. This text is used when user enables drawInstructionsAsText option. The maximum length of the string is 60 characters. If user set more than 60 characters then SDK will trim the string to 60 characters and display it on screen.
`accessibilityText`	String	<optional>	"Capture is paused. Tap to continue."	Screen reader will read this text when voice over or talk back is enabled and Capture Pause Instruction is displayed on screen.

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',
    instructionsBackgroundColor: '#000000',
    outOfFrameTransparency: 1.0,
    guidanceTransparency: 0.5,
    drawInstructionsAsText: false,
    instructionsTextColor: '#FFFFFF',
    forceCaptureButtonAccessibilityText: "Force capture",
    centerFaceInstruction: {
        visible: true,
        text: "Center face",
        accessibilityText: "Center face"
    },
    moveCloserInstruction: {
        visible: true,
        text: "Move closer",
        accessibilityText: "Move closer"
    },
    moveBackInstruction: {
        visible: true,
        text: "Move back",
        accessibilityText: "Move back"
    },
    blinkSlowlyInstruction: {
        visible: true,
        text: "Blink slowly",
        accessibilityText: "Blink slowly"
    },
    tapToCaptureInstruction: {
        visible: true,
        text: "Tap to capture",
        accessibilityText: "Tap to capture"
    },
    holdSteadyInstruction: {
        visible: true,
        text: "Hold steady",
        accessibilityText: "Hold steady"
    },
    doneInstruction: {
        visible: true,
        text: "Done",
        accessibilityText: "Done"
    },
    capturePauseInstruction: {
        visible: true,
        text: "Capture is Paused. Tap to Continue.",
        accessibilityText: "Capture is Paused. Tap to Continue."
    },
    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, Range 0 - 1, 0 - transparent and visible, 1 - dark.