Configuration Options

The SDK accepts a configuration object during initialization with the following options:

Core Settings

Option	Type	Default	Description
lensFlavor	string	Required	Determines scanning experience type: - 'document': Receipts & Invoices scanning - 'long_document': Long Receipts scanning - 'credit_card': Credit card scanning - 'checks': Check scanning (front/back) - 'upload': File upload only
container	string	undefined	HTML element ID where lens will mount. Creates full-screen overlay if not specified
debug_mode	boolean	false	Enables debug logging to console

Document Processing

Option	Type	Default	Description
detectScreenCapture	boolean	false	Enables detection of screen capture attempts
enforceBothSides	boolean	false	Enforces capture of both sides of documents
enforceAndSkipBothSides	boolean	false	Enforces both sides capture but skips the dialog
delayBetweenCaptures	number	0	Delay in milliseconds between front and back capture
enforceDocumentDetection	boolean	false	Forces document detection validation
enforceBlurDetection	boolean	false	Forces blur detection validation

UI Elements

Option	Type	Default	Description
torchButton	boolean	false	Adds flashlight toggle button (requires device support)
exitButton	boolean	false	Adds button to close camera view
blurModal	boolean	false	Shows warning when blur detected
isDocumentModal	boolean	false	Shows warning when no document detected
enableSubmit	boolean	true	Shows submit button after successful capture
capCircleRadius	number	0.7	Default circle radius for bottle cap overlay
rectWidth	number	0.7	Default width for code strip overlay
rectHeight	number	0.08	Default height for code strip overlay

Special Features

Option	Type	Default	Description
captureBackOfCheck	boolean	false	Enables back side capture for checks (requires lensFlavor: 'checks')
enableLongReceiptPreview	boolean	false	Shows preview during receipt stitching (requires lensFlavor: 'long_document')

Check Processing

Option	Type	Default	Description
checksEnableManualMode	boolean	true	Enable/disable manual capture mode for checks when aspect ratio falls outside acceptable limits (requires lensFlavor: 'checks')
checksManualModeTimeout	number	3000	Timeout in milliseconds before switching to manual mode (requires lensFlavor: 'checks')
checksMaxAspectRatio	number	2.61	Maximum acceptable aspect ratio for check detection (requires lensFlavor: 'checks')
checksMinAspectRatio	number	2.61	Minimum acceptable aspect ratio for check detection (requires lensFlavor: 'checks')
persistManualModeOnRetake	boolean	true	Persist manual mode when retaking front side or capturing back side (requires lensFlavor: 'checks')
forceLandscapeCheckPreview	boolean	false	Force horizontal/landscape orientation for check previews (requires lensFlavor: 'checks')

Crop Settings

Option	Type	Default	Description
cropMargin	number	0.0	Margin around greenbox during cropping for all document types as percentage (0.0-1.0)
checksCropMargin	number	0.1	Margin around greenbox during cropping for checks as percentage (0.0-1.0, requires lensFlavor: 'checks')
cropLayoutAspectRatio	number	undefined	Custom aspect ratio for the manual mode crop layout guide overlay

Crop Layout Overlay

Option	Type	Default	Description
cropLayoutBorderColor	string	"#54C08B"	Border color of the manual mode guide rectangle
cropLayoutStroke	number	2	Border width in pixels of the manual mode guide rectangle
cropLayoutOverlayAlpha	number	0.6	Transparency of the manual mode guide overlay (0-1)
cropLayoutCornerRadius	number	0	Corner radius in pixels of the manual mode guide rectangle

Checks Manual Mode Crop Layout Position & Size

Option	Type	Default	Description
cropLayoutGuideTopPosition	string	"40%"	Vertical position of the crop guide (CSS value, e.g., "40%", "200px")
cropLayoutGuideLeftPosition	string	"50%"	Horizontal position of the crop guide (CSS value, e.g., "50%", "100px")
cropLayoutGuideWidthScale	number	0.90	Width scale of guide relative to video width (0-1, where 0.90 = 90%)
cropLayoutGuideMaxHeightScale	number	0.70	Maximum height scale of guide relative to video height (0-1, where 0.70 = 70%)

Checks Manual Mode Crop Layout Tip Text Styling

