DOT iOS Document library

v8.4.0

Introduction

DOT iOS Document provides components for document capture and related functionalities which are easy to integrate into an iOS application.

Requirements

Xcode 15.1+
iOS 12.0+
Swift or Objective-C
CocoaPods or Swift Package Manager

DOT iOS Document is distributed as a binary XCFramework - DotDocument.xcframework with its dependencies stored in our public github repository. It can be easily integrated into Xcode project in: Project → Package Dependencies.

Use https://github.com/innovatrics/dot-ios-sdk-spm.git repository and choose version you want to use. There you can select DotDocument package. All the required dependencies will be downloaded with the selected package.

Cocoapods

DOT iOS Document is distributed as a XCFramework - DotDocument.xcframework using Cocoapods with its dependencies stored in our public github repository. It can be easily integrated into Xcode with custom definition of podspecs. First step is to insert following line of code on top of you Podfile.

Podfile

source 'https://github.com/innovatrics/innovatrics-podspecs'

Then DOT iOS Document dependency must be specified in Podfile. Dependencies of DOT iOS Document will be downloaded alongside it.

Podfile

source 'https://github.com/innovatrics/innovatrics-podspecs'

use_frameworks!

target 'YOUR_TARGET' do

pod 'dot-document'

end

In case of CocoaPods problem with pod install, try to clone the private pod repository manually.

pod repo remove innovatrics
pod repo add innovatrics https://github.com/innovatrics/innovatrics-podspecs

Supported Architectures

DOT iOS Document provides all supported architectures in the distributed XCFramework package. Device binary contains: arm64. Simulator binary contains: x86_64, arm64.

Licensing

In order to use DotSdk in your iOS application, it must be licensed. The license can be compiled into the application as it is bound to Bundle Identifier specified in the General tab in Xcode.

The Bundle ID can be also retrieved in runtime by calling DotSdk.shared.bundleId.

In order to obtain the license, please contact your Innovatrics’ representative specifying Bundle ID. After you have obtained your license file, add it to your Xcode project and use it during the DotSdk initialization, as shown below.

Permissions

Set the following permission in Info.plist:

Info.plist

<key>NSCameraUsageDescription</key>
	<string>Your usage description</string>

Basic Setup

Initialization

Before using any of the components, you need to initialize DOT SDK with the license and DotDocumentLibrary object.

DOT SDK Sample shows how to initialize DOT SDK with DotDocumentLibrary. DotSdk.shared.initialize() method should be called on background thread.

Keep in mind that if you try to use any feature which was not added during initialization DOT SDK will generate fatal error.

Deinitialization

When you have finished using the DOT iOS Document, it is usually a good practice to deinitialize it in order to free the memory. You can deinitialize DOT iOS Document only after the complete process is finished and not within the life cycle of individual components. This can be performed using the DotSdk.shared.deinitialize() method. If you want to use the DOT iOS Document components again, you need to call DotSdk.shared.initialize() again.

Logging

DOT iOS Document supports logging using a global Logger class. You can set the log level as follows:

import DotDocument

Logger.logLevel = .debug

Log levels:

debug
info
warning
error
none

Each log message contains DotDocument tag. Keep in mind that logging should be used just for debugging purposes.

Components

Overview

DOT iOS Document provides both non-UI and UI components. Non-UI components are aimed to be used by developers who want to build their own UI using the DOT iOS Document functionality. UI components are build on top of non-UI components. Components having UI are available as UIViewController classes and can be embedded into the application’s existing UI or presented using the standard methods.

List of Non-UI Components

DOCUMENT DETECTOR: A component for performing document detection on an image.
IMAGE PARAMETERS ANALYZER: A component for computing image parameters such as sharpness, brightness or hotspots score.
IMAGE PERSPECTIVE WARPER: A component for warping the perspective of an image according to the detected document corners.
DOCUMENT AUTO CAPTURE CONTROLLER: A component for capturing good quality images suitable for optical character recognition.
MACHINE READABLE ZONE READER: A component for reading Machine Readable Zone (MRZ).

