MRZ Reader SDK: kds-mrz-reader-sdk-ios-release

Readme for framework version: 1.6.x

This repo contains the iOS framework kds-mrz-reader-sdk-ios which is responsible for scanning the MRZ (Machine Readable Zone) on e.g. passports.

The MRZ reader could detect and parse the five main types of Machine Readable Travel Documents, according to ICAO:

Example App

Inside the folder Example there is an Xcode project, that shows the usage of the SDK.

Example App

Preconditions

Installation

The easiest way is to use CocoaPods. It takes care of all required frameworks and dependencies. Just add this line to your Podfile

pod 'kds-mrz-reader-sdk-ios-release',
    :git => 'https://git.yourdomain.com/kds-mrz-reader-sdk-ios.git'

or (for local usage)

pod 'kds-mrz-reader-sdk-ios-release', :path => '../kds-mrz-reader-sdk-ios'

As this SDK is build as a dynamic framework, you have to use the target parameter use_frameworks! in the Podfile. After pod install the sdk is ready to use in your app.

Usage

To use the SDK, you have to import the module:

import kds_mrz_reader_sdk_ios

To use the MRZ reader in your app, instantiate the viewcontroller using the static function createInstance:

let kdsMrzScanner = KDSMrzRootVC.createInstance(delegate: self)
self.present(kdsMrzScanner, animated: true, completion: nil)

The mrzVC will call the related delegate methods defined in the protocol KDSMrzScannerVCDelegate:

extension YourViewController : KDSMrzScannerVCDelegate {
  func scanMrzDidComplete(withMrzInfo mrzInfo: MrzInfo) {
    debugPrint("scanMrzDidComplete: \(mrzInfo)")
  }
  
  func scanMrzDidComplete(withIdlInfo idlInfo: IdlInfo) {
    debugPrint("scanMrzDidComplete: \(String(reflecting: idlInfo))")
  }

  func scanMrzDidComplete(withParsingError error: MrzParserError) {
    debugPrint("scanMrzDidCompleteWithError: \(error)")
  }

  func scanMrzDidCancel() {
    debugPrint("scanMrzDidCancel: User cancelled Scan")
  }

  func scanMrzDidSkipScanning() {
    debugPrint("scanMrzDidSkipScanning: User skipped Scan")
  }
}

Customization

The appearance of the mrz reader vc could be modified using a configuration struct.

...
  let configuration = KDSMrzScannerConfiguration(
      navBarColor: UIColor.darkGray,
      navBarTintColor: UIColor.white,
      displayTopInfo: KDSMrzHintText.text(hintText: "Customized Guidance Text"),
      displaySkipButton: true,
      shouldRotateImage: true,
      detectionMode: KDSMrzDetectionMode = .mrzTextAndPdf417
  )

  //present the KDSMrzRootVC modally
  let kdsMrzScanner = KDSMrzRootVC.createInstance(
    delegate: self,
    withConfiguration: configuration)

  self.present(kdsMrzScanner, animated: true, completion: nil)
...   

To hide the top info bar completely, just use the ...displayTopInfo: KDSMrzHintText.hidden enum value.

Used structs and enums

1. Success Case: MrzInfo

The delegate method scanMrzDidComplete(withMrzInfo mrzInfo: MrzInfo) contains a struct of type MrzInfo as result. This struct contains all parsed values from the MRZ:

public struct MrzInfo {
  public let documentCode: String
  public let documentNumber: String
  public let surname: String
  public let givenNames: String
  public let gender: String
  public let dateOfBirth: Date
  public let dateOfExpiry: Date
  public let nationality: String
  public let issuingState: String
  public let optionalData: String
}

2. Error Case: MrzParserError

If there was a problem parsing the mrz the delegate method scanMrzDidComplete(withParsingError error: MrzParserError) contains an enum which specifies the problem:

public enum MrzParserError: Error {
  case invalidCheckSum(field: MrzParserCheckSumField)
  case invalidLength
  case invalidStructure
  case notRecognized
}

If the error is from type invalidCheckSum it contains the field for which the checksum doesn't match:

public enum MrzParserCheckSumField {
  case documentNumber
  case birthDay
  case expiryDay
  case composite
  case personalNumber
}

Additional hints

1. NSCameraUsageDescription in Host App

As the KDSMrzScannerVC needs camera access, the host app have to put a usage description inside it's Info.plist, otherwise the app crashes. Please add a string like this to the Info.plist of the host app:

<key>NSCameraUsageDescription</key>
<string>$(PRODUCT_NAME) needs camera access to scan your documents.</string>