Get Started With ID Capture
Quick overview
ID Capture provides the capability to scan personal identification documents, such as identity cards, passports or visas. In this guide you will learn step by step how to add ID Capture to your application. Roughly, the steps are:
Note
Using ID Capture at the same time as other modes (e.g. Barcode Capture or Text Capture) is currently not supported.
Create a SDCDataCaptureContext.
Access a SDCCamera.
Use SDCIdCaptureSettings to configure the scan process.
Implement an SDCIdCaptureListener to receive scan results.
Set up SDCDataCaptureView and SDCIdCaptureOverlay to see the camera feed and the scan UI.
Begin the scanning by adding an SDCIdCapture to SDCDataCaptureContext and starting a camera.
Prerequisites
Before starting with adding a capture mode, make sure that you have a valid Scandit Data Capture SDK license key and that you added the necessary dependencies. If you have not done that yet, check out this guide.
Note
You can retrieve your Scandit Data Capture SDK license key, by signing in to your account at ssl.scandit.com.
Internal dependencies
Some of the Scandit Data Capture SDK modules depend on others to work:
Module |
Dependencies |
---|---|
ScanditCaptureCore |
No dependencies |
ScanditBarcodeCapture |
|
ScanditParser |
No dependencies |
ScanditOCR |
No dependencies |
ScanditTextCapture |
|
ScanditIdCapture |
|
ScanditIDC |
No dependencies |
ScanditTXT |
No dependencies |
Please note that your license may support only a subset of ID Capture features. If you would like to use additional features please contact us at support@scandit.com.
Configure and Initialize the Library with loading status
Optionally you can also subscribe for the loading status of the library by simply attach a listener like this
Note
In order to have the progress information the library files must be served with the proper headers Content-Length and Content-Encoding if any compression is present. In case of missing information the percentage will be null
Create the Data Capture Context
The first step to add capture capabilities to your application is to create a new data capture context. The context expects a valid Scandit Data Capture SDK license key during construction.
self.context = DataCaptureContext(licenseKey: "-- ENTER YOUR SCANDIT LICENSE KEY HERE --")
Add the Camera
You need to also create the SDCCamera:
camera = Camera.default
context.setFrameSource(camera, completionHandler: nil)
let recommenededCameraSettings = IdCapture.recommendedCameraSettings
camera?.apply(recommenededCameraSettings)
Create ID Capture Settings
Use SDCIdCaptureSettings to configure the types of documents that you’d like to scan. Check SDCIdDocumentType for all the available options.
Warning
Using SDCIdDocumentTypeDLVIZ or SDCIdDocumentTypeIdCardVIZ together with any MRZ document (SDCIdDocumentTypeIdCardMRZ, SDCIdDocumentTypeVisaMRZ, SDCIdDocumentTypePassportMRZ, SDCIdDocumentTypeSwissDLMRZ) while SDCSupportedSidesFrontAndBack is enabled is currently not supported.
idCaptureSettings.supportedDocuments = [.idCardViz, .aamvaBarcode, .dlViz]
Implement the Listener
To receive scan results, implement SDCIdCaptureListener. A result is delivered as SDCCapturedId. This class contains data common for all kinds of personal identification documents. For more specific information use its non-nil result properties (for example SDCCapturedId.aamvaBarcodeResult).
extension IdCaptureViewController: IdCaptureListener {
func idCapture(_ idCapture: IdCapture, didCaptureIn session: IdCaptureSession, frameData: FrameData) {
let capturedId = session.newlyCapturedId
// The recognized fields of the captured Id can vary based on the type.
if capturedId.mrzResult != nil {
// Handle the information extracted.
} else if capturedId.vizResult != nil {
// Handle the information extracted.
} else if capturedId.aamvaBarcodeResult != nil {
// Handle the information extracted.
} else if capturedId.usUniformedServicesBarcodeResult != nil {
// Handle the information extracted.
}
}
func idCapture(_ idCapture: IdCapture,
didFailWithError error: Error,
session: IdCaptureSession,
frameData: FrameData) {
// Handle the error.
}
}
Create a new ID Capture mode with the chosen settings. Then register the listener:
idCapture = IdCapture(context: context, settings: idCaptureSettings)
idCapture.addListener(self)
Use a Capture View to Visualize the Scan Process
When using the built-in camera as frame source, you will typically want to display the camera preview on the screen together with UI elements that guide the user through the capturing process. To do that, add a SDCDataCaptureView to your view hierarchy:
let captureView = DataCaptureView(for: context, frame: view.bounds)
captureView.dataCaptureContext = context
captureView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
view.addSubview(captureView)
Then create an instance of SDCIdCaptureOverlay attached to the view:
let overlay = IdCaptureOverlay(idCapture: idCapture, view: captureView)
The overlay chooses the displayed UI automatically, based on the selected SDCIdCaptureSettings. If you prefer to show a different UI or to temporarily hide it, use SDCIdCaptureOverlay.setIdLayout:.
Turn on the Camera
Finally, turn on the camera to start scanning:
camera?.switch(toDesiredState: .on)
And this is it. You can now scan documents.
Capture both the front and the back side of documents
By default, when SDCIdDocumentTypeDLVIZ or SDCIdDocumentTypeIdCardVIZ are selected, Id Capture scans only the front side of documents. Sometimes however, you may be interested in extracting combined information from both the front and the back side.
Warning
Capturing combined information from both sides of documents is possible only for their parts intended to be read by humans (for example Visual Inspection Zone (VIZ) of a Machine-Readable Travel Document (MRTD)). It is currently not possible to obtain a single result that would additionally contain the information parsed from Machine-Readable Zones (MRZ) or barcodes, such as PDF417.
First, enable scanning of both sides of documents in SDCIdCaptureSettings:
settings.supportedDocuments = [.idCardVIZ, .dlVIZ]
settings.supportedSides = .frontAndBack
Start by scanning the front side of a document. After you receive the result in SDCIdCaptureListener, inspect SDCVizResult.isBackSideCaptureSupported. If scanning of the back side of your document is supported, flip the document and capture the back side as well. The next result that you receive is a combined result that contains the information from both sides. You may verify this by checking SDCVizResult.capturedSides. After both sides of the document are scanned, you may proceed with another document.
Sometimes, you may not be interested in scanning the back side of a document, after you completed the front scan. For example, your user may decide to cancel the process. Internally, Id Capture maintains the state of the scan, that helps it to provide better combined results. To abandon capturing the back of a document, reset this state by calling:
idCapture.reset()
Otherwise, Id Capture may assume that the front side of a new document is actually the back side of an old one, and provide you with nonsensical results.
Detect Tampered or Fake Documents
Id Capture helps to detect tampered or fake documents. This feature is currently limited to documents that follow the Driver License/Identification specification by American Association of Motor Vehicle Administrators (AAMVA).
Use SDCAAMVAVizBarcodeComparisonVerifier to perform basic, on-device document verification by comparing the human-readable data from the front side with the data encoded in the barcode.
This verifier may permit minor data divergence to compensate, for example, for a single character misread by OCR. While this verifier automatically detects many fraudulent documents, a failed check does not necessarily mean that the document is invalid. It is up to the user to subject such documents to additional scrutiny.
The verification is performed in the front & back scanning mode. Create the verifier and initialize SDCIdCapture with the following settings:
DataCaptureContext dataCaptureContext = DataCaptureContext(licenseKey: "-- ENTER YOUR SCANDIT LICENSE KEY HERE --")
AAMVAVizBarcodeComparisonVerifier verifier = AAMVAVizBarcodeComparisonVerifier()
IdCaptureSettings settings = IdCaptureSettings()
settings.supportedDocuments = [ .dlVIZ ]
settings.supportedSides = .frontAndBack
IdCapture idCapture = IdCapture(context: dataCaptureContext, settings: idCaptureSettings)
Then proceed to capture the front side & the back side of a document as usual. After you capture the back side and receive the combined result for both sides, you may run the verifier as follows:
func idCapture(_ idCapture: IdCapture, didCaptureIn session: IdCaptureSession, frameData: FrameData) {
guard let capturedId = session.newlyCapturedId,
let vizResult = capturedId.vizResult,
vizResult.capturedSides == .frontAndBack
else { return }
let result = verifier.verify(capturedId)
if result.checksPassed {
// Nothing suspicious was detected.
} else {
// You may inspect the results of individual checks, if you wish:
if (result.datesOfBirthMatch.checkResult == .failed) {
// The holder’s date of birth from the front side does not match the one encoded in the barcode.
}
}
}
The returned value allows you to query both the overall result of the verification and the results of individual checks. See SDCAAMVAVizBarcodeComparisonResult for details.
A more in-depth verification is performed by SDCAAMVACloudVerifier. This verifier sends the captured data to Scandit server for a more thorough check.
First, ensure that your Scandit Data Capture SDK license key supports cloud verification. Then, create an instance of SDCAAMVACloudVerifier:
let dataCaptureContext = DataCaptureContext(licenseKey: "-- ENTER YOUR SCANDIT LICENSE KEY HERE --")
let verifier = AamvaCloudVerifier(context: dataCaptureContext)
This kind of verification uses only data encoded in the barcode on the back side of the document. Therefore, you may capture both sides of the document, like in the previous example, or you may limit the capture just to the barcode.
Depending on the approach you choose initialize the mode with the following settings for the front & back:
let = IdCaptureSettings()
idCaptureSettings.supportedDocuments = [ .dlVIZ ]
idCaptureSettings.supportedSides = .frontAndBack
let idCapture = IdCapture(context: dataCaptureContext, settings: settings)
Or for the barcode only:
let settings = IdCaptureSettings()
settings.supportedDocuments = [ .dlVIZ ]
let idCapture = IdCapture(context: dataCaptureContext, settings: settings)
Once the barcode is captured, trigger the verification process. The process is asynchronous and the result will be delivered once our server verifies the received data:
func idCapture(_ idCapture: IdCapture, didCaptureIn session: IdCaptureSession, frameData: FrameData) {
guard let capturedId = session.newlyCapturedId,
let barcode = capturedId.aamvaBarcodeResult
else { return }
// Trigger the verification. This process is asynchronous.
verifier.verify(capturedId) { result, error in
if let error = error {
// Unable to reach the server - most probably the device has no internet connection.
} else if let result = result {
if result.allChecksPassed {
// Nothing suspicious was detected.
} else {
// Document may be fraudulent or tampered with - proceed with caution.
}
}
}
}