Kofax Mobile SDK Developer's Guide

powerfuelSoftware and s/w Development

Nov 9, 2013 (3 years and 9 months ago)

1,438 views

Kofax Mobile SDK
1.2.1
Kofax Mobile SDK Developer's
Guide
2013-08-09
©
2013 Kofax, Inc., 15211 Laguna Canyon Road, Irvine, California 92618, U.S.A. All rights reserved. Use is
subject to license terms.
Third-party software is copyrighted and licensed from Kofax’s suppliers.
This product is protected by U.S. Patent No. 6,370,277.
THIS SOFTWARE CONTAINS CONFIDENTIAL INFORMATION AND TRADE SECRETS OF KOFAX,
INC. USE, DISCLOSURE OR REPRODUCTION IS PROHIBITED WITHOUT THE PRIOR EXPRESS
WRITTEN PERMISSION OF KOFAX, INC.
Kofax, the Kofax logo, and the Kofax product names stated herein are trademarks or registered
trademarks of Kofax, Inc. in the U.S. and other countries. All other trademarks are the trademarks or
registered trademarks of their respective owners.
U.S. Government Rights Commercial software. Government users are subject to the Kofax, Inc. standard
license agreement and applicable provisions of the FAR and its supplements.
You agree that you do not intend to and will not, directly or indirectly, export or transmit the Software
or related documentation and technical data to any country to which such export or transmission is
restricted by any applicable U.S. regulation or statute, without the prior written consent, if required, of
the Bureau of Export Administration of the U.S. Department of Commerce, or such other governmental
entity as may have jurisdiction over such export or transmission. You represent and warrant that you are
not located in, under the control of, or a national or resident of any such country.
DOCUMENTATION IS PROVIDED “AS IS” AND ALL EXPRESS OR IMPLIED CONDITIONS,
REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE
DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY
INVALID.
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
3
Contents
Legal Notice ..........................................................................................................................................................................2
Preface ....................................................................................................................................................................................5
Getting Help for Kofax Products .................................................................................................................................5
The Kofax Mobile SDK .......................................................................................................................................................7
Overview ...........................................................................................................................................................................7
Licensing ...........................................................................................................................................................................8
Installing the License for the Sample Applications ..............................................................................................8
The Kofax Mobile SDK API ..........................................................................................................................................9
KMC Internal Layer Screens ....................................................................................................................................9
Standard eVRS Image Processing Features ..........................................................................................................10
Optional Image Processing Features .....................................................................................................................10
Two General SDK Uses ...........................................................................................................................................11
Use Case Examples ..................................................................................................................................................11
Sample Applications ..........................................................................................................................................................15
KMCDemo Sample Application .................................................................................................................................15
Wireless Access to Servers ......................................................................................................................................15
KMCDemo Sample Application - iOS ..................................................................................................................15
KMCDemo Sample Application - Android .........................................................................................................19
Driver’s License Demo Application Sample Application .......................................................................................23
OCR Service ...............................................................................................................................................................23
Settings File ...............................................................................................................................................................23
Architecture ...............................................................................................................................................................25
License File ................................................................................................................................................................26
Driver’s License Demo Application Sample Application - iOS ........................................................................26
Driver’s License Demo Application Sample Application - Android ...............................................................35
KMC Library XML File Format ..................................................................................................................................44
Element: destination .................................................................................................................................................44
Element: scanSettings ...............................................................................................................................................46
EVRS Operations String Tokens ............................................................................................................................47
Example XML String ................................................................................................................................................51
Bar Code Return Data ..................................................................................................................................................52
Data Formatting Details ..........................................................................................................................................54
Viewing Bar Code Data - KMCDemo Applications ...........................................................................................54
Contents
4
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
5
Preface
This guide includes the information you need to successfully integrate Kofax Mobile SDK
components into your mobile application.
Getting Help for Kofax Products
Kofax regularly updates the Kofax Support site with the latest information about Kofax
products.
To access some resources, you must have a valid Support Agreement with an authorized
Kofax Reseller/Partner or with Kofax directly.
Use the tools that Kofax provides for researching and identifying issues. For example, use the
Kofax Support site to search for answers about messages, keywords, and product issues. To
access the Kofax Support page, go to www.kofax.com/support
.
The Kofax Support page provides:
▪ Product information and release news
Click a product family, select a product, and select a version number.
▪ Downloadable product documentation
Click a product family, select a product, and click Documentation.
▪ Access to product knowledge bases
Click Knowledge Base.
▪ Access to the Kofax Customer Portal (for eligible customers)
Click Account Management and log in.
To optimize your use of the portal, go to the Kofax Customer Portal login page and click
the link to open the Guide to the Kofax Support Portal. This guide describes how to access
the support site, what to do before contacting the support team, how to open a new case or
view an open case, and what information to collect before opening a case.
▪ Access to support tools
Click Tools and select the tool to use.
▪ Information about the support commitment for Kofax products
Click Support Details and select Kofax Support Commitment.
Use these tools to find answers to questions that you have, to learn about new functionality,
and to research possible solutions to current issues.
Preface
6
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
7
Chapter 1
The Kofax Mobile SDK
The Kofax Mobile SDKprovides libraries, headers, code samples, documentation and a help
system that developers use to create mobile applications that require image processing.
This SDK is distributed as a zip file, which includes all development environments. The SDK
uses a license model, so that the libraries cannot be used without one. Once you unzip the
SDK, you will install the license within your own application or within the source code for the
sample applications.
Note If you select the TotalAgility server type, please note that “case” (as in “case type”)
or “cases,” as used in this guide, are not the same thing as the usage for “case” you may be
familiar with in TotalAgility
Overview
The Kofax Mobile SDK includes separate libraries to integrate with applications designed
to run on Android, iOS and Windows mobile devices. The Kofax Mobile SDK includes two
types of libraries: eVRS Image Processing and BPM (Business Process Management) image
capture.
The eVRS Image Processing library provides a C API to patented eVRS processing technology
that includes features specific to images obtained from mobile device cameras. The API
includes functions for creating buffers from images, and processing the buffered images using
simple image processing options. This library is described in a separate developer's guide. In
order to interface with this library you must create your own wrapper layer to be included in
your native programming model. This is not the case with the BPM Image Capture library.
The BPM Image Capture library allows for the use of integrated business processes,
processing images with the embedded eVRS Image Processing library, and optionally
submitting images to the server. You can use the BPM Image Capture library to write
applications using the native (Java or Objective-C) programming model.
The BPM Image Capture library uses a case type model with images. A case type is a
document schema that is associated with processed images, unprocessed images or photos,
and provides relevant information about these images. When a case type is instantiated, the
library helps you to enter information in case fields, such as a customer's name, address and
account number. Most library API methods make use of cases, but there are other ways to
work with images.
Cases can be submitted to your server, or the same information can be submitted to your
own BPM flow. The balance of this developer's guide goes into greater detail regarding the
options you have to design your own app with the BPM Image Capture library, and describes
different typical use cases.
The Kofax Mobile SDK
8
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
Note An underlying assumption with regard to case management is that you can have only
one active open case object at a time. Always process multiple cases sequentially.
The library includes a number of user interface screens that you can use as part of your
application, or you can design your own user interface and integrate using other API methods
that do not use the internal screens.
You can integrate the library class architecture with your application in different ways:
▪ Optionally use internal case management screens for data input, image review, and
editing.
▪ Customize the internal home screen if you decide to use it, or design your own and call
other library processes.
▪ Optionally integrate with your own server.
▪ Integrate with your own BPM flow with or without using cases.
▪ Integrate with the image processing features of the library without using cases at all.
The BPM Image Capture library is not available for Windows Mobile applications.
Licensing
All applications using the Mobile SDK require a license from Kofax. The application embeds
the license string within the source code. If a valid license is not compiled with the project,
the application will not function because the library returns a licensing error with most API
method calls.
All libraries use a consistent licensing scheme, regardless of the development environment
and which library you use.
You can obtain a license from though the channel you used to get this SDK. The license is
distributed as a file named kfxEVRS_License.h. Copy this file into the project folder where all
the source code is located. This will write over the temporary file that is already there.
The library API includes a class method to set your license string. If successful, you can call
other class methods in the library without error.
Installing the License for the Sample Applications
After you install the KMCDemo or Driver’s License Demo Application application on your
development system, you can build the sample application and run it on your mobile device.
The sample application source code includes a dummy license file that allows you to build the
sample applications without error.
When you obtain your license, replace the file included in the project with the correct license
header file. Then you can rebuild the sample application and call library methods without
error.
To verify your license with the sample application, you can launch it and tap the eVRS
button. If you see an eVRS License error, then you have not incorporated the license file
correctly.
The Kofax Mobile SDK
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
9
The Kofax Mobile SDK API
These SDK use cases are based on the methods and properties provided by the KMC Abstract
Layer (KAL) API. Several Kofax Mobile SDK classes implement the programming API
through this abstract layer. KAL itself (and API within) does not have any UI elements and is
therefore abstracted from the lower KMC internal layer. However, the KAL layer sits on top
of the KMC internal layer in the software stack, as shown below.
 
 
The KMC Internal layer includes UI elements. These UI elements are contained in the KMC
framework and associated bundle. A user application includes the KMC framework, but
communicates through the KAL which is a group of about 5 classes. There are approximately
20 screens integrated within the KMC internal layer, which is all contained in the KMC
library. These screens may or may not be used by your application, and are tabulated below.
KMC Internal Layer Screens
The use cases below are described in context with KAL, because it provides the methods for
these use cases. The following screens are contained in the KMC Internal layer.
Table 1-1. KMC Library Screens
Screen
Description
Home screen
Displays a home screen with the custom controls you specify. You can see an
about box, your logo, launch the KFS login or Settings screens, and start the
case management flow with capture and process.
Settings
This screen shows the options for the stability feature, automatic processing and
review options. This screen can be blocked from use by your users.
Case Selection
A list of cases obtained from KFS from which you select a case for adding
images.
The Kofax Mobile SDK
10
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
Screen
Description
KFS Account
This screen allows your user to log into the KFS server, by specifying the user
name, password, an email address and server name. You would need to specify
this at some point when you integrate with KFS.
Image Acquire
This is a camera image screen, including grid lines, the stability feature and flash
controls. This includes a screen with feedback during automatic processing.
Image Review
This screen shows the image acquired, with the edge of the document
highlighted, and the results of the image quality tests for saturation and focus.
Case Management
A view of document thumbnails and images associated with a case. You can use
it to edit and manipulate the images.
Edit Screens
A screen where you can edit an image, select from a menu to manually crop it,
rotate it, reprocess it and other options. Then the modified image goes back into
the case edit thumbnail list view.
Case Control Menu
A menu that allows capturing more photos or documents, entering case
information and submitting a case.
Case Information
This screen shows the fields that you want your user to fill in for the case, such
as name and address or account information.
Submit in process
This screen shows the submit information, the case data and document
information being submitted.
Submit complete
A final review screen with a Done button. Tapping done returns back into the
starting point, which might be the home screen or back to your application.
In just a few minutes, you can easily create an application using the library framework, and
calling the home screen method in KAL, which would be the easiest application to create. The
other cases depend on the types of things you want to do. eVRS image processing is common
with all the cases.
Standard eVRS Image Processing Features
The basic image processing that the Kofax Mobile 1.1 SDK library provides includes:
▪ Referencing the internal phone gyro to detect, control and reference movement, and taking
a photo after a selectable stability setting is reached to eliminate photo focus issues and
blur.
▪ Using images obtained from the camera’s photo roll, or from the camera in real time.
▪ Finding the trapezoidal edges of the document in a photo.
▪ Verifying the quality of the image, checking if it is under or over-saturated, or if it is blurry.
▪ Rectifying the trapezoidal source image into a rectangle, stretching the image as needed.
▪ Cropping the image to this rectified rectangle.
▪ Removing any skew in the rectangle, to make it straight up for reading or viewing.
▪ Applying any selectable and optional image processing enhancements to the rectified
image. The optional image processing features are listed below.
Optional Image Processing Features
Optional Feature
Description
Remove speckles
Removes specs of noise and cleans up a bitonal image using a sensitivity setting
Sharpen
Removes blur and sharpens up the image using a sensitivity setting. This
improves OCR and image crispness.
The Kofax Mobile SDK
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
11
Optional Feature
Description
Rotation
Rotates the image by 90 degree increments to orient it as desired.
Auto-orientation
Automatically rotates the image so characters are right side up.
Deskew by content
Deskews the original image by using the content on the document, rather than
the document edge. You can also select deskew by found document edges.
Change output
Changes output to a grayscale or bitonal image.
Scale DPI
Scales the effective DPI of the image, so to improve OCR to remove image
artifacts.
Smooth
background
Smooths out the background color of a color document, so that a variegated
color is replaced by an average fixed color.
Two General SDK Uses
There are two general use cases revolving around the two basic libraries in the SDK. If
you want to integrate an application with the server, or make use of the image processing
capabilities with management of images in a business process associated with a case, and
make use of the internal UI screens for designing a quick application around Kofax Mobile
services, then you should use the KMC Library.
If you want to design an application that uses only the low level image processing capabilities
of eVRS, and not use any of the business processes and UI, then you can use the eVRS library.
The eVRS library works with images in memory, and you would use the eVRS API directly to
process image. There is a separate guide for this library.
The KMC library also has a stand-alone eVRS image processing feature. Unlike the eVRS
image processing in the eVRS library, this KMC library API employs the camera capture
features and internal UI screens for image review, quality feedback and image storage.
KFS Case Model
The business processing flow involves what we refer to as a “case”. A case is simply a
definition or schema for a type of document and business process, along with the textual
data associated with one or more documents of that type. For instance, a case may include
fields, for the Name, Address and Driver’s License number for a claim or application. The end
user fills in these fields, and perhaps adds a photo of the driver’s license itself, a photo of a
damaged car, or of an application form. The contents of the case fields, and all the documents
in the case are then treated like a folder. Then this folder, or case, is sent to a repository such
as KFS or some other user selected destination. The library refers to the submit process, and
this refers to sending the case to the company for further processing. If you want to use this
case management feature, you use the KMC library and design an application around that
library.
Use Case Examples
Following are some common use cases.
KFS Integration Cases
These use cases are for designs that integrate with KFS, and need to use case management.
The Kofax Mobile SDK
12
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
Launch a Customized Home Screen, Submitting it to KFS
The KMC library includes methods to add your own logo into the top left corner of the home
screen, design your own about box contents to display with the more info button. You can
also specify your own application name for display on the home screen. If your application
and end users would be confused by the default use of the word “Case,” you can rename that
term. You can then launch the home screen and start a business process flow based on the
built-in UI and integration with KFS.
A very simple application could have one call into the KMC library after setting
customization features, and then launch right into the KMC feature set and processing flow.
From the home screen a "Create Case" button starts with case selection. After selecting a case
from the list, the application would navigate through the case management flow. At the end
of the management flow, you can view documents, edit them, and then submit the case to
KFS.
Design Your Own Home Screen, Jump into Case Management
This case is for an application that already has a home screen, and you want to integrate
the KMC features at some other integration point. You can call into the library to select a
predefined case that has been designed by your KFS administrator. After selecting the case
from the list, the application would navigate through the case management flow. At the end
of the management flow, you can view documents, edit them, and then submit the case to
KFS.
Preselect a Case and Then Start Case Management Flow
This is similar to the previous case, except that you can control the case. For instance you may
want your application to be very specific, and make it strictly check the quality of the case
information. You design your own UI and flow. Then you can call into the case management
flow. To do this, you preselect a case, and call the capture and process method in the KMC
case flow.
Manually Add Images to a Case and Manually Submit
This is the lowest level of controls, where you want to call into the library just to take an
image of a document for image processing, add a photo, and launch the screen to enter case
information. This eliminates the case management flow, but just includes the capture and
process. Your application takes control of the case management. Then, once your application
is satisfied, you can submit the case directly to KFS by launching the submit screen.
Integrate With Something Other Than KFS
You can integrate with systems that are not based on KFS.
Integrate an Application with Case Management
This sort of application would use your own screen management and involve selecting a case
of your own design. You would design your own XML file, and that file would include fields
and processing settings for the processed documents. Then you would use the contents of
that file to create a case, similar to the ones used in KFS. You would then launch the KMC
capture and process flow, and the library would navigate through the case management
process, taking pictures of things to improve with image processing or taking photos for case
inclusion. At the end of the management flow, you can view documents, edit them, manually
crop, rotate and save the image, and then prepare your case for submitting.
The Kofax Mobile SDK
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
13
There is a way to override the normal submit process, so that when the user taps on Submit
Case from the case management flow, the library calls your own submit routine in your
application instead of submitting the case to KFS. Within your submit call back function
you could do several things. You could submit the case to a server, cloud services, another
business process or send an email with attachments. The sample application included in the
SDK demonstrates how to send an email containing the information in the case, and with the
processed documents as attachments.
Integrate with Capture and Process Stand-Alone
You would use this case when you do not want to make use of the KMC case management
flow, nor the case submit process. In fact you don't want to use the concept of a case at all,
but you want to make use of the built in UI to take pictures for processing, and you want to
control how the image processing is done by specifying custom settings. The Capture and
Process flow includes the following:
▪ Select an image from the photo roll or from the camera
▪ Select the use and sensitivity of the camera stability feature when taking a photo
▪ Enable or disable automatic image processing
▪ Enable or disable image review
▪ Enable or disable image quality feedback to obtain the found document edges, the focus
quality and the saturation quality
You can also perform a batch process on a set of images and save these images in folders. This
use case is when you set a control to turn off automatic processing, so you can bulk process
the images on demand.
Then you handle the processed images according to your own application design. The library
gives you methods to access the raw files in the document folders associated with your
application.
Classification
The Classification API can be used to take advantage of the SDK's runtime classification
engine. The classification component recognizes specific types of driver licenses based on
information contained in a pre-configured driver license classification model.
In order to obtain the best results, the image of the driver license should be deskewed and
cropped before classification. During the classification process, the Classifier determines one
or more matches which are returned as a set of category strings.
Each category string consists of the state (following standard U.S. Postal Service two letter
abbreviations (for example CA is California) plus a digit. The digit is an arbitrary number
assigned to each variation of the license, for example a different license for younger drivers.
For specific details, see the Classification API reference documentation.
The Kofax Mobile SDK
14
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
15
Chapter 2
Sample Applications
See the following sections for information regarding the sample applications included with
the SDK.
There are two sample applications for each platform: iOS and Android.
▪ KMCDemo is a general purpose sample application that implements all library classes and
calls all available methods to demonstrate the common use cases.
▪ Driver’s License Demo Application is a special purpose sample application optimized for
capturing driver licenses and demonstrating all the silent API methods that do not use the
library screens. The Android version of this application is called “KMCDemoDL” while
the iOS version is called “KMCDLDemo.” Throughout this document, both are generically
referred to as the “Driver’s License Demo Application.”
Due to platform differences, there are minor variations between the iOS and Android
implementations of the sample applications, but they exhibit essentially the same behavior.
KMCDemo Sample Application
The following requirements apply to both iOS and Android. Requirements that are unique to
a platform can be found in their respective sections.
Wireless Access to Servers
Your mobile device must be configured for wireless access to the network containing the KFS
server and the network service for obtaining the extraction results (for the Driver’s License
Demo Application application). The network URL for the KFS server and the OCR service are
usually different, and use different ports. The URL for each type of server is contained in the
settings file for the application. The settings file for the Driver’s License Demo Application
application is described in another section of this document.
KFS Server
The sample application communicates with a KFS server, and the mobile device needs
access to a KFS 4.0 server that includes fix pack 1. This fix pack provides required KFS case
type settings to provide the best image quality settings for documents from which data is
extracted. The KFS server also needs the OCR service integrated as part of the same system.
KMCDemo Sample Application - iOS
The sample application for the iPhone or iPad demonstrates how to integrate the Kofax
Mobile Capture SDK library into an iOS application. The sample application gives you a fully
functioning demonstration of the capabilities supported by the library.
Sample Applications
16
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
Development Requirements
Developers working with the iOS sample application should have an environment that meets
the following requirements. Developers should also be familiar with iOS programming and
Apple's methods of provisioning and delivering applications to the App Store.
Hardware Requirements
Before evaluating the sample application and the Kofax Mobile Capture library, you need to
put together a test system. You need a standard Apple Macintosh, running Lion (OS X10.7 or
later).
Software Requirements
Install at least XCode 4.3.1 development environment on your Mac if you have not already
done so. You will use XCode to build and test the sample application.
Case Files
The application stores several file types in the sandbox area. The Documents/
KofaxMobileCapture folder holds all the files associated with image processing and case
management. The .cas files contain binary case information. All images used with KFS are
associated with a case file. The *_raw.jpg files are the raw image files before processing.
The *_proc.jpg and *_proc.tif files are the processed images which are smaller than the
original raw images. TIFF files are produced when bitonal images are required by the image
processing application. These images may be deleted during processing by using the API
methods or after a case is submitted. All files associated with a case are prepended with run-
time unique text, which includes the date and time the file was created, starting with the
calendar year, month and day.
The Documents/Library folder contains preferences and caches associated with the Kofax
Mobile Capture library, and the sample application.
Building the KMCDemo iOS Sample Application
The following sections provide an overview of building the sample application.
Integration of the KMC library
Copy the KofaxMobileCaptureSDK/KMCSDK-iOS.zip file to a folder on your Mac, for
instance in the Desktop/KMC folder. The iOS sample application source code and the iOS
framework and bundle are in this zip file. You must copy the zip file to your Mac and unzip
it from there. This is necessary because there are Mac-based symbolic links within the zipped
files and these symbolic links will not work correctly unless you unzip it in the correct
location. When you unzip on a Mac, it will create four folders, two for the KMC framework
and bundle, and two for the application.
The sample application already includes the framework and bundle, however if you create
your own application, you must also include the KMC framework and KMC bundle in your
application to integrate with the KMC library.
Likewise, the sample application already has the necessary build settings. If your create your
own application, add KMCSDK.framework from “Link Binary With Library” under Build
Phases and “KMCSDKBundle.bundle” from “Copy Bundle Resources” under Build Phases.
Sample Applications
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
17
Running the KMCDemo iOS Sample Application
Use the procedure in this section to run the sample application to try out the various
capabilities that are available with the Kofax Mobile Capture SDK library.
1 Install and run the sample application on your mobile iOS device.
2 From the home screen select the area you want to test. Each of the four categories test
different API functions.
▪ KFS (Kofax Front Office Server) takes you to the KFS Demo screen. From the Settings
button, you can log in, select case management flow controls, and Advanced Settings
(camera stability, automatic processing and so on). After starting Kofax Front Office
Server, you can select a case, and then start the standard case management flow.
▪ Non-KFS takes you to a demo area where you can test features that are not dependant
on Kofax Front Office Server. For example, you can customize the library capabilities
to create a case based on an XML file, add documents to the case, and then submit
to a user-defined receiving process by using a custom submit function that sends
documents to something other than Kofax Front Office Server. The sample application
sends an email and attachments.
▪ KMC takes you to a demo area where you can use the Customize Home button and
the KMC Home button. The Customize Home button takes you to a screen where
you can select from pre-defined examples of customized About box text, logos and
alternates for “Case”. The Settings, Select Case, Capture and Manual buttons work
together. The Settings button takes you to the Capture Settings screen where you can
select case management flow options or advanced settings. You can also log in to
Kofax Front Office Server from this screen. The Pending Cases button displays case
information and allows you to delete cases, change the content of a case or delete
images.
▪ VRS takes you to a demo area where you can test image processing that is outside of
the case management flow, and not intended for integration with Kofax Front Office
Server. This demonstrates how a user can integrate the image processing flow with
an application. This flow still uses the advanced settings but not the management
flow. When you capture documents they are added to the documents area in the
application's own workspace.
▪ Barcode Settings takes you to the Barcode Settings Screen. From this screen you can
enable or disable bar code recognition
. You can also specify the search directions
and types of bar code you want to be recognized.
▪ Show Barcodes takes you to a screen that displays the bar code data
.
Creating An iOS Application with the SDK
Following are some general guidelines to observe when creating your own application.
Integrating the KMC Library
You must include the KMC framework and KMC bundle in your own application to integrate
with the KMC library. To prepare to include the KMC frame work use the following steps.
Copy the KofaxMobileSDK-1.2.0.ZIP file from the SDK to a folder on your Mac, for instance
in your desktop in a Desktop/KMC folder. When you unzip it, you will unzip almost 9000
items, about 250 Mb. You will see the three top level folders for the SDK, Android, iOS and
WinMobile6 folders. Navigate into the iOS folder. Navigate into the KofaxMobileCaptureSDK
folder. Unzip the KMCSDK-iOS.zip file. Navigate into the KMCSDK-iOS folder. You will find
Sample Applications
18
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
two subfolders KMCSDK.framework and KMCSDKBundle.bundle. Copy the framework and
the bundle folders and paste them it into your application's top-level folder. Then you need to
include them into your XCode project.
To create your own application using the KMC library, you need to include the KMC
Library framework into your XCode project. To do this, you open your project, click
on the application target in XCode, and then select Build Phases from the in-screen top
menu. In Build Phases, click on the "Link binary with libraries" area and add the KMC
Library framework. To do so, you highlight an existing framework, scroll down and
click on the + symbol. This pops up a list of frameworks. You need to select and add the
KMCSDK.framework from the binary section of the SDK folder. You also use this technique
to add the other KMC SDK framework dependencies.
Add the KMCSDKBundle.bundle file in your project to allow use of all the screens embedded
in the framework and associated library.
Integrating Other iOS Frameworks
The KMCSDK framework has dependencies on several other frameworks. If you application
does not already include these frameworks, you need to add them to your project. You need
the following frameworks to build an application with the KMCSDK. These frameworks are
tabulated below.
▪ AVFoundation.framework
▪ UIKit.framework
▪ AudioToolbox.framework
▪ OpenGLES.framework
▪ ImagIO.framework
▪ CoreImage.framework
▪ CoreLocation.framework
▪ MobileCoreServices.framework
▪ QuartzCore.framework
▪ CoreMotion.framework
▪ SystemConfiguration.framework
▪ MessageUI.framework
▪ Foundation.framework
▪ CoreGraphics.framework
▪ libxml2.dylib
Design Guidelines
Many of the API methods need a Navigation Controller object reference in order to
display KMC Layer UI screens. Therefore, your application must be based on a Navigation
Controller.
The sample application uses Automatic Reference Counting (ARC) for memory management.
ARC is an Objective-C compiler option useful for any application targeted for iOS 4 and later.
With ARC enabled, the compiler controls and enforces proper memory management, giving
you an alternative to manual object release calls. The compiler inserts memory management
controls to free memory for an object when the code no longer references that object. This
approach is reliable and it simplifies the coding process. Kofax recommends that you also
design your application, which includes the Kofax KMC SDK library, to use ARC for memory
management.
Sample Applications
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
19
Furthermore, Kofax recommends that you design your application so that it checks carefully
for all return error codes from the library calls. As a result, you can better communicate with
Kofax support about any possible errors that you may have encountered during testing. Be
sure to use NSLog( ) to log debug information, which may also be useful in the event that you
require support or assistance from Kofax.
KMCDemo Sample Application - Android
The sample application for Android demonstrates how to integrate the Kofax Mobile
Capture SDK library into an Android application. The sample application gives you a fully
functioning demonstration of the capabilities supported by the library.
Development Requirements
Developers working with the Android sample application should have an environment
that meets the following requirements. Developers should also be familiar with Java
programming in an Android environment and the applicable methods of and delivering
applications to the end user.
Hardware Requirements
Before evaluating the sample application and the Kofax Mobile Capture library, you need to
put together a test system. Any standard Windows based desktop or laptop will work fine.
Software Requirements
Download and install the Eclipse version 3.7.2 or later.
Also, download the Android SDK and integrate it with Eclipse. At least Android
Development Tools (ADT) 15 is required.
Use at least Java JDK 1.6.
Building the KMCDemo Android Sample Application
Developing applications for Android devices is facilitated by a group of tools that are
provided with the Android SDK. You can access these tools through an Eclipse plug-in called
ADT (Android Development Tools) or from the command line. You can open the Kofax
Mobile Capture SDK sample project in the Eclipse development environment, where the
Android ADT plug-in is installed. Eclipse with ADT will compile and package the sample
application source files, resources, and native libraries.
Set Up the Sample Application
There are two projects, one is the sample application and the other is the resource only Kofax
Mobile Capture SDK project.
In general:
▪ Import the KMCSDK project to your Eclipse work space, clean and build it.
▪ Import the Sample Application project to Eclipse, clean and build it
▪ If there are errors, confirm that you have at least ADT 15 and JDK 1.6.
Once the application is successfully compiled and built, run it via the Eclipse IDE. It will
install the apk file on your device.
Sample Applications
20
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
In order to use the SDK to create your own application it is important to setup up your
AndroidManifest.xml file such that it includes the two blocks of lines shown below.
Include this:
<!-- These permissions must be added to the android manifest files -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission
android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /
>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /
>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.CALL_PHONE" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.FORCE_BACK" />
<uses-permission
android:name="android.permission.INSTALL_LOCATION_PROVIDER" />
<uses-permission android:name="android.permission.READ_CALENDAR" />
<uses-permission android:name="android.permission.WRITE_CALENDAR" />
<uses-permission android:name="android.permission.READ_CONTACTS" />
<uses-permission android:name="android.permission.WRITE_CONTACTS" />
<uses-permission android:name="android.permission.READ_OWNER_DATA" />
<uses-permission android:name="android.permission.READ_SMS" />
<uses-permission android:name="android.permission.WRITE_SMS" />
<uses-permission android:name="android.permission.RECEIVE_SMS" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.SEND_SMS" />
<uses-permission android:name="android.permission.SET_ALWAYS_FINISH" />
<uses-permission
android:name="android.permission.SUBSCRIBED_FEEDS_READ" />
<uses-permission
android:name="android.permission.SUBSCRIBED_FEEDS_WRITE" />
<uses-permission android:name="android.permission.VIBRATE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission
android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission
android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-feature android:name="android.hardware.camera" />
<uses-feature android:name="android.hardware.camera.autofocus" />
<uses-feature
android:name="android.hardware.telephony"
android:required="false" />
<supports-screens
android:anyDensity="true"
android:largeScreens="true"
android:normalScreens="true"
android:resizeable="true"
android:smallScreens="true" />
<!-- End copy of permissions -->
Also include this:
<!-- KofaxMobile Capture SDK copy and paste part two starts here -->


<activity
android:name="com.kofax.mobilecapture.sdk.kmc.view.
KMCHomePageActivity"
android:configChanges="orientation"
android:screenOrientation="portrait" >
</activity>
Sample Applications
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
21
<activity
android:name="com.kofax.mobilecapture.sdk.kmc.view.settings.
SettingsMainActivity"
android:configChanges="orientation"
android:label="@string/kmc_pref_kofax"
android:screenOrientation="portrait" />
<activity
android:name="com.kofax.mobilecapture.sdk.kmc.view.settings.
SettingsImageProcessingActivity"
android:configChanges="orientation"
android:label="@string/kmc_pref_vrs"
android:screenOrientation="portrait" />
<activity
android:name="com.kofax.mobilecapture.sdk.kmc.view.settings.
SettingsAccountActivity"
android:configChanges="orientation"
android:label="@string/kmc_pref_account"
android:screenOrientation="portrait" />
<activity
android:name="com.kofax.mobilecapture.sdk.kmc.view.casemgt.
CaseManagementActivity"
android:configChanges="orientation"
android:screenOrientation="portrait" />
<activity
android:name="com.kofax.mobilecapture.sdk.kmc.view.casemgt.
CaseEditActivity"
android:configChanges="orientation"
android:screenOrientation="portrait" />
<activity
android:name="com.kofax.mobilecapture.sdk.kmc.view.casemgt.
ImageViewActivity"
android:configChanges="orientation"
android:screenOrientation="portrait" />
<activity
android:name="com.kofax.mobilecapture.sdk.kmc.view.casemgt.
ImageEditActivity"
android:configChanges="orientation"
android:screenOrientation="portrait" />
<activity
android:name="com.kofax.mobilecapture.sdk.kmc.view.casemgt.
CaseInfoActivity"
android:configChanges="orientation"
android:screenOrientation="portrait" />
<activity
android:name="com.kofax.mobilecapture.sdk.kmc.view.casemgt.camera.
CameraActivity"
android:configChanges="orientation"
android:screenOrientation="landscape" />
<activity
android:name="com.kofax.mobilecapture.sdk.kmc.view.casemgt.camera.
ReviewImageActivity"
android:configChanges="orientation"
android:screenOrientation="portrait" />
<activity
android:name="com.kofax.mobilecapture.sdk.kmc.view.casemgt.camera.
ZoomImageActivity"
android:configChanges="orientation"
android:screenOrientation="portrait" />
<activity
android:name="com.kofax.mobilecapture.sdk.kmc.view.casemgt.crop.
CropImageActivity"
android:configChanges="orientation"
android:screenOrientation="portrait" />
<activity
android:name="com.kofax.mobilecapture.sdk.kmc.view.casemgt.
SubmitCaseActivity"
android:configChanges="orientation"
Sample Applications
22
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
android:screenOrientation="portrait" />
<activity
android:name="com.kofax.mobilecapture.sdk.kmc.view.debug.
KMCDebugMainActivity"
android:configChanges="orientation"
android:label="@string/kmc_app_name"
android:screenOrientation="portrait" />
<activity
android:name="com.kofax.mobilecapture.sdk.kmc.view.debug.
KMCCameraStabilizationTestActivity"
android:configChanges="orientation"
android:screenOrientation="portrait" />
<activity
android:name="com.kofax.mobilecapture.sdk.kal.KMCHiddenActivity"
android:theme="@android:style/Theme.Translucent.NoTitleBar"
android:configChanges="orientation"
android:screenOrientation="portrait" />

<service
android:name="com.kofax.mobilecapture.sdk.kmc.service.
BackgroundProcessingService" />
<activity
android:name="com.kofax.mobilecapture.sdk.kmc.view.KMCAboutActivity"
android:configChanges="orientation"
android:screenOrientation="portrait" />
<activity
android:name="com.kofax.mobilecapture.sdk.kmc.view.KMCAboutHTMLActivity" />

<!-- KofaxMobile Capture SDK copy and paste part ends here -->
These are also available in the AndroidManifest.xml file provided in the sample application.
Also make sure the KMCSDK project is included in the project space.
Running the KMCDemo Android Sample Application
The SDK includes two sample applications. The first is a general purpose sample application,
the second is an application that has been designed for capturing driver licenses.
KMCSDK - General Purpose Sample Application
Use the procedure in this section to run the sample application to try out the image
processing capabilities that are available with the Kofax Mobile Capture SDK library.
1 Install the sample application on your Android device.
2 From the home screen select the area you want to test. Each of the four categories test
different API functions.
▪ KFS (Kofax Front Office Server) takes you to the KFS Demo screen. From the Settings
button, you can log in, select case management flow controls, and Advanced Settings
(camera stability, automatic processing and so on). After starting Kofax Front Office
Server, you can select a case, and then start the standard case management flow.
▪ Non-KFS takes you to a demo area where you can test features that are not dependant
on Kofax Front Office Server. For example, you can customize the library capabilities
to create a case based on an XML file, add documents to the case, and then submit
to a user-defined receiving process by using a custom submit function that sends
documents to something other than Kofax Front Office Server.
A sample XML file has been provided in the asset folder of the project. The asset
folder is created when an Android project is created. For the purpose of the sample
application, please add your xml files in the same location.
Sample Applications
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
23
▪ KMC takes you to a demo area where you can use the Customize Home button and
the KMC Home button. The Customize Home button takes you to a screen where
you can select from pre-defined examples of customized About box text, logos and
alternates for “Case”. The Settings, Select Case, Capture and Manual buttons work
together for another test case. The Settings button takes you to the Capture Settings
screen where you can select case management flow options or advanced settings. You
can also log in to Kofax Front Office Server from this screen. The Pending Cases button
displays case information and allows you to delete cases.
▪ VRS takes you to a demo area where you can test image processing that is outside of
the case management flow, and not intended for integration with Kofax Front Office
Server. This demonstrates how a user can integrate the image processing flow with
an application. This flow still uses the advanced settings but not the management
flow. When you capture documents they are added to the documents area in the
application's own workspace.
▪ Barcode Settings takes you to the Barcode Settings Screen. From this screen you can
enable or disable bar code recognition
. You can also specify the search directions
and types of bar code you want to be recognized.
▪ Show Barcodes takes you to a screen that displays the bar code data
.
Driver’s License Demo Application Sample Application
The Kofax DL sample application has the following purposes:
▪ To demonstrate the use of the new silent API calls to perform many KMC Library tasks
without any UI for SDK users and integrators, and to serve as example code. The silent API
calls include those for: KFS login, image processing and KFS case submission. In addition,
the sample application demonstrates how to integrate the new iOS delegate methods with
the silent API calls.
▪ To demonstrate a working application that integrates a mobile image processing
application with typical OCR extraction as a system. The driver's license use case is
designed into the sample application. To determine the efficiency of each phase of the
process, the sample application displays timing information during the process flow to
demonstrate how each phase contributes to the whole process.
OCR Service
The sample application communicates with a Kofax service called KC-DL Project, (KCDLP),
which extracts driver’s license data using OCR. The URL for this service is supplied in
the settings file, and for the sake of this sample application, the service is integral to the
application process to extract data from the processed image. KCDLP extracts the data, stores
it in a database, and supplies a service where the sample application can access the database
for the OCR data that the service extracted.
Settings File
The kfxSettings file contains settings for the sample application. The sample application
opens this file and uses it to configure the KMC Library objects and to obtain extracted data.
You need to edit this file to configure the sample application for your own test environment.
The file included in the source code does not include valid URL strings.
Sample Applications
24
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
Note For the iOS sample, the kfxSettings file has a .txt extension, for Android it is .xml.
The settings are identical for both platforms except for the case of the setting name. When you
edit the file be sure to maintain the current letter cases.
The kfxSettings file includes the following settings:
serverURL
Set the server URL string to point to the Kofax server to which your own application
submits cases. After case submission completes, the Kofax Transformation Modules on
the server starts the OCR extraction process automatically. The sample application uses
this server URL to silently log into the KFS server.
KFSUserName
Just like the KFS account settings screen, this is the KFS User Name associated with your
KFS account. The sample application sets this string in the KFSModel object for the silent
login method call.
KFSPassword
Just like the KFS account settings screen, this is the KFS password associated with the
User Name for your KFS account.
CaseTypeName
Set this string to indicate what KFS case-type (short-cut) you want to use to submit the
image for processing on the KFS server. This case type must have some sort of unique
Photo Id index field to associate the image with extracted data.
OCRServiceURL
Set this URL to point to a server that is running the KCDLP software. This software
responds to network service get requests. The KCDLDemo application sends network
request using this URL, and the application adds the unique Photo Id to associate the
submitted photo with the data base containing the extracted data. When the KCDLP
starts processing the image, the sample application receives a JSON response packets that
includes fields with the word "Wait!". This notifies the application that the request was
acknowledged, but that the extracted data is not yet available. The sample application
retries the gets request to KCDLP until valid data is received.
FakeJSON
This element includes a typical JSON string that the sample application expects. The
sample application parses the JSON result. It is provided here for testing purposes before
you get the network services working with your own database. You can set a debug/test
variable called bUseFakeJSON to true, and the test JSON string will be used instead of
waiting for a host response.
EmailAddr
Set this email address to the address that you want to use for with your KFS account.
The sample application uses this for sending the notification email containing the
performance data associated with the whole process flow. The email body includes a list
of the license fields extracted from the original image. The email body also includes a
unique identifier that was used both with the submit case and for the JSON request. This
unique id identifies a row of data in the data base on the OCR Service server. The sample
application sets a new parameter in the kfsModel class for the email address used with
the KFS submit and Kofax Capture processing to acknowledge receipt of a case, and in
some cases data associated with a case.
Sample Applications
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
25
Architecture
The sample application communicates with a Kofax service called KC-DL Project, (KCDLP),
which extracts driver’s license data using OCR. The URL for this service is supplied in the
settings file, and for the sake of this sample application, the service is integral to the sample to
extract data from the processed image. KCDLP extracts the data, stores it in a database, and
supplies a service where the sample application can access the database for the OCR data that
the service extracted.
 
 
Driver’s License Demo Application
The top level user application layer includes all the custom code that a typical integrator
writes to include the KMC Library, which the SDK includes. You decide what type
of application to create, and what type of components with which to integrate. The
KMCDLDemo application only communicates with the library with the KMC Abstract Layer.
All the layers below the App layer are contained in the KMC SDK framework.
Bar Code Recognition
The driver's license demo application is able to recognize and extract data from certain bar
codes
that can be found on the backs of many driver licenses. The data extracted from the bar
codes
is displayed on the same screen as the other extracted OCR data.
KMC Abstract Layer
The KAL includes all the classes that comprise the API for the KMC Library. The lower KMC
internal layer is hidden to the User App layer, but the application can access components of it
through KAL. The KAL makes it easier to integrate with the KMC Internal layer by limiting
functionality and helping to simplify the operations that the SDK considers the most valuable
to you as an integrator. Therefore, KAL provides an interface to the internal components of
the library. This layer contains no UI screens.
Sample Applications
26
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
KMC Internal Layer
The KMC internal layer includes all the functionality that is part of the KMC application,
with modifications to make it work well in a stand-alone environment with an SDK. It is self-
contained, and provides the standard interface to KFS to allow users to design their own
application that serves as a capture process device, and submits images with cases to KFS.
This layer contains all of the UI components and multiple screens for the home screen, for
selecting case types, taking images, managing cases, editing images and submitting cases to
KFS.
EVRS Image Processing
This is contained in a separate library with its own internal interface. All of the image
processing library API interface is contained within the KMC internal layer, but the library
is a subcomponent contained within the KMC Library framework. The KMC library SDK
Framework includes the EVRS image processing library, called libKfxEVRSi.a in the EVRSLib
folder. This library provides the standard image improvement options. KAL does not have
any direct communication with the EVRS Library.
License File
The license is distributed as a file named: kfxEVRSLicense.h. The sample application already
includes this header file in the sample application project. This header file includes a #define
for the EVRS license string. The sample application uses this definition to set the license in the
KMCConfiguration object. A valid license is required for using the sample application and to
access the KMC library and the EVRS library. The file included in the SDK is a placeholder
with an invalid license, but allows the build to complete.
After you install Driver’s License Demo Application, you can build the source code and
run the application with limitations. But if you want to interface with the library, you will
need a valid license. You can obtain one from Kofax through the channel you used to get this
SDK. Copy the license file into the Driver’s License Demo Application folder where all the
source code is located. This will write over the temporary file that is already there. Rebuild
the application with the new file, and the sample application will be fully licensed.
To verify your license with the sample application, you can download the application and
launch it on the mobile device by attaching its cable to your computer. When the home screen
displays, the application sends the license string to the library and gets the return code. If you
get a eVRS License error, then you have not incorporated the license file correctly.
You may receive an evaluation and time limited license. Once you go into production you
will receive a production license with a long expiration date. An evaluation license and a
production license are still distributed as a header file.
Driver’s License Demo Application Sample Application - iOS
The sample application for the iPhone or iPad demonstrates how to integrate the Kofax
Mobile Capture SDK library into an iOS application. The sample application gives you a fully
functioning demonstration of the capabilities supported by the library.
The Kofax Mobile Capture 1.2 SDK includes the iOS Driver’s License Demo Application
application source code. The source code includes everything you need to build the Kofax
DL Sample application that runs on typical iOS devices such as the iPhone and iPad. Once
Sample Applications
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
27
deployed on an iOS device, you can see the advantage of the Kofax API to interface with the
Kofax Mobile Capture Abstract Layer, and the Kofax EVRS image processing features.
The Kofax Mobile Capture driver license sample application is a universal (iPhone or iPad),
Navigation Controller based application with only a few simple screens to demonstrate a
simple process flow using SDK features.
This Driver’s License Demo Application application demonstrates an automated process
flow for a driver's license use case for applications that want to authenticate an applicant or
to automatically fill in a loan application, for instance. Just like KMCDemo, this application
integrates with the Kofax KFS server to submit images for back end processing as part of an
overall Mobile Capture application in a BPM environment.
Development Requirements
Developers working with the iOS sample application should have an environment that meets
the following requirements. Developers should also be familiar with iOS programming and
Apple's methods of provisioning and delivering applications to the App Store.
Hardware Requirements
Before evaluating the sample application and the Kofax Mobile Capture library, you need to
put together a test system. You need a typical Mac development system with access to your
own developer portal so that you can configure and use the proper provisioning profile for
the sample application. Typical Mac book or iMac systems work fine.
Software Requirements
In order to build the DL sample project with the KMC library, you need the XCode 4.5.2 or
later. Previous versions of XCode may cause linker errors for parts of the KMC library. You
will use XCode to build and test the sample application.
Driver’s License Demo Application Screens
This application has the following screens
Table 2-1. Driver’s License Demo Application Library User Interface
Screen
Description
Home screen
The home screen launches when you start the application, and it shows the only
two buttons in the application. The settings button launches the settings screen,
and the License button launches the process flow screen for the license use
case.
Settings Screen
Use the settings screen to modify settings available in the sample application.
The settings are limited to those things that are pertinent to the purpose of
the application, which is to automate as much as possible to demonstrate the
silent progress in a driver's license extraction use case. The settings provide
the typical things needed for demonstration purposes. Other typical settings are
automatically set for you.
Use the Show Prompts option to enable or disable the display of image prompts.
Before the application takes the picture of the front side and the back side of the
license, the app prompts you appropriately.
Sample Applications
28
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
Screen
Description
License Process
Flow Screen
Use the License process screen to test and demonstrate all the phases of the
use case to process a driver's license image and extract the license data. The
application calls the KMC library silent API methods and uses the delegates to
progress through the phases of the process. The screen shows labels for all of
the phases used in the process flow.
Refer to the process flow phase chart below that gives a brief overview of the
purpose of each phase. Then other sections describe each phase in detail.
Logout Button
Use the logout button to test and demonstrate the silent logout feature. It calls
the logout method on the KFSModel object. If you don't log out, then the next
time you process another license, the registration phase completes sooner.
Settings Screen Options
At the bottom of the screen are the KMC and eVRS version strings. Use these versions when
communicating about this application to support personnel.
You can select the input image source from either the camera itself, or from the photo roll.
When you select the photo roll, you can select an image that you captured once before, and
reuse this same image. Otherwise, the camera selection allows taking another image using the
KMC layer and the camera stability feature when taking a new photo.
The application automatically selects the review feature, by setting the review option in the
KMCConfiguration object. When Review is on, the library lets you review the image before
continuing. You can cancel the image if you don't want to use the image you acquired.
Enable automatic processing to cause automatic EVRS image processing as soon as the picture
is taken. This feature allows you to review the processed image before submitting it to KFS.
During the processing period, the library displays a progress bar until the image is saved on
the device.
Quality feedback causes the image to be preprocessed by EVRS in order to find the borders
and corners of the document in the image. During preview image processing, the KMC
library displays a progress bar, indicating the progress of determining image quality and
image borders. Upon completion, the KMC Library will launch a review view, showing the
original image with a green border shown around the image document found The library
will indicate if the exposure and focus are good enough for processing. If you tap Done, the
sample application uses this image.
The camera stability feature controls how still the camera needs to be to take a picture.
The higher the number, the steadier you must hold the camera before the picture is taken.
The camera delays the shot until the camera is found steady enough. The application
automatically sets this for you.
Understanding the License Process Flow Screen
Before you start the process, all the phase labels are shown in gray. Once you tap the Start
button, the process begins and the application times each phase of the process. As the process
progresses, the labels are shown green upon successful completion. Each phase will show the
status of the phase, the elapsed time of that phase (unless otherwise noted) and a progress
spinner or progress bar while that phase is in progress. Upon completion of a phase, the
application advances to the next phase. Otherwise, the application will stop on first failure,
and the UI indicates what phase of the process failed in red, and status why the phase failed.
Sample Applications
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
29
Error Handling
When an error occurs, the application will either display a pop up warning or will show a
status message in the UI under the appropriate phase. The application will change the phase
label to red, indicating that phase failed. The application will fail the process on first error,
and indicates that the overall process failed.
Process Flow Phases
The following diagram shows the standard process phases used in the application. Each
phase carries out a step in the process, may include elapsed time measurement to indicate
the impact of each phase on the total elapsed time for the process. The process advances
with a software delegate. If the delegate is not called, then the process waits on that phase.
The UI screen indicates the advancement through each phase when the label turns green.
The progress of each phase is indicated with either a spinner or progress bar. Some phases
cause other UI screen display, with no progress indication. Each phase highlights if the phase
passed or failed, green if it completed ok, or red if an error was detected. The whole process
ends on first failure, and the application shows the failing phase in red. Errors are shown in
a pop up screen or with an error message associated with each phase. If the phase completes
without error, the application shows the elapsed time for that phase.
 
 
Sample Applications
30
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
Registration
The application uses this phase to login to the KFS server using the settings from the settings
file for the KFS server URL, the user name, user password and email address. The KMC
Library calls the loginCompleted delegate to indicate the final login status. The login may
fail for an incorrect URL, unknown user and password or other unavailable service errors.
(Your iOS device must be configured for wireless access to the network containing the
KFS server.) Once the library calls the delegate, and the login completes without error, the
application displays the elapsed time, and advances to the Synchronization phase.
Synchronization
The application uses this phase to synchronize with the KFS server to obtain the case index
fields associated with the driver's license case type. This phase creates a new KFS case, and
then waits for the fetchCaseCompleted delegate to indicate when the case object is ready for
use. This phase normally completes quickly, but does require communication with the KFS
server to obtain all the fields associated with the case. The case type index fields include a
unique Photo Id. The application fills in a unique GUID in the Photo ID field of the case so
that it can be associated with the extracted data from the OCR service. Once the library calls
the delegate, and the synchronization completes without error, the application displays the
elapsed time, and advances to the Acquisition phase to get an image to process.
Acquisition
In this phase, the application acquires an image by calling the addDocument API method to
obtain a driver's license image for processing. If you selected the photo roll for your image
source, then this phase will display a UI to choose a photo for processing. If you selected
the camera for the image source, then the library displays the standard camera screen to
take a picture with the camera. Once you choose an image the library returns control to
the application via the viewDidLoad delegate, which advances the application to the next
Conversion phase. If you selected automatic processing from the settings screen, then the
library automatically processes the image using the image processing settings associated
with the case as obtained from KFS. The library automatically displays the EVRS processing
progress bar in the KMC library UI screen. After processing completes, control returns to
the application. If image quality feedback is specified, then the library creates the preview,
displays the EVRS processing progress bar for the preview, then displays the green border
around the document edges, and indicates if the image is blurry under saturated or over
saturated. If you select continue, the image is used for subsequent processing. If you select
cancel, then the library launches the correct UI to select another photo or take a new one.
Conversion
If automatic processing is turned off, this phase processes the image and shows a progress
bar. The application calls the batchProcess method to process the image acquired. The library
in turn calls the processProgress delegate method to indicate the percent completion. The
application displays this percent in a progress bar associated with this phase. The multiple
delegate calls continue until 100% completion. As long as there is no processing error,
the application advances to the submission phase after recording the elapsed time for the
conversion process. In this case, the elapsed time includes the overhead of the processing and
feedback of the silent processing.
If automatic processing is turned on, then there are no delegates used, and the app advances
to the submission phase, and the elapsed time of automatic EVRS processing is included
as part of the untimed acquisition phase, because the app does not know how long it takes
Sample Applications
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
31
a user to select an image. Therefore, the resulting time reporting does not include time for
conversion.
Submission
This phase measures elapsed time of the silent submit call to send the processed image to
KFS. The submit method of the KFSCase object also sends the case data associated with the
image. The case includes the Photo Id for the image. The sample application displays an
error if the case type does not include a PhotoId index field. Once the KFS server gets the
image, and it finds that this is a license type case, it launches the Kofax KCDLP process to
inspect the license image and extract all the data fields for the license. Meanwhile, the sample
application responds to the submission. When submission completes, the library calls the
submitCompleted delegate to indicate if the submit passed or failed. If the submit completes
without error, the application displays the elapsed time for the submission in the UI, and then
advances to the Detection phase. If the submit fails, the application shows the phase in red,
and displays text or a pop up describing the reason for the submission error.
Detection
This phase runs in parallel to the KFS server OCR extraction process. The detection phase
prompts you to take a picture of the back side of the driver's license in order to find
the barcodes and tabulate the data contained in the barcodes found. The app uses the
addDocument API method on a nonKFSCase object. The image acquired is only used to find
any barcodes, and the image is discarded. The image is not included in the case submission.
Up to two barcodes are tabulated and the barcode data for each is saved in memory for
display with the extraction results, during the Verification phase.
If automatic processing is turned on, then there are no delegates used, and the app advances
to the extraction phase, and the elapsed time of automatic EVRS processing is included as
part of acquiring the back image. Therefore, the resulting time reporting does not include
time for processing the back side image.
Extraction
For the sake of this sample program, the application accesses the Kofax KC-DL Project
(KCDLP) service using a URL that includes the server name, port and photoID. This service
allows the sample application to communicate with KCDLP. The KFS server handles starting
KCDLP extraction as a result of the case submission. The process goes on in parallel to
completing the Detection phase and the starting the extraction phase. The KCDLP software
analyzes the processed driver's license image for typical license data. KCDLP knows to
look for license data because the submitted case indicates a license image. The license data
includes the license number, the name, gender, address, city, state, zip code and date of birth
from the license image. When the extraction process completes, the server stores the data in a
database, and associates the Photo Id with that data.
The application's extraction phase uses network services to poll for the extraction results
using a web service URL. The application obtains this URL from the settings file. The
application appends the Photo Id string to the end of the URL, and uses a network get data
request. The server responds with a JSON data packet. If the packet includes the phrase
"Wait!" as a data item, it indicates that the server does not have the extracted data stored in
the database. The application will then retry the get data request, and indicate in the UI that
another retry is being done and indicates the count of retries performed. A retry is performed
every half second. This retry loop continues indefinitely until one of two things happens:
user cancels the process or the process completes. If you tap the Cancel button in the UI, the
application indicates that the extraction was cancelled, shows the phase in red and advances
to the completion phase to indicate the process failed. Otherwise the application waits for a
Sample Applications
32
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
valid data response. The extraction process may take about 10 seconds or less normally, but
depending on case load and network activity, you may experience some delays.
Once the extracted data is available, the application saves the data in a second case for
display. The application creates a case object from an internal Non-KFS case XML string
obtained from a file associated with the sample application's bundle. The XML string includes
case index fields, and one field is associated with each data item expected to be extracted from
the driver's license image. The application parses the JSON replay packet, extracts each data
item found within it, and copies that data item to the appropriate case field.
The settings file in the application's bundle includes a typical JSON data packet. This packet is
exclusive to and unique to the KCDLP service. In your own implementation of the extraction
process, you may use a different approach other than a web service polling sequence. But
this Extraction Phase demonstrates a suggested way to use an external service to provide the
extraction process and data. If your implementation uses a JSON reply, you would need to
replace the sample application process with your own JSON parsing process.
Once the application stores the driver's license data in the new case, it indicates the phase
completed normally, and the app displays the elapsed time for the process and advances to
the Verification phase.
Verification
The Verification phase is intended for you to see the final license data, and allows you to
any fields that may be incorrect. All the real-time actual extracted data is shown in a case
information screen. The app copied data from the JSON reply packet into the appropriate
fields of the case during the extraction phase. The app also includes the bar code information
from the back side of the license, if any, and shows the bar code type found and the bar code
data. Up to two bar codes are included in the verification view.
The application then calls the showCaseInformationScreen method on the NonKfsCase object
created with the XML string in the Extraction phase. The application pauses for you to tap on
either the Save or Cancel button. When you tap the Save button, the phase completes, and the
application transitions to the Notification phase. Typically a verification screen would shows
all the extracted data.
Notification
The purpose of the notification phase is to send you an email with all the test results. The
application creates an email message and sends the email to the address specified in the
settings file. The body of the email includes information about all of the phases, the elapsed
time for each phase and the PhotoID used with the case. The email body also shows all of
the driver's license data extracted from the image, but it does not include the processed
image. The email includes the bar code information found. If the bar code data is binary, it is
encoded in base64 for you to decode in your own process. You can review the email message,
add to it if necessary, and then send or cancel the email. If you send the email, the process
completes normally and advances to the Completion phase.
The sample application will not send an email if any other phase leading up to this phase
failed.
Completion
The completion phase shows the final results, if the process completed normally or failed.
The total time for the process is show for all the phases that were timed. The application uses
this phase to do some housekeeping, and release objects used in the process. The application
Sample Applications
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
33
advances directly to the Completion phase if an error is detected and the failing phase is
indicated in red.
Building the Driver’s License Demo Application iOS Sample Application
The following sections provide an overview of building the sample application. This section
assumes you are already familiar with XCode development and the user interface.
Zip File Contents
Copy the KofaxMobileSDK-1.2.0.ZIP contains all the files associated with the SDK. Copy
this file from the SDK to a folder on your Mac. When unzipped, there will be almost 9000
items, about 250 Mb. Navigate into the iOS folder. The iOS folder contains these sub folders,
DemoApps, Docs, EVRS_lib and KofaxMobileCaptureSDK. The following sections describe
these iOS folders.
DemoApps
This folder contains the source code for the two sample applications included with the SDK.
The KMCDLDemo-iOS.zip contains the source code for this application and is described in
this document.
Docs
The Docs folder contains several SDK documents, a developer guide, and an API guide for
the actual iOS implementation, describing the iOS API classes, methods and properties. To
launch the API reference, use the Welcome-iOS.htm file on your development system
EVRS_lib
The EVRS_lib folder contains folders for the EVRS library and API for iOS. The bin folder
contains the libKfxEVRSi.a static library that you can include in an iOS application to directly
interface with EVRS image processing library functions. The VRSDemo example application
demonstrates how to use this static library, which is described in another document.
The folder named "include" contains the license file and a kfxVRSMbl.h file that describes the
API methods in the EVRS static library.
The samples folder contains the source code for the VRSDemo application, which is described
in another document.
KofaxMobileCaptureSDK
This folder contains the KMCSDK-iOS.zip file. This file contains the framework for the KMC
Library. Unzip this file on your Mac to preserve the links on the Mac to the Kofax Mobile SDK
framework and bundle. When you unzip this file, you will see these two sub folders:
KMCSDK.framework
: This is the framework that you would integrate into your own application. This
framework contains all the header files you need to interface with the framework for
the KMC Library. Launch the API reference guide, using the "Welcome-iOS.htm" file to
review the library API and the classes included in the framework.
KMCSDKBundle.bundle
Include this bundle in your own application to integrate it with your own application.
Note that the framework and bundle are automatically included for you within the
Driver’s License Demo Application source code.
Sample Applications
34
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
Installing the Driver’s License Demo Application Sample Code
Copy the KofaxMobileSDK-1.2.0.ZIP file from the SDK to another folder and unzip it.
Navigate into the iOS folder and then the DemoApps folder. Unzip KMCDLDemo-iOS.zip.
The KMCDLDemo application includes the KMCSDK framework and bundle folders with the
zip file including the source code for KMCDLDemo.
Folder
Description
KMCDLDemo
The source code for the application.
KMCDLDemo.xcodeproj
The XCode project folder. Click on this folder to launch XCode and
open the project file.
KMCSDK.framework
The KMC library framework for inclusion in the KMCDLDemo
application or your own application.
KMCSDKBundle.bundle
The KMC Library bundle for the KMC library use.
Building and Testing with Driver’s License Demo Application
Once you launch XCode using the project file in the KMCDLDemo folder, XCode will show
the project files and settings. From the XCode title bar, use the Product tab to prepare for
testing. Select Clean to ensure you do not have any old objects from a previous build, and
then select Build to build the source code. XCode should build without any errors. If you get
linker errors, make sure you have included all the iOS frameworks needed with the Kofax
Mobile SDK.
Attach the iOS device for which you have already setup your provisioning profile. Check in
the top left corner of XCode, you should see scheme and breakpoints. Right above scheme,
is a drop down to select the device you want to test with. If you see simulator then click
on the drop down and select the device you want to use. Then you can click on Product
Run, and then XCode will download the sample application to your iOS device. You can set
breakpoints in the source code and see how it interfaces with the Kofax SDK library.
The sample application generates sufficient logging information during debugging to
understand what the code is doing. To view the logging information, select Show the Logging
Navigator box icon on the left-hand panel. KMCDLDemo uses a user interface from which
you select options and buttons to launch KMC library internal screens. The home screen is
shown when you start the application.
Source Code File Descriptions
The Driver’s License Demo Application folder contains the source code for the sample
application. The following provides a brief overview of the files.
File
Description
networkManager.h and m
These files define a class that handles the interface to KCDLP
OCR service, and contains utility methods to manage the
network access.
kfxAppDelegate.h and m
These files contain the standard iOS application delegate
components for a typical application.
Sample Applications
Kofax Mobile SDK Kofax Mobile SDK Developer's Guide
35
File
Description
kfxMainViewController.h, m and .Xib
This set of files describes the main home screen and the