DOT iOS Face Lite library
v8.4.0
Introduction
DOT iOS Face Lite provides components for face 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
Distribution
Swift Package Manager
DOT iOS Face Lite is distributed as a binary XCFramework - DotFaceLite.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 the version you want to use. There you can select DotFaceLite
package. All the required dependencies will be downloaded with the selected package.
Cocoapods
DOT iOS Face Lite is distributed as a XCFramework - DotFaceLite.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
.
source 'https://github.com/innovatrics/innovatrics-podspecs'
Then DOT iOS Face Lite dependency must be specified in Podfile
. Dependencies of DOT iOS Face Lite will be downloaded alongside it.
source 'https://github.com/innovatrics/innovatrics-podspecs'
use_frameworks!
target 'YOUR_TARGET' do
pod 'dot-face-lite'
end
In case of CocoaPods problem with
|
Supported Architectures
DOT iOS Face Lite 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
:
<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 DotFaceLiteLibrary
object.
DOT SDK Sample shows how to initialize DOT SDK with DotFaceLiteLibrary
. 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 Face Lite, it is usually a good practice to deinitialize it in order to free the memory. You can deinitialize DOT iOS Face Lite 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 Face Lite components again, you need to call DotSdk.shared.initialize()
again.
Logging
DOT iOS Face Lite supports logging using a global Logger
class. You can set the log level as follows:
import DotFaceLite
Logger.logLevel = .debug
Log levels:
debug
info
warning
error
none
Each log message contains DotFaceLite
tag. Keep in mind that logging should be used just for debugging purposes.
Components
Overview
DOT iOS Face Lite 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 Face Lite 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
- FACE DETECTOR
A component for performing face detection on an image.
- FACE AUTO CAPTURE CONTROLLER
A component for capturing good quality image of human face.
List of UI Components
- FACE AUTO CAPTURE
A visual component for capturing good quality image of human face.
- MAGNIFEYE LIVENESS
A visual component for capturing images suitable for MagnifEye liveness evaluation.
Non-UI Components
Face Detector
The FaceDetector
class provides a face detection functionality.
Create a FaceDetector
:
let faceDetector = FaceDetector()
To perform detection, call the following method on the background thread:
let result = try? faceDetector.detect(bgraRawImage: bgraRawImage, limit: 1).first
Face Auto Capture Controller
The FaceAutoCaptureController
class provides a stateful face auto capture functionality.
You can configure FaceAutoCaptureController
using FaceAutoCaptureController.Configuration
.
Create FaceAutoCaptureController
:
let configuration = try! FaceAutoCaptureController.Configuration(
minValidFramesInRowToStartCandidateSelection: 2
candidateSelectionDurationMillis: 1000,
detectionNormalizedRectangle: detectionNormalizedRectangle,
validators: validators)
let controller = FaceAutoCaptureController(configuration: configuration)
You can use detectionNormalizedRectangle
to specify the region in the input image which will be used for face 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 face detection.
To capture a good quality face image, repeatedly call the process()
method using the camera frames:
faceAutoCaptureController.process(bgraRawImage: bgraRawImage, timestampMillis: timestampMillis)
The controller evaluates the face 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 face image candidate is returned by the delegate and the face auto capture process is over.
UI Components
Camera handling
Camera lifecycle
DOT iOS Face Lite view controller will start the camera in viewWillAppear(:)
lifecycle method.
DOT iOS Face Lite view controller will stop the camera in viewDidDisappear(:)
lifecycle method.
Camera permission
DOT iOS Face Lite 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 viewController = FaceAutoCaptureViewController.create(configuration: .init(), style: .init())
viewController.delegate = self
self.present(viewController, animated: true, completion: nil)
To embed view controller into your view controller:
override func viewDidLoad() {
super.viewDidLoad()
let viewController = FaceAutoCaptureViewController.create(configuration: .init(), style: .init())
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 Face Lite view controllers ignore safe area layout guide when they layout their subviews. Therefore, for example if you push DOT iOS Face Lite view controller using UINavigationController
, you will get incorrect layout. If you want to respect safe area layout guide, you should embed DOT iOS Face Lite view controller in a container view controller and setup the layout constraints accordingly.
Face Auto Capture
The view controller with instructions for obtaining quality face images suitable for matching.
You can configure FaceAutoCaptureViewController
using FaceAutoCaptureViewController.Configuration
.
For face verification scenarios, a convenient preset configuration simple
is available within FaceAutoCaptureViewController.Configuration.Presets
.
You can customize the appearance of FaceAutoCaptureViewController ` using `FaceAutoCaptureViewController.Style
.
You can handle the FaceAutoCaptureViewController ` events using its delegate `FaceAutoCaptureViewControllerDelegate
.
To create FaceAutoCaptureViewController
:
let viewController = FaceAutoCaptureViewController.create(configuration: .init(), style: .init())
viewController.delegate = self
self.present(viewController, animated: true, completion: nil)
To start the face auto capture process call the start()
method. You can start the process any time.
In case you want to handle detection data, implement faceAutoCaptureViewController(:processed:)
delegate callback. This callback is called with each processed camera frame. When the face auto capture process finishes successfully, the result will be returned via the faceAutoCaptureViewController(:captured:)
callback.
In case you want to force the capture event, call the requestCapture()
method. The most recent image will be returned via the faceAutoCaptureViewController(:captured:)
callback asynchronously.
Call start()
method again in case you need to start over the face auto capture process. You can also call start()
method to stop and start over ongoing process as well.
In case you want to stop the face 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 FaceAutoCaptureViewController.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 = FaceAutoCaptureViewController.Configuration.QualityAttributeThresholdPresets.standard.build()
// Modified thresholds based on the standard preset
let modified = try FaceAutoCaptureViewController.Configuration.QualityAttributeThresholdPresets.standard
.minConfidence(minConfidence)
.maxDevicePitchAngle(nil)
.build()
// Custom thresholds
let custom = try FaceAutoCaptureViewController.Configuration.QualityAttributeThresholds.Builder()
.minConfidence(minConfidence)
.maxDevicePitchAngle(maxDevicePitchAngle)
.build()
Available presets (pre-defined builders with thresholds) in QualityAttributeThresholdPresets
:
standard
- The resulting image suitable for evaluation on Digital Identity Service. See the thresholds.
MagnifEye Liveness
The view controller with instructions for obtaining face data suitable for MagnifEye liveness evaluation.
In order to configure the behaviour of MagnifEyeLivenessViewController
, use MagnifEyeLivenessViewController.Configuration
.
In order to customize the appearance of MagnifEyeLivenessViewController
, use MagnifEyeLivenessViewController.Style
.
You can handle the MagnifEyeLivenessViewController
events using its delegate MagnifEyeLivenessViewControllerDelegate
.
To start the MagnifEye liveness process call the start()
method. You can start the process any time.
In case you want to handle detection data, implement magnifEyeLivenessViewController(:processed:)
callback. This callback is called with each processed camera frame. When the MagnifEye liveness process finishes successfully, the result will be returned via the magnifEyeLivenessViewController(:finished:)
callback.
Call start()
method in order to start over the MagnifEye liveness process. You can also call start()
method to stop and start over ongoing process.
In case you want to stop the MagnifEye liveness process prematurely, call the stopAsync()
method. The callback in the method argument indicates that the processing is over.
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 thisLocalizable.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 DotFaceLite
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 DotFaceLite
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
"dot_face_lite.face_auto_capture.instruction.candidate_selection" = "Stay still...";
"dot_face_lite.face_auto_capture.instruction.face_out_of_bounds" = "Center your face";
"dot_face_lite.face_auto_capture.instruction.face_not_detected" = "Position your face into the circle";
"dot_face_lite.face_auto_capture.instruction.size_too_small" = "Move closer";
"dot_face_lite.face_auto_capture.instruction.size_too_large" = "Move back";
"dot_face_lite.face_auto_capture.instruction.brightness_too_high" = "Turn towards light";
"dot_face_lite.face_auto_capture.instruction.brightness_too_low" = "Turn towards light";
"dot_face_lite.face_auto_capture.instruction.sharpness_too_low" = "Turn towards light";
"dot_face_lite.face_auto_capture.instruction.device_pitch_too_high" = "Hold your phone at eye level";
"dot_face_lite.magnifeye_liveness.instruction.eye_centering" = "Fit your eye into square";
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)
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.
Appendix
Changelog
8.4.0 - 2024-09-11
Technical release. No changes.
8.3.2 - 2024-08-16
Technical release. No changes.
8.3.1 - 2024-08-15
Technical release. No changes.
8.3.0 - 2024-08-08
Technical release. No changes.
8.2.1 - 2024-07-31
Fixed
Default value for argument
isFacePresenceRequired
in methodFaceAutoCaptureViewController.requestCapture()
.
8.2.0 - 2024-07-30
Added
Nested enumerator
Error
to all public components. It groups all possible errors that might be thrown by a component.Enum
CaptureMode
.Property
FaceAutoCaptureViewController.Configuration.captureMode
.Property
FaceAutoCaptureViewController.Configuration.isPlaceholderVisible
.Class
FaceAutoCaptureViewController.Configuration.Presets
.Method argument
isFacePresenceRequired
to methodFaceAutoCaptureViewController.requestCapture()
.
Fixed
Camera session crashed in some rare cases.
8.1.0 - 2024-07-09
Changed
Face detection is improved (UI Face Auto Capture, Face Auto Capture Controller, Face Detector).
Sharpness calculation is improved (UI Face Auto Capture, Face Auto Capture Controller).
8.0.0 - 2024-06-27
Changed
Minimal required iOS version to iOS 12.0.
Minimal required version of Xcode to Xcode 15.1.
Method
.create()
for all UI components to.init()
.Renamed property
FaceAutoCaptureViewController.Style.overlayColor
to.placeholderOverlayColor
.Renamed property
MagnifEyeLivenessViewController.Style.overlayColor
to.placeholderOverlayColor
.Method signature
FaceDetector.detect()
.Class
FaceDetector.Result
toFaceDetector.Face
.Property
FaceDetector.Result.normalizedRectangle
toFaceDetector.Face.position
.Property
FaceAutoCaptureDetection.faceDetectorResult
to.face
.Property
FaceAutoCaptureDetection.position
toFaceAutoCaptureDetection.face.position
.Property
FaceAutoCaptureFrameParameters.faceDetectorResult
to.face
.Property
FaceAutoCaptureFrameParameters.detectionPosition
toFaceAutoCaptureFrameParameters.face.position
.Property
FaceAutoCaptureResult.faceDetectorResult
to.face
.Property
MagnifEyeLivenessResult.faceDetectorResult
to.face
.Moved
FaceAutoCaptureConfiguration
toFaceAutoCaptureViewController.Configuration
,FaceAutoCaptureStyle
toFaceAutoCaptureViewController.Style
,FaceAutoCaptureControllerConfiguration
toFaceAutoCaptureController.Configuration
.Moved
MagnifEyeLivenessConfiguration
toMagnifEyeLivenessViewController.Configuration
,MagnifEyeLivenessStyle
toMagnifEyeLivenessViewController.Style
.Updated localization keys.
Removed
Callback
FaceAutoCaptureViewControllerDelegate.faceAutoCaptureViewControllerCandidateSelectionStarted(_:)
.
7.5.3 - 2024-06-24
Added
Security guidelines section to the integration manual.
7.5.2 - 2024-04-30
Changed
Changed minimal required version of Xcode to Xcode 14.2.0.
7.5.1 - 2024-04-15
Fixed
Added
PrivacyInfo.xcprivacy
and signature toDotProtocolBuffers
dependency.
7.5.0 - 2024-04-03
Added
Callback
onStopped
as an argument to methodFaceAutoCaptureViewController.stopAsync()
.Callback
onStopped
as an argument to methodMagnifEyeLivenessViewController.stopAsync()
.
Removed
Method
FaceAutoCaptureViewControllerDelegate.faceAutoCaptureViewControllerStopped()
. UseFaceAutoCaptureViewController.stopAsync()
method argumentonStopped
instead.Method
MagnifEyeLivenessViewControllerDelegate.magnifEyeLivenessViewControllerStopped()
. UseMagnifEyeLivenessViewController.stopAsync()
method argumentonStopped
instead.
7.4.2 - 2024-03-21
Fixed
Stability issue.
7.4.1 - 2024-03-19
Technical release. No changes.
7.4.0 - 2024-03-19
Technical release. No changes.
7.3.0 - 2024-02-23
Fixed
Fixed licensing issue. Newly generated licenses will only work from this and subsequent releases.
7.2.1 - 2024-01-11
Technical release. No changes.
7.2.0 - 2023-12-28
Changed
Camera preview and image analysis resolution selection strategy in UI components for
CameraPreviewScaleType.fill
.
7.1.1 - 2023-12-21
Fixed
In some cases UI components created invalid
.content
in its result class.
7.1.0 - 2023-12-14
Technical release. No changes.
7.0.2 - 2023-12-04
Fixed
DOT SDK initialization (license parsing).
7.0.1 - 2023-12-01
Technical release. No changes.
7.0.0 - 2023-11-02
Added
Class
DotSdk
.Class
DotSdkConfiguration
.Protocol
DotLibrary
.License file is required. To obtain one, please contact
support@innovatrics.com
.
Changed
Class
DotFaceLiteLibrary
reworked.
6.5.1 - 2023-10-19
Technical release. No changes.
6.5.0 - 2023-10-04
Technical release. No changes.
6.4.0 - 2023-09-19
Added
Class
TiltAngles
.Class
DevicePitchTooHighValidator
.Property
.maxDevicePitchAngle
toFaceAutoCaptureConfiguration.QualityAttributeThresholds
.Property
.deviceTiltAngles
toFaceAutoCaptureDetection
.Property
.deviceTiltAngles
toFaceAutoCaptureFrameParameters
.Property
.deviceTiltAngles
toFaceAutoCaptureController.Sample
.Localization key
dot.face_lite_auto_capture.instruction.device_pitch_too_high
.
Changed
Signature of
FaceAutoCaptureController.process()
method.
6.3.0 - 2023-08-18
Changed
Update
MagnifEyeLivenessResult.content
.
6.2.0 - 2023-07-26
Added
Property
.sessionToken
toFaceAutoCaptureConfiguration
,MagnifEyeLivenessConfiguration
,FaceAutoCaptureControllerConfiguration
.
6.1.1 - 2023-07-19
Technical release. No changes.
6.1.0 - 2023-07-07
Added
Property
.isTorchEnabled
toFaceAutoCaptureConfiguration
,MagnifEyeLivenessConfiguration
.
Fixed
MagnifEye Liveness UI components after restart.
6.0.0 - 2023-06-14
Added
FaceAutoCaptureConfiguration.QualityAttributeThresholds.Builder
FaceAutoCaptureConfiguration.QualityAttributeThresholdPresets
FaceAutoCaptureResult.content
MagnifEyeLivenessResult.faceDetectorResult
Changed
create
FaceAutoCaptureConfiguration.QualityAttributeThresholds
using.Builder
.SizeTooSmallValidator.defaultMinDetectionSizeToImageShorterSideRatioThreshold
SizeTooLargeValidator.defaultMaxDetectionSizeToImageShorterSideRatioThreshold
Definition of property
DetectionPosition.sizeToImageShorterSideRatio
now fits [Face Size](https://developers.innovatrics.com/digital-onboarding/docs/glossary/) definition.
5.5.0 - 2023-04-26
Technical release. No changes.
5.4.0 - 2023-03-24
Added
MagnifEye Liveness UI component (
MagnifEyeLivenessViewController
,MagnifEyeLivenessViewControllerDelegate
,MagnifEyeLivenessConfiguration
,MagnifEyeLivenessStyle
,MagnifEyeLivenessResult
).localization key
dot.face_lite_magnifeye_liveness.instruction.eye_centering
.
5.3.0 - 2023-03-23
Added
Enum
FaceAutoCaptureController.Phase
.Property
FaceAutoCaptureController.ProcessingResult.phase
.
Changed
Method
FaceAutoCaptureViewController.start()
(re)starts the process any time during the lifecycle of the component.
Removed
Enum
FaceAutoCaptureController.Event
.Property
FaceAutoCaptureController.ProcessingResult.events
. Use propertyFaceAutoCaptureController.ProcessingResult.phase
instead.Method
FaceAutoCaptureController.restart()
. Create new instance ofFaceAutoCaptureController
instead.Method
FaceAutoCaptureViewController.restart()
. UseFaceAutoCaptureViewController.start()
instead.
5.2.0 - 2023-03-06
Technical release. No changes.
5.1.1 - 2023-02-21
Added
support for Swift Package Manager.
5.1.0 - 2023-02-08
Added
shared dependency
DotCore
.shared dependency
DotCamera
.
Changed
types moved to
DotCore
:BgraRawImage
,BgraRawImageFactory
,CGImageFactory
,CIImageFactory
,ImageSize
,RectangleDouble
,PointDouble
,IntervalFloat
,IntervalDouble
.types moved to
DotCamera
:CameraFacing
,CameraPreviewScaleType
.
5.0.0 - 2023-01-27
Changed
New SDK versioning: All libraries (DOT Document, DOT Face, DOT Face Lite and DOT NFC) are released simultaneously with a single version name. Libraries with the same version name work correctly at build time and at run time.
text of localization key
dot.face_lite_auto_capture.instruction.face_not_present
toPosition your face into the circle
all UI components will return images with aspect ratio 4:3
Fixed
maximal resolution of images returned from all UI components was too high
@objc prefix pattern to
DOTFL*
1.1.2 - 2022-10-24
Fixed
verification of validator dependencies
Changed
minimal required version to Xcode 14+
Added
FaceAutoCaptureDetectionValidator.dependencyIdentifiers
Changed
FaceAutoCaptureControllerConfiguration.init()
throwsSizeTooSmallValidator
andSizeTooLargeValidator
threshold interval from [0,1] to [0,inf]FaceAutoCaptureConfiguration.sizeInterval
from [0,1] to [0,inf]
1.1.1 - 2022-08-15
Fixed
crash when camera device is not available
camera session lifecycle
camera permission issue
1.0.0 - 2022-05-19
First release