JSDoc: Namespace: Capture

Methods

(static) choosePictureAsBase64(successCallBack, errorCallBack)

Allows picture to be choosen from device photo library/gallery OR from device camera. This method returns selected Image as base64, hence best suited for the usecases where application picks images from gallery and send it for extraction.

Parameters:

Name	Type	Description
`successCallBack`	function	callback with Base64 data of captured or picked image
`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. This method works in manual mode i.e useVideoStream is 'false'.

(static) create(options, successCallBack, errorCallBack)

Creates capture control based on given options.

Parameters:

Name Type Description

options

Object

The options.

Properties

Name Type Attributes Default Description

containerId String ID of an empty element where the camera preview and 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.

preference String String representing the source of the captured document. Acceptable values are 'camera' for capturing with the device's rear camera, or 'gallery' to select an image from the device's photo gallery. On Android devices, a value of 'camera' will require the user to take a photo. On Android and iOS devices, even if a value of 'gallery' is used the user may elect to take a photo instead.

useVideoStream Boolean Boolean value representing either capture with gallery/camera option or auto-capture with guidance messages. Check KfxWebSDK.Utilities.supportsAutoCapture 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 image using the SDK review control.

resolution KfxWebSDK.resolution <optional> RES_FULL_HD This parameter is used to specify the resolution which user want to use in the Advance Capture. Advance capture supports Full HD and 4K resolutions based on the device capabilities. User need to pass RES_FULL_HD for Full HD and RES_4K for 4K resolutions. If user do not specify this parameter then it will use the Full HD resolution. If user pass other than RES_FULL_HD and RES_4K values then error will be thrown. If the device browser supports 4k resolution and user pass RES_4K then 4K resolution will be used in Advance capture. If the device browser does not support 4K resolution and user pass RES_4K then Full HD resolution will be used in Advance capture. If the device browser does not support both resolutions then error will be thrown.

downscaleSize Number <optional> 2 This option will be considered in Mega Pixels. If the captured image size is more than this value then we will downscale the image to the specified size. The valid range is [1-50].

frameAspectRatio

Number

0.629

Aspect ratio of the frame.

Document Type	Recommended Value
Mobile ID	0.629
Check	0.460
Credit Card	0.623
Passport	0.703

framePadding Number <optional> 5 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.

frameCornerHeight Number <optional> 10 Frame corner height.

frameCornerWidth Number <optional> 60 Frame corner width.

frameCornerColor String <optional> '#00FF00' Frame corner color.

outOfFrameTransparency Number <optional> 0.5 Out of frame space transparency,Range 0 - 1, 0 - transparent and visible, 1 - dark.

iconTransparency Number <optional> 0.5 Instruction icon background transparency,Range 0 - 1, 0 - transparent and visible, 1 - dark.

showEdges Boolean <optional> true Draws a border around the document 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.

guidanceOrientation string <optional> PORTRAIT To change the guidance orientation.

useTargetFrameCrop Boolean <optional> false Enable target frame cropping.

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

instructionsAsTextOrientation String <optional> PORTRAIT To change the instructions as text orientation.

instructionsTextColor String <optional> '#FFFFFF' Instructions text color.

instructionsBackgroundColor String <optional> '#000000' Instruction background color.

galleryButtonAccessibilityText String <optional> "Gallery" Screen reader will read this text when voice over or talk back is enabled and user click on gallery button.

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.

tapToDismissInstruction

Object

To configure Tap to Dismiss Instruction options.

Properties

Name	Type	Attributes	Default	Description
`visible`	Boolean	<optional>	true	To maintain the backward compatibility, we are providing showTapToDismissMessage option as well. showTapToDismissMessage option has high priority as compared to this option. We will consider this option when we remove showTapToDismissMessage option.
`text`	String	<optional>	"Tap to Dismiss"	To change the Tap to Dismiss Instruction text.
`accessibilityText`	String	<optional>	"Tap to Dismiss"	Screen reader will read this text when voice over or talk back is enabled and Tap To Dismiss Instruction is displayed on screen. 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.
`orientation`	KfxWebSDK.orientation	<optional>	LANDSCAPE	To change the Tap to Dismiss Instruction orientation.

fitDocumentInstruction

Object

To configure Fit Document Instruction options.

Properties

Name	Type	Attributes	Default	Description
`visible`	Boolean	<optional>	true	Boolean value specifies whether to show the Fit Document Instruction or not. By default is is true means Fit Document Instruction will be displayed. If user want to hide the Fit Document Instruction then pass this value as false.
`text`	String	<optional>	"Fit document in the frame"	To change the Fit Document 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>	"Fit document in the frame"	Screen reader will read this text when voice over or talk back is enabled and Fit Document Instruction is displayed on screen.

zoomInInstruction

Object

To configure Zooom In Instruction options.

Properties

Name	Type	Attributes	Default	Description
`visible`	Boolean	<optional>	true	Boolean value specifies whether to show the Zoom In Instruction or not. By default is is true means Zoom In Instruction will be displayed. If user want to hide the Zoom In Instruction then pass this value as false.
`text`	String	<optional>	"Move closer"	To change the Zoom In 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 Zoom In Instruction is displayed on screen.

zoomOutInstruction

Object

To configure Zoom Out Instruction options.

Properties

Name	Type	Attributes	Default	Description
`visible`	Boolean	<optional>	true	Boolean value specifies whether to show the Zoom Out Instruction or not. By default is is true means Zoom Out Instruction will be displayed. If user want to hide the Zoom Out Instruction then pass this value as false.
`text`	String	<optional>	"Move back"	To change the Zoom Out 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 Zoom Out Instruction is displayed on screen.

centerDocumentInstruction

Object

To configure Center Document Instruction options.

Properties

Name	Type	Attributes	Default	Description
`visible`	Boolean	<optional>	true	Boolean value specifies whether to show the Center Document Instruction or not. By default is is true means Center Document Instruction will be displayed. If user want to hide the Center Document Instruction then pass this value as false.
`text`	String	<optional>	"Center the document"	To change the Center Document 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 the document"	Screen reader will read this text when voice over or talk back is enabled and Center Document Instruction is displayed on screen.

rotateDeviceInstruction

Object

To configure Rotate Device Instruction options.

Properties

Name	Type	Attributes	Default	Description
`visible`	Boolean	<optional>	true	Boolean value specifies whether to show the Rotate Device Instruction or not. By default is is true means Rotate Device Instruction will be displayed. If user want to hide the Rotate Device Instruction then pass this value as false.
`text`	String	<optional>	"Rotate device"	To change the Rotate Device 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>	"Rotate device"	Screen reader will read this text when voice over or talk back is enabled and Rotate Device Instruction is displayed on screen.

holdDeviceLevelInstruction

Object

To configure Hold Device Level Instruction options.

Properties

Name	Type	Attributes	Default	Description
`visible`	Boolean	<optional>	true	Boolean value specifies whether to show the Hold Device Level Instruction or not. By default is is true means Hold Device Level Instruction will be displayed. If user want to hide the Hold Device Level Instruction then pass this value as false.
`text`	String	<optional>	"Hold device level"	To change the Hold Device Level 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 device level"	Screen reader will read this text when voice over or talk back is enabled and Hold Device Level 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.

motionPermissionInstruction

Object

To configure Motion Permission Instruction options

Properties

Name	Type	Attributes	Default	Description
`visible`	Boolean	<optional>	false	When this option is enabled, the user will get instruction to take Device Motion and Orientation access. When this option is disabled, the user will not get Device Motion and Orientation access instruction. Hold Device level instruction will not be displayed when disabling this option. This option only works for iOS platform.
`text`	String	<optional>	"Tap to give device motion and orientation access"	To change the Motion Permission Instruction text. 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>	"Tap to give device motion and orientation access"	Screen reader will read this text when voice over or talk back is enabled and Motion Permission 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. 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.

targetFrameBackground String <optional> "" Use this property to set target Frame Background. Image file to be available in the folder set to "imagesPath" property defined by the KfxWebSDK. By default "imagesPath" folder is not set, then it will search from SDK images folder path.

targetFrameSuccessBackground String <optional> "" Use this property to set Target Frame Background when all constrints fullfilled. Image file to be available in the folder set to "imagesPath" property * defined by the KfxWebSDK. By default "imagesPath" folder is not set, then it will search from SDK images folder path.

enableAutoCapture Boolean <optional> true Boolean value specifies whether to enable the auto capture or not. By disabling auto capture, All instruction messages are not displayed and Force Capture button will be displayed immediately.

enableFlashCapture Boolean <optional> false Used to enable the Flash Capture. When this option is enabled, user will get an additional image captured with Flash enabled. If the device browser doesn't support flash feature then user will not be returned any Flash Image. This option only works with the Android platform.

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.19	The maximum distance the document can be shifted from the target frame. The movement tolerance puts an upper bound on how far a document 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 document bounds.
`maxFillFraction`	Number	<optional>	1.8	The maximum fill area as a fraction of the target frame. The maximum fill fraction puts an upper bound on what is considered an acceptable zoom level. If the area of a detected document is greater then the area of the target frame multiplied by the maximum fill fraction, guidance will suggest zooming out from the document.
`minFillFraction`	Number	<optional>	0.65	The minimum fill area as a fraction of the target frame. The minimum fill fraction puts a lower bound on what is considered an acceptable zoom level. If the area of a detected document is less then the area of the target frame multiplied by the minimum fill fraction, guidance will suggest zooming in on the document.
`longAxisThreshold`	Number	<optional>	85	This property is a percent value. The valid range is [0 - 100]. When page detection is enabled, this property specifies the minimum size of the page that spans the long side of the frame. If the page is smaller than the threshold, it will not be captured. The value 0 will disable page long axis threshold check. The default value is 85. Because page detection requires some margin around a page to properly detect it, the useful upper limit of this property is around 90%.
`shortAxisThreshold`	Number	<optional>	60	This property is a percent value. The valid range is [0 - 100]. When page detection is enabled, this property specifies the minimum size of the page that spans the short side of the frame. If the page is smaller than the threshold, it will not be captured. The value 0 will disable page short axis threshold check. The default value is 60. Because page detection requires some margin around a page to properly detect it, the useful upper limit of this property is around 90%. However to detect a document with a magnetic stripe (back side of driver licenses) the useful limit should not be higher 60%.
`turnSkewAngleTolerance`	Number	<optional>	10	The maximum angle the document can be rotated off from the target frame. The skew angle tolerance puts an upper bound on how far a document can be rotated clockwise or counter-clockwise relative to the target frame and still be considered acceptable. Angles of rotation greater than the tolerance will result in guidance to turn the document. The default value is 10, specified in degrees. Valid values are in the range [0, 90]. A value of 90 disables rotation guidance.
`pitchThreshold`	Number	<optional>	15	The pitch threshold value which needs to be met before taking a picture. Valid values are in the range [0, 45]. The default value is 15. A value of 45 disables level checking for pitch.
`rollThreshold`	Number	<optional>	15	The roll threshold value which needs to be met before taking a picture. Valid values are in the range [0, 45]. The default value is 15. A value of 45 disables level checking for roll.

lookAndFeel

Object

The look and feel options.

Properties

Name	Type	Attributes	Default	Description
`documentSample`	Boolean \| String	<optional>	The url to the default document sample image	The URL to an image of the document sample. If the given documentSample is false or an empty string, then the sample will not be shown.
`showTapToDismissMessage`	Boolean	<optional>	true	Used to show or hide the Tap To Dismiss Message. When this option is enabled, Tap To Dismiss message will be shown. When this option is disabled, Tap To Dismiss message will not be shown.
`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.
`documentSampleTimeout`	Number	<optional>	6	This value in seconds specifies how long document sample has to be shown. Default value is 6 sec. If the value is less than 1 the default value will be considered.
`gallery`	Boolean	<optional>	true	This value specifies whether to show the gallery button.

