Development Guide (Document Capture)

This page contains the information of Usage, Configuration, Result of OkayCam for Android, iOS and React-native in Document Capture

Android

Usage

For Android, the Camera can be launched by invoking the start method on OkayCameraActivity with context, license key, config and callback method as follow:

• A License Key is required to start the SDK.

OkayCamDoc.start(this,license_key, config) {
success, images, exception -> 
    // do something with the result 
}

Configuration

• The configuration object is optional if is calling from Kotlin.

• The configuration object can be created and can be customized as the code below:

val config = OkayCamConfig.init(this)
config.topLabel.text = "Top Label"

List of Possible Configurations

This is a complete list of possible configurations that has been provided to the user to make any custom configuration:

-	Property	Description	Default Value
-	crop	crop the frame area	false
-	width	width to resize the image	null
-	torchBtnEnabled	to show torch button. If set to true, it will only be shown if onFlash from captureConfig is set to false.	false
-	imageQuality	quality of the image	1.0f (range from 0 to 1.0)
topLabel	text	text of the top label	" "(empty string)
topLabel	color	color of the top label	#FFFFFF
topLabel	size	text size of the top label	24
bottomLabel	text	text of the bottom label	" "(empty string)
bottomLabel	color	color of the bottom label	#FFFFFF
bottomLabel	size	text size of the bottom label	24
frame	size	size of the camera overlay frame	null
frame	color	color of the camera overlay frame	#FFFFFF
frame	content	content of the camera overlay frame (able to display vector drawable within the frame for guidance)	null (drawable id / file path)
-	showOverlay	transparent black background for camera overlay	true
timer	backgroundColor	background of the count down timer	#662196F3
timer	textColor	text color of the count down timer	#FFFFFF
-	captureBtnColor	color of the capture button	#EB144C
confirmBtnConfig	backgroundColor	background color of the confirm button	#EB144C
confirmBtnConfig	contentColor	content color of the confirm button	#FFFFFF
retakeBtnConfig	backgroundColor	background color of the retake button	#EB144C
retakeBtnConfig	contentColor	content color of the retake button	#FFFFFF
captureConfig	first	config for the first capture delay: countdown before capture onFlash: enable/disable flash onImageQuality: enable/disable image quality check outputPath: desired output image path	SDK Version 2.x.x delay:0s, onFlash:false, onImageQuality:true outputPath: null SDK Version 1.x.x delay:0s, onFlash:false, outputPath: null,
captureConfig	second	config for the second capture delay: countdown before capture onFlash: enable/disable flash onImageQuality: enable/disable image quality check outputPath: desired output image path	SDK Version 2.x.x delay:0s, onFlash:false, onImageQuality:false outputPath: null SDK Version 1.x.x delay:5s, onFlash:false, outputPath: null,
preview	title	ref image on preview screen	""(empty string)
preview	reflmg	ref image on preview screen	null
preview	instruction1	instruction on preview screen	""(empty string)
preview	instruction2	instruction on preview screen	""(empty string)
preview	instruction3	instruction on preview screen	""(empty string)
preview	backgrounColor	background color of preview screen	null
instruction	title	Instruction's title on camera capture screen	""(empty string)
instruction	refImage1	Instruction's reference image 1	null
instruction	refImage2	Instruction's reference image 2	null
	showPreviewInstruction	Show or hide preview instruction for captured photos	false

If there is no value is set for properties, default values will be implied.

Result Callback

• After the image is capture or cancelled by the user, the callback method will be called.

• Result callback has 3 parameters as follow:

Result	Description
Success	It will be true if the image is captured successfully, else it will return false.
Images	If it is successful, images will contain the file path of 2 images in a list of format, else it will return null.
Exception	If it is successful, the exception will be null, else it will contain the exception that occurred during the image capturing.

Base64 Conversion

import com.innov8tif.okaycam.utils.BitmapUtils;

