FaceLiveness
FaceLiveness for iOS brings cutting-edge live facial verification and fingerprint authentication technology into your iOS applications. By leveraging the iProov Biometrics iOS SDK and FingerprintPro S
Current Version
FaceLiveness
7.0.0
Requirements
iOS Target
13.0+
Xcode
15.4+
Swift
5.5+
A valid Caf mobileToken.
Cocoapods installed
SDK Dependencies
FaceLiveness utilizes two key external SDKs, managed through CocoaPods for straightforward integration:
iProov
12.2.2
FingerprintPro
2.6.0
iProov Biometrics iOS: Facilitates the integration of live facial verification technology.
FingerprintPro iOS: Adds fingerprint authentication capabilities, enhancing your app's security features.
Runtime permissions
In the info.plist
file, add the permissions below:
Privacy - Camera Usage Description
Capturing the selfie in live facial verification policies
Yes
Installation
CocoaPods
In your Podfile, specify the reference to our framework. Replacing <version>
with the current version:
For versions prior to FaceLiveness 4.0.0
, you must also include these additional sources in the Podfile:
SPM
Open your Xcode project.
Navigate to File > Add Packages.
In the search bar, paste the URL of this repository:
Instantiating the SDK
First, instantiate an object of type FaceLivenessSDK
. This object is for you to configure all your business rules:
FaceLiveness Options
.startSDK(viewController: UIViewController, mobileToken: String, personId: String)
token
: Usage token associated with your CAF accountpersonId
: Identifier of the user who will perform the face liveness verification. It's recommended to use the user's identification document in this field, such as their CPF (Brazilian document ID), but it could be any other value.
.setStage(stage: CAFStage)
Used to redirect the SDK to the desired environment in caf api. It has the following options: .beta
or .prod
.
No
.prod
.setFilter(filter: Filter)
Set the camera filter applied to the camera preview. It has the following options: .natural
or .lineDrawing
No
.lineDrawing
.setLoadingScreen(withLoading: Bool)
This boolean parameter determines whether the loading screen will be implemented via a delegate or if you will use the default screen. If set to 'true,' the loading screen will be a standard SDK screen. In the case of 'false,' you should use the 'LoadingScreen' session and implement the delegates.
No
false
.setImageUrlExpirationTime(time: Time)
Use to change the default image URL expiration time to retrieve the scan capture. It has the following options: .threeHours
, .thirtyDays
or .thirtyMin
.
No
30 min
.setAuthenticationBaseUrl(authBaseUrl: String)
Enables the use of a reverse proxy to execute SDK's authentications. Sets the base URL for authentication; protocol must be HTTPS. Adds a trailing slash if missing.
No
Default Caf URL
.setFaceLivenessBaseUrl(livenessBaseUrl: String)
Enables the use of a reverse proxy to execute face liveness checks. Sets the base URL; protocol must be WSS. Adds a trailing slash if missing. Requires certificates set via .setCertificates
for security.
No
Default IProov URL
.setCertificates(certificates: [String])
Sets the SHA256 Base64-encoded protocols for secure communication in reverse proxy implementations. Required when using custom URLs for authentication or face liveness checks.
No
Empty list
Reverse Proxy
To configure reverse proxy settings, please follow these instructions:
FaceLiveness Reverse Proxy
Set your proxy to communicate with the URL that corresponds to the
CAFStage
you are using:CAFStage.PROD
->https://api.public.caf.io/v1/sdks/faces/
CAFStage.BETA
->https://api.public.beta.caf.io/v1/sdks/faces/
CAFStage.DEV
->https://api.public.dev.caf.io/v1/sdks/faces/
Use the method
.setFaceLivenessBaseUrl
to set the URL on which FaceLiveness should run.The URL's protocol must be WSS.
Use the
.setCertificates
method to set the certificates, which should be the base64-encoded SHA-256 hash of the certificate's Subject Public Key Info.Certificates are required for the FaceLiveness reverse proxy to work properly.
Authentication reverse proxy
Set your proxy to communicate with `wss://us.rp.secure.iproov.me/wsΒ΄.
Use the method
.setAuthenticationBaseUrl
to set the URL on which the authorization requests must run.The URL's protocol must be HTTPS.
Getting the Results
You must implement the FaceLivenessDelegate
class to get the SDK results. To do that, you should provide a UIViewController
to your SDK instance:
Delegate Implementation
The delegate below must be implemented to handle the SDK results. When implementing the delegate extension, you will have access to an object depending on the return type. In each case, the object carries different information.
Loading Screen
To create a loading screen during the SDK validation processes, you need to implement a view with the loading screen and display this screen in the onConnectionChanged(_ state: FaceLiveness.LivenessState)
delegate function.
closed
SDK has been closed
dismiss
connecting
SDK is connecting to liveness server
display
connected
SDK has been connected with the liveness server
dismiss
In the SDK implementation, it is necessary to add the view to the view stack using the following code. This makes the view visible.
This view should be added before the Builder of each SDK.
SDK Returns
Success cases
At the end of a successful execution, you will receive an object of type LivenessResult
. This object carries a signedResponse
property containing a JWT token with the execution result. This token should be decrypted to obtain the execution results details.
Within the signedResponse
, the parameter isAlive
defines the execution of liveness, where true
is approved and false
is rejected (Failure case will be returned).
SignedResponse params
requestId
Request identifier.
isAlive
Validation of a living person, identifies whether the user passed successfully or not.
token
Request token.
userId
User identifier provided for the request.
imageUrl
Temporary link to the image, generated by our API.
personId
User identifier provided for the SDK.
sdkVersion
Sdk version in use.
iat
Token expiration.
The isAlive parameter is VERY IMPORTANT, as it dictates whether the validation process proceeds or halts. When isAlive: true
, the user gains passage to continue their journey; conversely, if isAlive: false
, the user is deemed invalid and access to further stages of the journey should be denied. This parameter plays a pivotal role in guiding the flow of operations.
Error cases
In the event of execution errors, you will receive an object of type SDKError
. This object encompasses an enum containing the errorType
, and a description
.
unsupportedDevice
Indicates that the device hardware or software does not meet the minimum requirements for facial recognition.
cameraPermission
Indicates that the device does not have permission to access the camera, either due to user denial or missing app permissions.
networkException
Indicates a network-related error, such as no internet connection, server timeouts, or network congestion.
tokenException
Indicates an issue with the provided authentication token, such as being invalid, expired, or lacking necessary permissions.
serverException
Indicates a server-side error, which may include server misconfigurations, processing failures, or service interruptions.
certificateException
Indicates that there are no valid certificates for the proxy URL, preventing secure communication.
captureAlreadyActiveException
Indicates that a facial recognition capture is already in progress. A new capture cannot start until the current one completes.
unexpectedErrorException
Indicates an unrecoverable error occurred during the facial recognition transaction.
userTimeoutException
Indicates a server-side error, which may include server misconfigurations, processing failures, or service interruptions.
imageNotFoundException
Indicates a user has taken too long to complete the claim.
tooManyRequestsException
Indicates that the server has received more requests than itβs prepared to handle.
Failure cases
In the event of execution failures, you will receive an object of type SDKFailure
. This object encompasses an enum containing the failureType
, description
and a signedResponse
.
All failure reasons are exclusively returned in GPA liveness validation flows. In LA (Liveness Assurance) flows, any failure will consistently return the generic UNKNOWN error, regardless of the specific issue encountered.
unknown
Try again.
tooMuchMovement
Keep still.
tooBright
Move somewhere darker.
tooDark
Move somewhere brighter.
misalignedFace
Keep your face in the oval.
eyesClosed
Keep your eyes open.
faceTooFar
Move your face closer to the screen.
faceTooClose
Move your face farther from the screen.
sunglasses
Remove sunglasses.
obscuredFace
Remove any face coverings.
multipleFaces
Ensure only one person is visible.
β οΈ Sandbox Configuration for iOS
If you encounter the error related to Sandbox: rsync.samba deny file-write-create
when using this SDK in an iOS project, follow the steps below:
In Xcode, go to your project under the Build Settings tab.
In the search field, look for sandbox.
Locate the User Script Sandboxing option.
Change the value to No.
Last updated
Was this helpful?