Android Integration

This guide will help you integrate the OCR Lite SDK into your Android application.

note

You can find sample project containing complete integration of SDK here.

Installation

info

OCR Lite SDK is built with the support for minSdk 23 and compiled on JAVA 17.

Prerequisites

Make sure you are provided with the following required credentials for integration:

S3_BUCKET_ID, S3_ACCESS_KEY, S3_SECRET_KEY and the latest communicated version.

Implementation

Include AWS maven repository (where the sdk is deployed) at the project's dependency management.

 repositories {
        ...
        maven {
            url 's3://' + S3_BUCKET_ID
            credentials(AwsCredentials) {
                accessKey S3_ACCESS_KEY
                secretKey S3_SECRET_KEY
            }
        }
    }

Add the following dependency in project's app/build.gradle:

dependencies {
    ...
    implementation 'com.fetchsky.ocrlite:sdk:<version-code>'
}

Launch SDK

Create an intent and launch OcrActivity. See Initialization Parameters for the full list of supported parameters.

val intent = Intent(this, com.fetchsky.ocrlitesdk.OcrActivity::class.java)
intent.putExtra(OcrCommunication.ParamKey.IDENTITY_NUMBER.value, cnicNumber)
startActivity(intent)

Receive events

Receive messages sent from OCR activity and handle them accordingly.

1. Create a Broadcast Receiver

Events are posted with a standard receiver action:

OCR_RECEIVER_ACTION = "com.fetchsky.ocrlitesdk.OCR_MESSAGE"

Create receiver class:

private val ocrMessagesReceiver = object : BroadcastReceiver() {
        override fun onReceive(context: Context?, intent: Intent?) {
            if (intent?.action.equals(OCR_RECEIVER_ACTION)) {
                 handleResult(intentType, payload) 
            }  
        }
    }
}

2. Initialize the receiver

Initialize OCR broadcast receiver at launch:

ContextCompat.registerReceiver(
    this,
    ocrMessagesReceiver,
    IntentFilter(OCR_RECEIVER_ACTION),
    ContextCompat.RECEIVER_EXPORTED
)

Prefer using ContextCompat receiver registration for lower api level support.

3. Handle results

info

Event sent from OCR Activity will be one of the defined types listed in Response Events.

Extract the enum of posted event type as follows and handle them as per the need.

fun handleResult(type: String, payload: Bundle) {
    val messageTypes = OcrCommunication.PostMessage.entries.associateBy { it.name }
    val event = messageTypes[type]
    ...
}

Reading extractedData

On the OCR_SUCCESS event, the SDK includes the parsed CNIC fields — plus a raw entry holding the full unparsed OCR text — as a nested Bundle under the extractedData key. Text recognition and parsing happen inside the SDK. It is empty for old cards, or when no text could be recognized (it never causes a failure). See the extractedData object reference for the full list of fields.

val extracted = payload.getBundle("extractedData") ?: Bundle()

val name = extracted.getString("name")            // null if absent
val cnic = extracted.getString("identityNumber")
val raw = extracted.getString("raw")              // full unparsed OCR text
// ...other fields: fatherName, dateOfBirth, dateOfIssue, dateOfExpiry, gender, country