String result = BitmapUtils.INSTANCE.convertToBase64(image);

iOS

Usage

For iOS, it can start by importing the OkayCam module into the swift file.

import OkayCam

Document Capture

• The configuration object must be instantiated and a reference must be passed into the view controller.

let config = OkayCamConfig(viewController: viewController)

The configuration object is initialized with default values.

• Start the process by calling start on OkayCam class. The result can be handle in the completion handler.

OkayCamDoc.start(
    okayCamConfig: config, 
    license: licenseKey,
    { filePaths, error in 
        // handle
    }
}

• The received result will either be a filePath or an error. One will be valid and the other will be NIL.

Configuration

The configuration object will need to be modified as follow:

let config = OkayCamConfig(viewController: nav)
        config.topLabel.text = "top label text"
        config.topLabel.color = .green
        config.topLabel.size = 14
        config.bottomLabel.text = "bottom label text"
        config.bottomLabel.color = .systemPink
        config.bottomLabel.size = 20
        config.frame.size = CGSize(width: 210, height: 150)
        config.frame.color = .orange
        config.frame.content = URL(fileURLWithPath: Bundle.main.path(forResource: "card", ofType: "svg")!)
        config.showOverlay = false
        config.imageQuality = 1.0
        config.timer.backgroundColor = .magenta
        config.timer.textColor = .systemTeal
        config.captureBtnColor - .white
        config.confirmBtnConfig.backgroundColor = .blue
        config.confirmBtnConfig.contentColor = .orange
        config.retakeBtnConfig.backgroundColor = .orange
        config.retakeBtnConfig.contentColor = .blue
        config.torchBtnEnabled = false
        config.captureConfigPair = CaptureConfigPair(
                firstPhoto: OkayCamCaptureConfig(
                        timeOut: 2, 
                        onFlash: false,
                        outputPath: myCustomFilePath
                ),
                secondPhoto: OkayCamCaptureConfig(
                        timeOut: 1,
                        onFlash: false, 
                        outputPath: myCustomFilePath
                )
        )
        config.crop = true
        config.width = 250
        config.imageQuality = 1.0

        let label = OkayCamLabelConfig(text: "Label", color: UIColor.red, size: 14)
        let refImag = URL(fileURLWithPath: Bundle.main.path(forResource: "image", ofType: "svg")!)

        config.preview = OkayCamPreviewConfig(title: label, refImage: refImag, instruction1: label, instruction2: label, instruction3: label, 
                        backgroundColor: UIColor.black)

List of Possible Configurations:

Properties on OkayCamConfig:

Property	Type	Default Value
topLabel	OkayCamLabelConfig	OkayCamLabelConfig(text: "Tap to focus", color: UIColor.white, size: CGFloat(24))
bottomLabel	OkayCamLabelConfig	OkayCamLabelConfig(text: "Please align ID card within frame", color: UIColor.white, size: CGFloat(24))
frame	OkayCamFrameConfig	OkayCamFrameConfig(size: CGSize(width: 210, height: 150), color: .orange, content: URL(fileURLWithPath: Bundle.main.path(forResource: "card", ofType: "svg")!))
showOverlay	Bool	true
timer	OkayCamTimerConfig	OkayCamTimerConfig(backgroundColor: UIColor.black, textColor: UIColor.white)
captureBtnColor	UIColor	UIColor(red: 0.92, green: 0.08, blue: 0.30, alpha: 1.0)
confirmBtnConfig	OkayCamBtnConfig	OkayCamBtnConfig( backgroundColor: UIColor(red: 0.92, green: 0.08, blue: 0.30, alpha: 1.0), contentColor: UIColor.white )
retakeBtnConfig	OkayCamBtnConfig	OkayCamBtnConfig( backgroundColor: UIColor(red: 0.92, green: 0.08, blue: 0.30, alpha: 1.0), contentColor: UIColor.white )
torchBtnEnabled	Bool	false
captureConfigPair	CaptureConfigPair	SDK Version 2.x.x CaptureConfigPair(firstPhoto: OkayCamCaptureConfig(timeOut: 0, onFlash: false, onImageQuality: true, outputPath: MY_CUSTOM_FILE_PATH), secondPhoto: OkayCamCaptureConfig(timeOut: 5, onFlash: true,onImageQuality: false, outputPath: MY_CUSTOM_FILE_PATH)) SDK Version 1.x.x CaptureConfigPair(firstPhoto: OkayCamCaptureConfig(timeOut: 0, onFlash: false, outputPath: MY_CUSTOM_FILE_PATH), secondPhoto: OkayCamCaptureConfig(timeOut: 5, onFlash: true, outputPath: MY_CUSTOM_FILE_PATH))
crop	Bool	false
width	Int	nil
imageQuality	CGFloat	1.0 (range from 0 to 1.0)
preview.title	OkayCamLabelConfig	OkayCamLabelConfig(text: "Title", color: UIColor.white, size: CGFloat(24))
preview.refImg	URL	URL(fileURLWithPath: Bundle.main.path(forResource: "", ofType: "")!)
preview.instruction1	OkayCamLabelConfig	OkayCamLabelConfig(text: "Instruction 1", color: UIColor.white, size: CGFloat(24))
preview.instruction2	OkayCamLabelConfig	OkayCamLabelConfig(text: "Instruction 2", color: UIColor.white, size: CGFloat(24))
preview.instruction3	OkayCamLabelConfig	OkayCamLabelConfig(text: "Instruction 3", color: UIColor.white, size: CGFloat(24))
preview.backgroundColor	UIColor	UIColor.black
instruction.title	OkayCamLabelConfig	OkayCamLabelConfig(text: "Title", color: UIColor.white, size: CGFloat(24))
instruction.refImage1	OkaycamInstructionRefImg	OkaycamInstructionRefImg(title: "", img: URL(fileURLWithPath: Bundle.main.path(forResource: "", ofType: "svg")!))
instruction.refImage2	OkaycamInstructionRefImg	OkaycamInstructionRefImg(title: "", img: URL(fileURLWithPath: Bundle.main.path(forResource: "", ofType: "svg")!))

Result Callback

• After the image is capture or cancelled by the user, the callback method will be called.

• Result callback has 2 parameters as follow:

Result	Description
filepaths	If it is successful, images will contain the file path of 2 images in a list of format, else it will return nil.
error	If it is successful, the error will be nil, else it will contain the error that occurred during the image capturing.

Base64 Conversion

do {
    let base64String = try convertImageToBase64(fileUrl: myImageFilePath)
    print(base64String)
} catch  {
    print(error.localizedDescription)
}

React-Native

Usage

For React-native, this is an example for the document capture for the custom camera UI design as following:

captureDocument(license, base64, config)

To generate base64 string as output, base64 parameter needs to be set as true.

import { captureDocument } from "react-native-okaycam"

captureDocument(
	license,
	{
		topLabel: {
			text: "Align your card within the frame",
			color: "#4287f5",
			size: 20
		},
		bottomLabel: {
			text: "Tap to Focus",
			color: "#4287f5",
			size: 20
		},
        frame: {
            size: {
				width: 1000,
				height: 300,
			},
			color: "#4287f5",
        	content: require('./images/content.svg')
		},
		showOverlay: true,
		timer: {
			backgroundColor: "#4287f5",
			textColor: "#ffffff"
		},
        torchBtnEnabled: true,
        confirmBtnConfig: {
            backgroundColor: "#4287f5",
            contentColor: "#000000"
        },
        retakeBtnConfig: {
            backgroundColor: "#4287f5",
            contentColor: "#000000"
        },
		captureBtnColor: "#4287f5",
		firstPhotoConfig: {
			delay: 0,
			onFlash: false,
			outputPath: null
		},
		secondPhotoConfig: {
			delay: 5,
			onFlash: true,
			outputPath: null
		},
		crop: true,
		width: 2000,
        imageQuality: 1.0,
		preview: {
			title: {text: 'testing', color: '#000000', size: 25},
			refImage: require('./images/ref.png'),
			instruction1: {text: 'instr1', color: '#000000', size: 14},
			instruction2: {text: 'instr2', color: '#000000', size: 14},
			instruction3: {text: 'instr3', color: '#000000', size: 14},
			backgroundColor: '#374fff',
      }
	}
)
	.then(result => {
		console.log(result)
	})
	.catch(error => {
		console.log(error)
	})