List of UI Components

DOCUMENT AUTO CAPTURE: An visual component for capturing good quality images suitable for optical character recognition.

Non-UI Components

Document Detector

The DocumentDetector class provides a document detection functionality.

Create a DocumentDetector:

let documentDetector = DocumentDetector()

To perform detection, call the following method on the background thread:

let documents = try documentDetector.detect(bgraRawImage: bgraRawImage, limit: 1)

Image Parameters Analyzer

The ImageParametersAnalyzer class provides an image parameters analysis functionality.

Create ImageParametersAnalyzer:

let imageParametersAnalyzer = ImageParametersAnalyzer()

To perform analysis, call the following method on the background thread:

let imageParameters = try? imageParametersAnalyzer.analyze(bgraRawImage: bgraRawImage)

Image Perspective Warper

The ImagePerspectiveWarper class provides perspective warping functionality.

Create ImagePerspectiveWarper:

let imagePerspectiveWarper = ImagePerspectiveWarper()

To perform perspective warping, call the following method on the background thread:

let warpedBgraRawImage = try? imagePerspectiveWarper.warp(bgraRawImage: bgraRawImage, detectionPosition: detectionPosition, targetImageSize: targetImageSize)

Document Auto Capture Controller

The DocumentAutoCaptureController class provides a stateful document auto capture functionality.

You can configure DocumentAutoCaptureController using DocumentAutoCaptureController.Configuration.

Create DocumentAutoCaptureController:

let configuration = try! DocumentAutoCaptureController.Configuration(
            validators: validators,
            minValidFramesInRowToStartCandidateSelection: 2
            candidateSelectionDurationMillis: 1000,
            detectionNormalizedRectangle: detectionNormalizedRectangle,
            isMrzReadingEnabled: false)
let controller = DocumentAutoCaptureController(configuration: configuration)

You can use detectionNormalizedRectangle to specify the region in the input image which will be used for document detection. For example, if you want to ignore top 30% and bottom 30% of the input image, you can do it as follows:

let detectionNormalizedRectangle = RectangleDouble(left: 0, top: 0.3, right: 1.0, bottom: 0.7)

If detectionNormalizedRectangle is set to nil(default) the full input image is used for document detection.

To capture a good quality document image, repeatedly call the process() method using the camera frames:

let processingResult = try documentAutoCaptureController.process(bgraRawImage: bgraRawImage, timestampMillis: timestampMillis)

The controller evaluates the document image requirements for each frame. Once the controller detects enough (minValidFramesInRowToStartCandidateSelection) valid frames in a row, candidate selection is started with duration of candidateSelectionDurationMillis milliseconds. After the candidate selection is finished, the best document image candidate is returned and the document auto capture process is over.

Machine Readable Zone Reader

The MrzReader class provides a Machine Readable Zone (MRZ) reading functionality.

Create MrzReader:

let mrzReader = MrzReader()

To read a MRZ, call the following method on the background thread:

let result = mrzReader.read(bgraRawImage: bgraRawImage, document: document)

Or alternatively, if you know the travel document type, call this method to increase the precision of the reading process:

let result = mrzReader.read(bgraRawImage: bgraRawImage, document: document, travelDocumentType: travelDocumentType)

The document argument is a product of either Document Detector component, Document Auto Capture Controller component or Document Auto Capture UI component.

The result of successful MRZ reading contains travel document type and machine readable zone. If MRZ reading was not successful, the result will contain an error and travelDocumentType and/or machineReadableZone may be nil.

UI Components

Camera handling

Camera lifecycle

DOT iOS Document view controller will start the camera in viewWillAppear(:) lifecycle method. DOT iOS Document view controller will stop the camera in viewDidDisappear(:) lifecycle method.

Camera permission