acceptButton

Object

By using these options we can customize the Review Control accept button when preview is set to true options.preview

Properties

Name	Type	Attributes	Default	Description
`text`	String	<optional>	"Accept"	By using this we can configure the Review Control accept button text when preview is set to true options.preview.

retakeButton

Object

By using these options we can customize the Review Control retake button when preview is set to true options.preview.

Properties

Name	Type	Attributes	Default	Description
`text`	String	<optional>	"Retake"	By using this we can configure the Review Control retake button text when preview is set to true options.preview.

nextButton

Object

By using these options we can customize the Review Control next button when preview is set to true options.preview.

Properties

Name	Type	Attributes	Default	Description
`text`	String	<optional>	"Next"	By using this we can configure the Review Control next button text when preview is set to true options.preview.

successCallBack function empty callback indicating API call is successful

errorCallBack function callback with error message to be invoked when something goes wrong

Deprecated:

showTapToDismissMessage option is deprecated, use tapToDismissInstruction.visible option instead. We will remove this option in the next major release. This option has the high priority as compared to tapToDismissInstruction.visible.

See:

KfxWebSDK.Utilities.supportsAutoCapture

Example

var options = {
    containerId: 'divId',
    preference: 'camera',
    useVideoStream: true,
    preview: false,
    frameAspectRatio: 0.629,
    framePadding: 5,
	   resolution: KfxWebSDK.resolution.RES_FULL_HD,
	   downscaleSize: 2,
    frameCornerHeight: 10,
    frameCornerWidth: 60,
    frameCornerColor: '#00FF00',
    outOfFrameTransparency: 0.5,
    iconTransparency: 0.5,
    showEdges: false,
    edgesColor: '#FFFF00',
    edgesWidth: 4,
    guidanceSize: 150,
	   guidanceOrientation: KfxWebSDK.orientation.PORTRAIT,
    useTargetFrameCrop: false,
    drawInstructionsAsText: false,
	   instructionsAsTextOrientation: KfxWebSDK.orientation.PORTRAIT,
    instructionsTextColor: '#FFFFFF',
    instructionsBackgroundColor: '#000000',
    galleryButtonAccessibilityText: "Gallery",
    forceCaptureButtonAccessibilityText: "Force capture",
    tapToDismissInstruction: {
         visible: true,
         text: "Tap to Dismiss"
         accessibilityText: "Tap to Dismiss"
			orientation: KfxWebSDK.orientation.LANDSCAPE	
    },
    fitDocumentInstruction: {
         visible: true,
         text: "Fit document in the frame",
         accessibilityText: "Fit document in the frame"
    },
    zoomInInstruction: {
         visible: true,
         text: "Move closer",
         accessibilityText: "Move Closer"
    },
    zoomOutInstruction: {
         visible: true,
         text: "Move back",
         accessibilityText: "Move back"
    },
    centerDocumentInstruction: {
         visible: true,
         text: "Center the document",
         accessibilityText: "Center the document"
    },
    rotateDeviceInstruction: {
         visible: true,
         text: "Rotate device",
         accessibilityText: "Rotate device"
    },
    holdDeviceLevelInstruction: {
         visible: true,
         text: "Hold device level",
         accessibilityText: "Hold device level"
    },
    holdSteadyInstruction: {
         visible: true,
         text: "Hold steady",
         accessibilityText: "Hold steady"
    },
    doneInstruction: {
         visible: true,
         text: "Done",
         accessibilityText: "Done"
    },
    motionPermissionInstruction: {
         visible: false,
         text: "Tap to give device motion and orientation access",
         accessibilityText: "Tap to give device motion and orientation access"
    },
    capturePauseInstruction: {
         visible: true,
         text: "Capture is Paused. Tap to Continue.",
         accessibilityText: "Capture is Paused. Tap to Continue."
    }
    targetFrameBackground: "",
    targetFrameSuccessBackground: "",
    enableAutoCapture: true,
    enableFlashCapture: false,
    criteria: {
        minFillFraction: 0.65,
        maxFillFraction: 1.8,
        longAxisThreshold: 85,
        shortAxisThreshold: 60,
        centerToleranceFraction: 0.19,
        captureTimeout: 1700,
        turnSkewAngleTolerance: 10,
        pitchThreshold: 15,
        rollThreshold: 15
    },
    lookAndFeel: {
        documentSample: 'http://example.com/images/document_sample.jpg',
		   showTapToDismissMessage: true,
        forceCapture: 10,
        documentSampleTimeout: 6,
        gallery: true
    },
    acceptButton: { 
       text: "Accept" 
    },
    retakeButton: { 
       text: "Retake" 
    },
    nextButton: { 
       text: "Next" 
    }
};

(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) forceTakePicture(successCallBack, errorCallBack)

Captures document by ignoring capture criteria.

Parameters:

Name	Type	Description
`successCallBack`	function	callback contains captured image data as the first argument and flash image data as the second argument. If user enables enableFlashCapture option, flash image data will be returned. Otherwise only captured image data is returned.
`errorCallBack`	function	callback with error message to be invoked when something goes wrong

(static) getDefaultOptions(successCallBack, errorCallBack)

Returns default capture control options.

Parameters:

Name	Type	Description
`successCallBack`	function	callback with JSON object representing capture control options
`errorCallBack`	function	callback with error message to be invoked when something goes wrong

(static) getOptions(successCallBack, errorCallBack)

Returns current capture control options.

Parameters:

Name	Type	Description
`successCallBack`	function	callback with JSON object representing capture control options
`errorCallBack`	function	callback with error message to be invoked when something goes wrong

(static) setOptions(options, successCallBack, errorCallBack)

Sets capture control options.

Parameters:

Name Type Description

options

Object

The options.

Properties

Name Type Attributes Default Description

frameAspectRatio

Number

0.629

Aspect ratio of the frame.

Document Type	Recommended Value
Mobile ID	0.629
Check	0.460
Credit Card	0.623
Passport	0.703