Option	Type	Default	Description
cropLayoutTipPosition	string	"right"	Position of tip text relative to guide. Options: "top", "bottom", "left", "right"
cropLayoutTipFontFamily	string	"Arial, sans-serif"	Font family for tip text
cropLayoutTipFontSize	string	"16px"	Font size for tip text (CSS value, e.g., "16px", "1rem")
cropLayoutTipFontWeight	string	"bold"	Font weight for tip text
cropLayoutTipColor	string	"white"	Color for tip text
cropLayoutTipTextShadow	string	"0 1px 2px rgba(0,0,0,0.8)"	Text shadow for tip text (CSS text-shadow value)
cropLayoutTipOffset	string	"35%"	Offset distance of tip text from guide edge (CSS value)

Text Customization

Option	Type	Default	Description
documentModalMessage	string	'Oops, There appears to be no document on your image'	Custom message for document detection modal
blurModalMessage	string	'Oops, The image is too blurry to process'	Custom message for blur detection modal
submitButtonText	string	'Submit Anyway'	Custom text for submit button
retakeButtonText	string	'Retake a picture'	Custom text for retake button
cropButtonText	string	'Crop'	Custom text for crop button
resetButtonText	string	'Reset'	Custom text for reset button
dropZoneText	string	'Click or drag and drop to upload an image'	Custom text for upload drop zone (requires lensFlavor: 'upload')
checkEnforcedModalMessage	string	'Please flip the check and capture the back side'	Custom message when back check capture is required (requires lensFlavor: 'checks' and enforceBothSides: true)
checkOptionalModalMessage	string	'Do you want to capture the back side of the check?'	Custom message when back check capture is optional (requires lensFlavor: 'checks' and captureBackOfCheck: true)
checkContinueButtonText	string	'Continue'	Custom text for check continue button (requires lensFlavor: 'checks' and enforceBothSides: true)
checkYesButtonText	string	'Yes'	Custom text for check confirmation button (requires lensFlavor: 'checks')
checkNoButtonText	string	'No'	Custom text for check rejection button (requires lensFlavor: 'checks')
bottleCapText	string	'Position bottle cap in circle'	Default instruction text for bottle cap overlay
codeStripsText	string	'Position code strip in rectangle'	Default instruction text for code strip overlay
cropLayoutTipMessage	string	undefined	Instructional text shown with the crop layout overlay in manual mode

Navigation & Callbacks

Option	Type	Default	Description
onCloseRedirectUrl	string	undefined	URL to redirect to when exit pressed
onClose	function	undefined	Callback when camera view closes: (isVisible: boolean) => void

Usage Examples

Document Scanning

await VeryfiLens.init("YOUR_CLIENT_ID", {
    lensFlavor: "document",
    statusIndicator: true,
    torchButton: true,
    exitButton: true,
    debug_mode: true,
    documentModalMessage: "Please ensure a document is visible in the frame",
    blurModalMessage: "Image is too blurry, please try again",
    submitButtonText: "Process Document",
    retakeButtonText: "Capture Again"
});

Check Scanning with Manual Mode

await VeryfiLens.init("YOUR_CLIENT_ID", {
    lensFlavor: "checks",
    captureBackOfCheck: true,
    enforceBothSides: true,
    checksEnableManualMode: true,
    checksManualModeTimeout: 3000,
    checksMaxAspectRatio: 2.7,
    checksMinAspectRatio: 1.8,
    checksCropMargin: 0.1,
    persistManualModeOnRetake: true,
    forceLandscapeCheckPreview: false,
    // Checks manual mode crop layout overlay styling
    cropLayoutBorderColor: "#54C08B",
    cropLayoutStroke: 2,
    cropLayoutOverlayAlpha: 0.6,
    cropLayoutCornerRadius: 0,
    // Checks manual mode crop layout positioning
    cropLayoutGuideTopPosition: "40%",
    cropLayoutGuideLeftPosition: "50%",
    cropLayoutGuideWidthScale: 0.90,
    cropLayoutGuideMaxHeightScale: 0.70,
    // Checks manual mode crop layout tip text
    cropLayoutTipMessage: "Align check within the guide",
    cropLayoutTipPosition: "bottom",
    cropLayoutTipFontSize: "18px",
    cropLayoutTipColor: "white",
    torchButton: true,
    exitButton: true
});

Dynamic Configuration

You can update configuration during runtime:

info

All settings except lensFlavor and container can be updated during runtime.

VeryfiLens.configureLens({
    blurModal: false,
    torchButton: false
});