DOT iOS Document view controller will check the camera permission right before the camera is started. If the camera permission is granted the view controller will start the camera. If the camera permission is denied the view controller will call *ViewControllerNoCameraPermission(:) callback. Implement this callback in order to navigate the user further in your app workflow. If the camera permission is not determined the view controller will use iOS API - AVCaptureDevice.requestAccess(for: .video) method to request the camera permission. This method will present the system dialog to the user of the app. The user of the app can grant or deny the camera permission and then the view controller will proceed the same way as it does during the camera permission check as was explained at the beginning of this section.

View Controller Configuration

Components containing UI are embedded into the application as view controllers. All view controllers can be embedded into your own view controller or presented directly. Each view controller can be configured using its *Configuration class and each view controller can have its appearance customized using its *Style class.

To present view controller:

let controller = DocumentAutoCaptureViewController.create(configuration: .init(), style: .init())
controller.delegate = self
navigationController?.pushViewController(controller, animated: true)

To embed view controller into your view controller:

override func viewDidLoad() {
    super.viewDidLoad()

    addChild(viewController)
    view.addSubview(viewController.view)
    viewController.view.translatesAutoresizingMaskIntoConstraints = false
    viewController.didMove(toParent: self)

    NSLayoutConstraint.activate([
        viewController.view.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
        viewController.view.leadingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.leadingAnchor),
        viewController.view.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor),
        viewController.view.trailingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.trailingAnchor)
    ])
}

Safe Area

DOT iOS Document view controllers ignore safe area layout guide when they layout their subviews. Therefore, for example if you push DOT iOS Document view controller using UINavigationController, you will get incorrect layout. If you want to respect safe area layout guide, you should embed DOT iOS Document view controller in a container view controller and setup the layout constraints accordingly.

Document Auto Capture

The view controller with document placeholder which is used for capturing document images.

You can configure DocumentAutoCaptureViewController using DocumentAutoCaptureViewController.Configuration. You can customize the appearance of DocumentAutoCaptureViewController using DocumentAutoCaptureViewController.Style. You can handle the DocumentAutoCaptureViewController events using its delegate DocumentAutoCaptureViewControllerDelegate.

To create DocumentAutoCaptureViewController:

let viewController = DocumentAutoCaptureViewController.create(configuration: .init(), style: .init())
viewController.delegate = self
present(viewController, animated: true)

In order to start the document auto capture process call the start() method.

In case you want to handle detection data, implement documentAutoCaptureViewController(:processed:) delegate callback. This callback is called with each processed camera frame. When the document auto capture process finishes successfully, the result will be returned via the documentAutoCaptureViewController(:captured:) callback.

In case you want to force the capture event, call the requestCapture() method. The most recent image will be returned via the documentAutoCaptureViewController(:captured:) callback asynchronously.

Call start() method again in case you need to start over the document auto capture process (e.g. you want to capture both sides of the document, one after another). You can also call start() method to stop and start over ongoing process as well.

In case you want to stop the document auto capture process prematurely, call the stopAsync() method. The callback in the method argument indicates that the processing is over.

Quality Attributes of the Output Image

You may adjust quality requirements for the output image. To perform this, you can use pre-defined builders - QualityAttributeThresholds.Builder - from QualityAttributeThresholdPresets with recommended thresholds and pass it to DocumentAutoCaptureViewController.Configuration by setting the qualityAttributeThresholds. You can also create your own instance of QualityAttributeThresholds from scratch or based on pre-defined builders according to your needs.

Possible ways how to create QualityAttributeThresholds:

// The standard preset
let standard = DocumentAutoCaptureViewController.Configuration.QualityAttributeThresholdPresets.standard.build()

// Modified thresholds based on the standard preset
let modified = try DocumentAutoCaptureViewController.Configuration.QualityAttributeThresholdPresets.standard
        .minConfidence(minConfidence)
        .minSharpness(nil)
        .build()

// Custom thresholds
let custom = try DocumentAutoCaptureViewController.Configuration.QualityAttributeThresholds.Builder()
        .minConfidence(minConfidence)
        .minSharpness(minSharpness)
        .build()

