> For the complete documentation index, see [llms.txt](https://api2-ekycapis.innov8tif.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api2-ekycapis.innov8tif.com/okaycam-mobile-sdk/okaycam-mobile-sdk-all/development-guide-document-capture/development-guide-document-capture-for-v3.md). # Development Guide (Document Capture) for V3 {% tabs %} {% tab title="Android" %} ### Installation {% hint style="info" %} Requires: Android SDK 30+ {% endhint %} * OkayCam V3 is available through maven central repo. To install it, add following dependency in `app/build.gradle` dependencies block: ``` dependencies { implementation('com.innov8tif.okaycam:OkayCam:3.0.0') { transitive = true } } ``` Also add following repo in project root `build.gradle`: ``` allprojects { repositories { maven { url "https://innov8tif-okaycam.firebaseapp.com" content { includeGroup "com.innov8tif.xendity" } } } } ``` ### License Key The license key is a `string` which you need to request from Innov8tif. In the following usage example, we put as `LICENSE_KEY` but you can use whatever variable name you want. ### Usage - Document Capture #### Starting Camera * Camera can be launched by invoking **start** method on OkayCameraActivity with context,config and callback method as follow * Config object is optional if you call from Kotlin (refer to Configuration for more info) * After the image is captured or the user cancel, the callback method will be called (refer result) ``` OkayCamAutoDoc.start(this, LICENSE_KEY, config) { success, images, exception -> // do something with the result } ``` ### Configuration * Configuration object can be created and can be customized as follow * if no value is set for properties, default values will be implied ``` val config = OkayCamAutoCaptureConfig.init() config.width = 1080 ``` #### List of Possible Configurations The complete list of possible configurations can be found in the following table | width | width to resize the image | 2000 | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---- | | imageQuality | quality of cropped image | 1.0f | | autoCapture |

When set to true, the system will automatically capture the document once it is properly detected and aligned.

When set to false, the user must manually trigger the capture instead.

| true | | FULL | Captures front of document, front of document with flash, and back of document automatically. This is the default mode for complete document capture. | ✅ | | FRONT\_ONLY | Captures only the front of document. | ❌ | | FRONT\_BACK | Captures both front and back of document automatically without flash. | ❌ | | FRONT\_WITH\_FLASH | aptures the front of document with flash enabled | ❌ | ### Result * Result callback has 3 parameters as follow:
ResultDescription
ResultDescription
SuccessIt will be true if the image is captured successfully, else it will return false.
ImagesIf it is successful, images will contain the file path of 2 images in a list of format, else it will return null.
ExceptionIf it is successful, the exception will be null, else it will contain the exception that occurred during the image capturing.
{% endtab %} {% tab title="iOS" %} {% hint style="info" %} Requires iOS 9+ and Swift 5 {% endhint %} ### Installation OkayCam is available through [CocoaPods](https://cocoapods.org). To install it, add the following to your app target in your podfile: ```swift use_frameworks! pod 'OkayCam' post_install do |installer| installer.pods_project.targets.each do |target| if target.name == "CryptoSwift" puts "Enable module stability for CryptoSwift" target.build_configurations.each do |config| config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES' end end end ``` You will need to add `NSCameraUsageDescription` to your `info.plist` for camera permissions. ### Usage Start by importing `OkayCam` module into your swift file. ```swift import OkayCam ``` #### Document Capture 1. Instantiate the configuration object. You must pass a reference to your navigation controller. ```swift let config = OkayCamConfig(navigationController: nav) ``` The configuration object is initialized with default values. 2. Start the process by calling `start` on `OkayCamDoc` class. You can handle the result in the completion handler. ```swift OkayCamDoc.start( okayCamConfig: config, license: yourLicense, { filePaths, error in // handle } ) ``` You will only either receive `filePaths` or an `error`. One will be valid and the other will be `nil`. #### Configuration Modifying the configuration object: ```swift let config = OkayCamConfig(navigationController: 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.color = .blue config.frame.size = CGSize(width: 230, height: 100) config.frame.content = URL(fileURLWithPath: Bundle.main.path(forResource: "image", ofType: "svg")!) config.showOverlay = false config.timer.backgroundColor = .magenta config.timer.textColor = .systemTeal config.captureBtnColor = .white config.torchBtnEnabled = false config.confirmBtnConfig.backgroundColor = .blue config.confirmBtnConfig.contentColor = .black config.retakeBtnConfig.backgroundColor = .orange config.retakeBtnConfig.contentColor = .black config.captureConfigPair = CaptureConfigPair( firstPhoto: OkayCamCaptureConfig( timeOut: 2, onFlash: false, onImageQuality: false, // Required for SDK >= 2.0.0 outputPath: myCustomFilePath ), secondPhoto: OkayCamCaptureConfig( timeOut: 1, onFlash: false, onImageQuality: false, // Required for SDK >= 2.0.0 outputPath: myCustomFilePath ) ) config.crop = true config.width = 250 config.imageQuality = 1.0 ``` Properties on `OkayCamConfig` | Property | Default | Type | | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | | topLabel | `OkayCamLabelConfig(text: "Tap to focus", color: UIColor.white, size: CGFloat(24))` | OkayCamLabelConfig | | bottomLabel | `OkayCamLabelConfig(text: "Please align ID card within frame", color: UIColor.white, size: CGFloat(24))` | OkayCamLabelConfig | | frame | OkayCamFrameConfig(size: nil, color: .white, content: nil) | OkayCamFrameConfig | | showOverlay | true | Bool | | timer | OkayCamTimerConfig(backgroundColor: UIColor.black, textColor: UIColor.white) | OkayCamTimerConfig | | captureBtnColor | UIColor(red: 0.92, green: 0.08, blue: 0.30, alpha: 1.0) | UIColor | | torchBtnEnabled | false | Bool | | confirmBtnConfig | OkayCamBtnConfig(backgroundColor: UIColor(red: 0.92, green: 0.08, blue: 0.30, alpha: 1.0), contentColor: UIColor.white) | OkayCamBtnConfig | | retakeBtnConfig | OkayCamBtnConfig(backgroundColor: UIColor(red: 0.92, green: 0.08, blue: 0.30, alpha: 1.0), contentColor: UIColor.white) | OkayCamBtnConfig | |

SDK version 1.1.13 <= or SDK version 1.1.15 >=

captureConfigPair

| CaptureConfigPair(firstPhoto: OkayCamCaptureConfig(timeOut: 0, onFlash: false, outputPath: nil), secondPhoto: nil) | CaptureConfigPair | |

New SDK version 2.0.0 >=

captureConfigPair

| **New** `CaptureConfigPair(firstPhoto: OkayCamCaptureConfig(timeOut: 0, onFlash: false, onImageQuality: false, outputPath: nil), secondPhoto: nil)` | CaptureConfigPair | | crop | false | Bool | | width | nil | Int? | | imageQuality | `1.0 (range 0 - 1.0)` | CGFloat | | frameSize | nil | CGSize? | *** #### Document Autocapture 1. Instantiate the configuration object. You must pass a reference to your navigation controller. ```swift let config = OkayCamAutoCaptureConfig(viewController: nav) ``` The configuration object is initialized with default values. 2. 2- Start the process by calling `start` on `OkayCamAutoDoc` class. You can handle the result in the completion handler. ```swift OkayCamAutoDoc.start( okayCamConfig: config, license: yourLicense, { filePaths, error in // handle } ) ``` ### Configuration **Using Auto Capture** No additional parameters need to be configured. The SDK will automatically manage: * Detection * Capture timing * Validation * Image processing **Usage Example:** ```swift let config = OkayCamAutoCaptureConfig(viewController: nav) // Choose capture mode: full, frontOnly, frontBack, frontWithFlash config.mode = .full // Default config.width = 2000 // Default config.autoCapture = true // Default ``` Properties on `OkayCamAutoCaptureConfig` for AutoCapture: ### OkayCam Auto Capture Configuration | Property | Default | Type | Description | | ------------ | ------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | mode | full | OkayCamAutoCaptureMode |

Defines which sides of the document to capture:
• full – front, front with flash, and back automatically (default).
• frontOnly – only front.
• frontBack – front and back without flash.
• frontWithFlash – front with flash.

| | width | 2000 | Int? | Target width (in pixels) of the captured image after processing (crop & resize). Image scales proportionally to maintain aspect ratio | | autoCapture | `true` | bool | When set to `true`, the system will automatically capture the document once it is properly detected and aligned. When set to `false`, the user must manually trigger the capture instead. | | {% endtab %} | | | | {% tab title="React Native" %} ### Installation {% hint style="info" %} Requirements #### Android * minSdkVersion >= 30 #### iOS * iOS 15+ * Swift 5 {% endhint %} ### Getting Started ``` $ yarn add react-native-okaycam@3.x.x ``` #### Android 1. Navigate to `android` folder 2. Add following snippet in the root `build.gradle` file: ``` allprojects { repositories { maven { url "https://innov8tif-okaycam.firebaseapp.com" content { includeGroup "com.innov8tif.xendity" } } } } ``` 3. Sync Gradle
#### iOS 1. Navigate to ios folder 2. Add the following code to Podfile ``` platform :ios, '15.0' use_frameworks! post_install do |installer| installer.pods_project.targets.each do |target| if (target.name&.eql?('FBReactNativeSpec')) target.build_phases.each do |build_phase| if (build_phase.respond_to?(:name) && build_phase.name.eql?('[CP-User] Generate Specs')) target.build_phases.move(build_phase, 0) end end end target.build_configurations.each do |config| config.build_settings["EXCLUDED_ARCHS[sdk=iphonesimulator*]"] = "arm64" config.build_settings["ONLY_ACTIVE_ARCH"] = "NO" if target.name == "CryptoSwift" puts "Enable module stability for CryptoSwift" config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES' end if target.name == 'fmt' puts "Enable module stability for fmt" config.build_settings['CLANG_CXX_LANGUAGE_STANDARD'] = 'c++17' end end end end ``` 3. Run command [`pod install`](#user-content-fn-1)[^1] 4. Add camera position #### **Android Issue** Duplicate class org.hamcrest.xxx If you encouter the errors above, you may exclude junit module. ``` configurations { compile.exclude group: "junit", module: "junit" } ``` #### **iOS Issue** `Undefined symbol: _`*`swift_FORCE_LOAD`*`$_swiftUniformTypeIdentifiers` `Undefined symbol: _`*`swift_FORCE_LOAD`*`$_swiftCoreMIDI`\ \ If you encouter the errors above, you may create a new swift file called **Void.swift** without adding **bridging header**.
#### **License** Apply licenses for Android and iOS SDKs ``` const license = Platform.select({ android: "", ios: "" }) ``` #### **OkayCam Document** | - | Property Name | Description | Default value | | ------------------------------------------------ | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | | width | width to resize the image | 2000 | | | imageQuality | quality of cropped image | 1.0f | | **New** **SDK version >= 3.0.0** mode | FULL | Captures front of document, front of document with flash, and back of document automatically. This is the default mode for complete document capture. | ✅ | | | FRONT\_ONLY | Captures only the front of document. | ❌ | | | FRONT\_BACK | Captures both front and back of document automatically without flash. | ❌ | | | FRONT\_WITH\_FLASH | Captures the front of document with flash enabled | ❌ | ### Usage ``` import { captureDocument, DocumentCaptureMode } from "react-native-okaycam" captureDocument(license, false, { width: 2000, imageQuality: 0.8, mode: DocumentCaptureMode.FULL, }) .then(result => { console.log(JSON.stringify(result)); }) .catch(error => { console.log(JSON.stringify(error)); }); ``` ### Result | Result | Description | | ------------------ | ------------------------------ | | fullDocumentImage | Result of first photo | | fullDocumentImage2 | Result of first photo cropped | | fullDocumentImage3 | Result of second photo | | fullDocumentImage4 | Result of second photo cropped | | {% endtab %} | | | {% endtabs %} | | ### Supported ID Types These are the supported ID types of document to be auto captured.\ This allows the SDK to optimize detection, alignment, and cropping based on the selected document format. | ID Type | Description | | ----------------------------- | -------------------------------------------- | | Passport (MRZ) | Machine-readable travel documents (passport) | | Malaysia MyKad | Malaysian national identity card | | Malaysia MyTentera | Malaysian military ID | | Malaysia iKad | Malaysian temporary resident card | | Malaysia Driving License | Malaysian driver’s license | | Malaysia MyPR | Malaysian permanent resident card | | Singapore NRIC | Singapore national ID | | Singapore Work Permit | Singapore work permit card | | Singapore Visit Pass | Singapore visit pass | | Singapore Driving License | Singapore driver’s license | | Indonesia eKTP | Indonesian electronic ID card | | Thailand National ID | Thailand national ID | | Thailand Driving License (65) | Thai driving license (older format) | | Thailand Driving License (35) | Thai driving license (new format) | | Jordan National ID | Jordan national ID | | Malaysia MyKid | Malaysian child identity card | | Malaysia MyKas | Malaysian temporary ID | | Malaysia MyPOCA | Malaysian restricted residence card | | Bangladesh ID | Bangladesh national ID | | Cambodia ID | Cambodia national ID | ### User Interface Example ### OkayCam Demo Preview ( V3 - Old Design)
### OkayCam Demo Preview ( V3 - New UI Design)
[^1]: