Get Started
This page will guide you through the process of adding ID Capture to your iOS application. ID Capture is a mode of the Scandit Data Capture SDK that allows you to capture and extract information from personal identification documents, such as driver's licenses, passports, and ID cards.
The general steps are:
- Creating a new Data Capture Context instance
- Accessing a Camera
- Configuring the Capture Settings
- Implementing a Listener to Receive Scan Results
- Setting up the Capture View and Overlay
- Starting the Capture Process
Using ID Capture at the same time as other modes (e.g. Barcode Capture) is not supported.
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. See the installation guide for details.
You can retrieve your Scandit Data Capture SDK license key by signing in to your account Dashboard.
Module Overview
The modules that need to be included in your project depend on the features you want to use. The following table lists what modules you need to include in your project, depending on the features you want to use.
Module | Required for Feature |
---|---|
ScanditCaptureCore | Required for all ID Capture features |
ScanditIdCapture | Required for all ID Capture features |
ScanditIdCaptureBackend | Extract data from visual inspection zones (e.g. the front of IDs and driver licenses, or the human-readable data on Passport) |
ScanditIdEuropeDrivingLicense | Extract vehicle category data from the back of EU Driver Licenses |
ScanditIdAamvaBarcodeVerification | Verify US Driver Licenses |
ScanditIdVoidedDetection | Reject voided IDs |
Note that your license may support only a subset all ID Capture capabilities. If you need to use additional features, contact us.
Create a 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.
- Swift
- Objective-C
self.context = DataCaptureContext(licenseKey: "-- ENTER YOUR SCANDIT LICENSE KEY HERE --")
SDCDataCaptureContext *dataCaptureContext = [SDCDataCaptureContext contextForLicenseKey:@"-- ENTER YOUR SCANDIT LICENSE KEY HERE --"];
Access a Camera
Next, you need to create a new instance of the SDCCamera
class to indicate the camera that will be used to stream previews and to capture images. The camera settings are also configured, in this case, we use the recommendedCameraSettings
that come withe ID Capture SDK.
- Swift
- Objective-C
camera = Camera.default
context.setFrameSource(camera, completionHandler: nil)
// Use the recommended camera settings for the IdCapture mode.
let recommendedCameraSettings = IdCapture.recommendedCameraSettings
camera?.apply(recommendedCameraSettings)
SDCCamera *camera = [SDCCamera defaultCamera];
[dataCaptureContext setFrameSource:camera completionHandler:nil];
auto recommendedCameraSettings = [SDCIdCapture recommendedCameraSettings];
[camera applySettings:recommendedCameraSettings completionHandler:nil];
Configure the Capture Settings
Use IdCaptureSettings to configure the scanner type to use and the documents that should be accepted and/or rejected.
Check IdCaptureDocumentType for all the available options.
- Swift
- Objective-C
var acceptedDocuments = [IdCaptureDocument]()
var rejectedDocuments = [IdCaptureDocument]()
// Passports from any region:
acceptedDocuments.append(Passport(region: .any))
// Only documents issued by a specific country:
acceptedDocuments.append(IdCard(region: .germany))
// Standardized documents issued in Europe:
acceptedDocuments.append(IdCard(region: .euAndSchengen))
acceptedDocuments.append(DriverLicense(region: .euAndSchengen))
// Regional documents:
acceptedDocuments.append(RegionSpecific(subtype: .apecBusinessTravelCard))
acceptedDocuments.append(RegionSpecific(subtype: .chinaExitEntryPermit))
// Reject passports from certain regions:
rejectedDocuments.append(Passport(region: .cuba))
// Configure:
let settings = IdCaptureSettings()
settings.acceptedDocuments = acceptedDocuments
settings.rejectedDocuments = rejectedDocuments
// Capture only one-side documents and a given zone
// Capture only barcodes
settings.scannerType = SingleSideScanner(enablingBarcode: true,
machineReadableZone: false,
visualInspectionZone: false)
// Capture only Machine Readable Zone (MRZ)
settings.scannerType = SingleSideScanner(enablingBarcode: false,
machineReadableZone: true,
visualInspectionZone: false)
// Capture only Visual Inspection Zone (VIZ)
settings.scannerType = SingleSideScanner(enablingBarcode: false,
machineReadableZone: false,
visualInspectionZone: true)
// Full document scanner
settings.scannerType = FullDocumentScanner()
NSMutableArray<SDCIdCaptureDocument *> *acceptedDocuments = [NSMutableArray new];
NSMutableArray<SDCIdCaptureDocument *> *rejectedDocuments = [NSMutableArray new];
// Passports from any region:
[acceptedDocuments addObject:[SDCPassport documentWithRegion:SDCIdCaptureRegionAny]];
// Only documents issued by a specific country:
[acceptedDocuments addObject:[SDCIdCard documentWithRegion:SDCIdCaptureRegionGermany]];
// Standardized documents issued in Europe:
[acceptedDocuments addObject:[SDCIdCard documentWithRegion:SDCIdCaptureRegionEUAndSchengen]];
[acceptedDocuments addObject:[SDCDriverLicense documentWithRegion:SDCIdCaptureRegionEUAndSchengen]];
// Regional documents:
[acceptedDocuments addObject:[SDCRegionSpecific documentWithSubtype:SDCIdCaptureRegionSpecificSubtypeApecBusinessTravelCard]];
[acceptedDocuments addObject:[SDCRegionSpecific documentWithSubtype:SDCIdCaptureRegionSpecificSubtypeChinaExitEntryPermit]];
// Reject passports from certain regions:
[rejectedDocuments addObject:[SDCPassport documentWithRegion:SDCIdCaptureRegionCuba]];
// Configure:
SDCIdCaptureSettings *settings = [SDCIdCaptureSettings new];
settings.acceptedDocuments = acceptedDocuments;
settings.rejectedDocuments = rejectedDocuments;
// Capture only one-side documents and a given zone
// Capture only barcodes
settings.scannerType = [SDCSingleSideScanner scannerEnablingBarcode:YES
machineReadableZone:NO
visualInspectionZone:NO];
// Capture only Machine Readable Zone (MRZ)
settings.scannerType = [SDCSingleSideScanner scannerEnablingBarcode:NO
machineReadableZone:YES
visualInspectionZone:NO];
// Capture only Visual Inspection Zone (VIZ)
settings.scannerType = [SDCSingleSideScanner scannerEnablingBarcode:NO
machineReadableZone:NO
visualInspectionZone:YES];
// Full document scanner
settings.scannerType = [SDCFullDocumentScanner scanner];
Create a new ID Capture mode with the chosen settings:
- Swift
- Objective-C
idCapture = IdCapture(context: context, settings: idCaptureSettings)
SDCIdCapture *idCapture = [SDCIdCapture idCaptureWithContext:dataCaptureContext settings:idCaptureSettings];
Implement a Listener
To receive scan results, implement and IdCaptureListener. The listener provides two callbacks: didCapture
and didReject
- Swift
- Objective-C
extension IdCaptureViewController: IdCaptureListener {
func idCapture(_ idCapture: IdCapture, didCapture capturedId: CapturedId) {
// Success! Handle extracted data here.
}
func idCapture(_ idCapture: IdCapture,
didReject capturedId: CapturedId?,
reason: RejectionReason) {
// Something went wrong. Inspect the reason to determine the follow-up action.
}
}
idCapture.addListener(self)
- (void)idCapture:(SDCIdCapture *)idCapture didCapture:(SDCCapturedId *)capturedId {
// Success! Handle extracted data here.
}
- (void)idCapture:(SDCIdCapture *)idCapture
didReject:(nullable SDCCapturedId *)capturedId
reason:(SDCRejectionReason)rejectionReason {
// Something went wrong. Inspect the reason to determine the follow-up action.
}
[idCapture addListener:self];
Handling Success
Capture results are delivered as a CapturedId. This class contains data common for all kinds of personal identification documents.
For more specific information, use its non-null result properties (e.g. CapturedId.barcode).
On a successful scan you may read the extracted data from CapturedId
:
- Swift
- Objective-C
func idCapture(_ idCapture: IdCapture, didCapture capturedId: CapturedId) {
let fullName = capturedId.fullName
let dateOfBirth = capturedId.dateOfBirth
let dateOfExpiry = capturedId.dateOfExpiry
let documentNumber = capturedId.documentNumber
// Process data:
processData(fullName, dateOfBirth, dateOfExpiry, documentNumber)
}
- (void)idCapture:(SDCIdCapture *)idCapture didCapture:(SDCCapturedId *)capturedId {
NSString *fullName = capturedId.fullName;
NSDate *dateOfBirth = capturedId.dateOfBirth;
NSDate *dateOfExpiry = capturedId.dateOfExpiry;
NSString *documentNumber = capturedId.documentNumber;
// Process data:
[self processData:fullName dateOfBirth:dateOfBirth dateOfExpiry:dateOfExpiry documentNumber:documentNumber];
}
All data fields are optional, so it's important to verify whether the required information is present if some of the accepted documents may not contain certain data.
Handling Rejection
The ID scanning process may fail for various reasons. Start by inspecting RejectionReason
to understand the cause.
You may wish to implement the follow-up action based on the reason of failure:
- Swift
- Objective-C
func idCapture(_ idCapture: IdCapture,
didReject capturedId: CapturedId?,
reason: RejectionReason) {
if reason == .timeout {
// Ask the user to retry, or offer alternative input method.
} else if reason == .notAcceptedDocumentType {
// Ask the user to provide alternative document.
} else {
// Handle other rejection reasons, if necessary.
}
}
- (void)idCapture:(SDCIdCapture *)idCapture
didReject:(nullable SDCCapturedId *)capturedId
reason:(SDCRejectionReason)rejectionReason {
if (rejectionReason == SDCRejectionReasonTimeout) {
// Ask the user to retry, or offer alternative input method.
} else if (rejectionReason == SDCRejectionReasonNotAcceptedDocumentType) {
// Ask the user to provide alternative document.
} else {
// Handle other rejection reasons, if necessary.
}
}
Set up Capture View and Overlay
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:
- Swift
- Objective-C
let dataCaptureView = DataCaptureView(context: dataCaptureContext, frame: .zero)
view.addSubview(dataCaptureView)
dataCaptureView.translatesAutoresizingMaskIntoConstraints = false
view.addConstraints([
dataCaptureView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
dataCaptureView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
dataCaptureView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
dataCaptureView.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor)
])
SDCDataCaptureView *dataCaptureView =
[SDCDataCaptureView dataCaptureViewForContext:dataCaptureContext frame:CGRectZero];
dataCaptureView.translatesAutoresizingMaskIntoConstraints = NO;
[self.view addSubview:dataCaptureView];
[self.view addConstraint:[dataCaptureView.topAnchor constraintEqualToAnchor:self.view.safeAreaLayoutGuide.topAnchor]];
[self.view addConstraint:[dataCaptureView.bottomAnchor constraintEqualToAnchor:self.view.safeAreaLayoutGuide.bottomAnchor]];
[self.view addConstraint:[dataCaptureView.leadingAnchor constraintEqualToAnchor:self.view.leadingAnchor]];
[self.view addConstraint:[dataCaptureView.trailingAnchor constraintEqualToAnchor:self.view.trailingAnchor]];
Then, add a SDCIdCaptureOverlay
to the view:
- Swift
- Objective-C
let overlay = IdCaptureOverlay(idCapture: idCapture, view: captureView)
SDCIdCaptureOverlay *overlay = [SDCIdCaptureOverlay overlayWithIdCapture:idCapture view:dataCaptureView];
The overlay chooses the displayed UI automatically, based on the selected SDCIdCaptureSettings
.
Start the Capture Process
Finally, turn on the camera to start scanning:
- Swift
- Objective-C
camera?.switch(toDesiredState: .on)
[camera switchToDesiredState:SDCFrameSourceStateOn];