Available presets (pre-defined builders with thresholds) in QualityAttributeThresholdPresets:

standard - The resulting image suitable for evaluation on Digital Identity Service. See the thresholds.

Customization of UI Components

Localization

String resources can be overridden in your application and alternative strings for supported languages can be provided following these two steps:

Add your own Localizable.strings file to your project using standard iOS localization mechanism. To change a specific text override corresponding key in this Localizable.strings file.
Set the localization bundle to the bundle of your application (preferably during the application launch in your AppDelegate).

Use this setup if you want to use standard iOS localization mechanism, which means your iOS application uses system defined locale.

import DotDocument

Localization.bundle = .main

Custom Localization

You can override standard iOS localization mechanism by providing your own translation dictionary and setting the Localization.useLocalizationDictionary flag to true. Use this setup if you do not want to use standard iOS localization mechanism, which means your iOS application ignores system defined locale and uses its own custom locale.

import DotDocument

guard let localizableUrl = Bundle.main.url(forResource: "Localizable", withExtension: "strings", subdirectory: nil, localization: "de"),
      let dictionary = NSDictionary(contentsOf: localizableUrl) as? [String: String]
else { return }

Localization.useLocalizationDictionary = true
Localization.localizationDictionary = dictionary

Localizable.strings

"dot_document.document_auto_capture.instruction.brightness_too_high" = "Less light needed";
"dot_document.document_auto_capture.instruction.brightness_too_low" = "More light needed";
"dot_document.document_auto_capture.instruction.document_out_of_bounds" = "Center document";
"dot_document.document_auto_capture.instruction.document_does_not_fit_placeholder" = "Center document";
"dot_document.document_auto_capture.instruction.document_not_detected" = "Scan document";
"dot_document.document_auto_capture.instruction.size_too_small" = "Move closer";
"dot_document.document_auto_capture.instruction.hotspots_score_too_high" = "Avoid reflections";
"dot_document.document_auto_capture.instruction.mrz_not_present" = "Scan valid machine readable document";
"dot_document.document_auto_capture.instruction.mrz_not_valid" = "Scan valid machine readable document";
"dot_document.document_auto_capture.instruction.sharpness_too_low" = "More light needed";
"dot_document.document_auto_capture.instruction.candidate_selection" = "Hold still...";

Common Classes

`ImageSize`

Class which represents a size of an image. To create an instance:

let imageSize = ImageSize(width: 100, height: 100)

`BgraRawImage`

Class which represents an image.

To create an instance from CGImage:

let bgraRawImage = BgraRawImageFactory.create(cgImage: cgImage)

To create an instance from CIImage:

let bgraRawImage = BgraRawImageFactory.create(ciImage: ciImage, ciContext: ciContext)

To create CGImage from BgraRawImage:

let cgImage = CGImageFactory.create(bgraRawImage: bgraRawImage)

To create CIImage from BgraRawImage:

let ciImage = CIImageFactory.create(bgraRawImage: bgraRawImage, ciContext: ciContext)

`DetectionPosition`

Class which represents a document card corners. To create an instance:

let detectionPosition = DetectionPosition(topLeft: topLeft, topRight: topRight, bottomRight: bottomRight, bottomLeft: bottomLeft)

Security guidelines

The effectiveness of our video injection prevention feature can be strengthened if the application that implements it includes security recommendations from Apple: App integrity. Which ensure its authenticity that it was downloaded only from the App Store and the transmission of its sensitive data cannot be modified.

OWASP Mobile Application Security

We also strongly recommend following the OWASP Mobile Application Security guidelines. The OWASP Mobile Application Security (MAS) flagship project provides a security standard for mobile apps (OWASP MASVS) and a comprehensive testing guide (OWASP MASTG) that covers the processes, techniques, and tools used during a mobile app security test, as well as an exhaustive set of test cases that enables testers to deliver consistent and complete results.