Configuration

There are some configurations object to be followed in the development stage. The configurations that are going to show below can be implemented into the Usage section above.

List of Possible Configurations

-	Property	Description	Default Value
-	crop	crop the frame area	false
-	width	width to resize the image	-1
-	torchBtnEnabled	to show torch button. If set to true, it will only be shown if onFlash from captureConfig is set to false.	false
-	imageQuality	quality of image	1.0 (range from 0 to 1.0)
frame	size	size of the frame (width and height)	90% of width and height is scaled proportionally to card size
frame	color	color of the frame	#FFFFFF
frame	content	content of the frame (able to display svg file within the frame for guidance)	null
-	showOverlay	transparent black overlay	true
topLabel	text	text of the top label	"" (empty string)
topLabel	color	color of the top label	#FFFFFF
topLabel	size	text size of the top label	20
bottomLabel	text	text of the bottom label	"" (empty string)
bottomLabel	color	color of the bottom label	#FFFFFF
bottomLabel	size	text size of the bottom label	20
timer	backgroundColor	background of the countdown timer	#FFA500
timer	textColor	text color of the countdown timer	#FFFFFF
-	captureBtnColor	color of the capture button	#FFFFFF
confirmBtnConfig	backgroundColor	background of the confirm button	#EB144C
confirmBtnConfig	contentColor	content color of the confirm button	#FFFFFF
retakeBtnConfig	backgroundColor	background of the retake button	#EB144C
retakeBtnConfig	contentColor	content color of the retake button	#FFFFFF
SDK Version 1.x.x	firstPhotoConfig	config for the first capture	delay:0s,onFlash:false, outputPath: null
SDK Version 1.x.x	secondPhotoConfig	config for the second capture	null
SDK Version 2.x.x	firstPhotoConfig	config for the first capture	delay:0s, onFlash:false, outputPath: null, onImageQuality: true
SDK Version 2.x.x	secondPhotoConfig	config for the second capture	delay:0s, onFlash:false, outputPath: null, onImageQuality: false
preview	title	title on preview screen	""(empty string)
preview	refImg	ref image on preview screen	null
preview	instruction1	instruction on preview screen	""(empty string)
preview	instruction2	instruction on preview screen	""(empty string)
preview	instruction3	instruction on preview screen	""(empty string)
preview	backgroundColor	background color of preview screen	null
instruction	title	Instruction's title on camera capture screen	""(empty string)
instruction	refImage1	Instruction's reference image 1	null
instruction	refImage2	Instruction's reference image 2	null
-	showPreviewInstruction	Show or hide preview instruction for captured photos	false

Result

Result	Description
fullDocumentImage	Result of firstPhotoConfig
fullDocumentImage2	Result of secondPhotoConfig. Will only return if secondPhotoConfig is configured

User Interface Example

The OkayCam contains two different user interface, one will be with flash and another one without flash. The only difference between these two user interfaces is one contains a timer (with flash) and the other one does not contain a timer (without flash) on the screen.

Example 1 (without flash):

Figure above shows the UI design of OkayCam (without flash)

Example 2 (with flash):

Figure above shows the UI design of OkayCam (with flash)

Example 3 (with frame content):

Figure above shows the UI design of OkayCam (with frame content)

OkayCam Demo Preview