Skip to main content

IOS Integration

Please follow these steps for integrating OCR Lite xcframework.

note

You can find sample project containing complete integration of SDK here (requires access).

Integration Guide (Swift)​

You can add the OcrLite framework to your project using either CocoaPods.

Pods Linking​

For linking OcrLite library using CocoaPods you can add either:

  • OcrLite repository link with version tag in your Podfile
pod 'Ocr', :git => "https://gitlab.com/fetchsky/peekaboo-connect-studio/identity/ocr-lite-pod", :tag => "vX.X.X"

Use the latest communicated version of the framework.

  • Or place OcrLite directory in your project root and its path in your Podfile
pod 'Ocr', :path => "./OcrLite"

Run pod install in your terminal.

Adding via Xcode​

  1. In Xcode, open File ▸ Add Package Dependencies…

  2. Paste the package URL into the search field:

    https://gitlab.com/fetchsky/peekaboo-connect-studio/identity/ocr-lite-swift-package.git

  3. For Dependency Rule, select Exact Version and enter the latest communicated version tag, then click Add Package.

  4. When prompted, add the Ocr library product to your app target.

Use the latest communicated version of the framework.

Adding via Package.swift​

If your project declares dependencies in a Package.swift manifest, add the package to your dependencies array:

dependencies: [
    .package(
        url: "https://gitlab.com/fetchsky/peekaboo-connect-studio/identity/ocr-lite-swift-package.git",
        exact: "X.X.X"
    )
]

Then add the Ocr product to the target that uses it:

.target(
    name: "YourTarget",
    dependencies: [
        .product(name: "Ocr", package: "ocr-lite-swift-package")
    ]
)

Using Library​

Link Ocr in your ViewController

import Ocr

Conform to OcrControllerDelegate protocol in your class to handle events and results related to the framework.

class ViewController: OcrControllerDelegate { ....

Initialize OcrViewController​

Create an instance of OcrViewController with the CNIC number to validate against. See Initialization Parameters for the full list of supported parameters.

let ocrController = OcrViewController(cnicNumber: "your_cnic_number")

Setup and Display​

// Set Delegate
ocrController.delegate = self

// Add as Child View Controller
addChild(ocrController)

// Configure View Frame
ocrController.view.frame = CGRect(x: 0, y: 0, width: view.bounds.width, height: view.bounds.height)

// Add as Subview
view.addSubview(ocrController.view)

// Notify Child View Controller
ocrController.didMove(toParent: self)

Event Handlers​

Implement the required delegate methods:

class ViewController: OcrControllerDelegate {

    func handleInfo(message: String) {
        // Handle informational messages from the framework
        print("Info: \(message)")
    }

    func handleError(code: String) {
        // Handle errors from the framework
        // Error codes can be: initialization_error, invalid_source, model_error, no_camera, etc.
        print("Error: \(code)")

        // Remove the OCR controller view when error occurs
        ocrController?.view?.removeFromSuperview()
    }

    func handleResponse(identityNumber: String, frontImage: String, backImage: String, documentType: DocumentType, distance: Double, extractedData: ExtractedData) {
        // Handle successful OCR response
        // identityNumber: Extracted identity number from the document
        // frontImage: Base64 encoded front image of the document
        // backImage: Base64 encoded back image of the document
        // documentType: Type of document detected
        // distance: Distance of the extracted CNIC from the provided CNIC (lower = closer match)
        // extractedData: Structured fields parsed from the front card by the SDK
        //                (see the extractedData fields below). Empty when nothing
        //                could be recognized or parsed — it never throws.

        print("Identity Number: \(identityNumber)")
        print("Document Type: \(documentType)")
        print("Distance: \(distance)")
        print("Extracted Data: \(extractedData.toDictionary())")

        // Remove the OCR controller view after successful processing
        ocrController?.view?.removeFromSuperview()
    }
}

Extracted Data​

extractedData is an ExtractedData value parsed by the SDK from the front card using on-device text recognition (Apple Vision). It is populated for new (chip-based) CNICs only; old cards have no machine-readable text fields and yield an empty value. All parsed fields are optional String? — a field that could not be recognized is left nil, and a fully failed recognition yields an empty value (it never throws). The raw field holds the complete unparsed text as recognized and is populated whenever any text was recognized, even when no individual field could be parsed. Call toDictionary() to get only the populated fields as a [String: String].

public struct ExtractedData {
    public var name: String?
    public var fatherName: String?
    public var identityNumber: String?
    public var dateOfBirth: String?   // DD.MM.YYYY
    public var dateOfIssue: String?   // DD.MM.YYYY
    public var dateOfExpiry: String?  // DD.MM.YYYY
    public var gender: String?        // "M" | "F" | "X"
    public var country: String?
    public var raw: String?           // Full unparsed OCR text (present whenever any text was recognized)

    public func toDictionary() -> [String: String]
}

See the extractedData object reference for a description of each field.

Complete Implementation Example​

class ViewController: UIViewController, OcrControllerDelegate {

    var ocrController: OcrViewController? = nil

    @IBAction func launchOCR(_ sender: Any) {
        ocrController = OcrViewController(cnicNumber: "your_cnic_number")

        if let ocrController = ocrController {
            ocrController.delegate = self
            addChild(ocrController)
            ocrController.view.frame = CGRect(x: 0, y: 0, width: view.bounds.width, height: view.bounds.height)
            view.addSubview(ocrController.view)
            ocrController.didMove(toParent: self)
        }
    }

    // Implement delegate methods as shown above
}

Updating Info.plist​

Add Privacy - Camera Usage Description in your app's Info.plist to allow access to camera.