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

Name Version

Name	Version
`FaceLiveness`	6.2.1

FaceLiveness

6.2.1

Requirements

Deployment Info	Version
iOS Target	13.0+
Xcode	15.4+
Swift	5.5+

Deployment Info

Version

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:

SDK Version

SDK	Version
`iProov`	12.2.1
`FingerprintPro`	2.6.0

iProov

12.2.1

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:

Permission Reason Required

Permission	Reason	Required
`Privacy - Camera Usage Description`	Capturing the selfie in live facial verification policies	Yes

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:

target 'your-project' do
  use_frameworks!

  pod 'FaceLiveness', '<version>'

For versions prior to FaceLiveness 4.0.0, you must also include these additional sources in the Podfile:

source 'https://github.com/combateafraude/iOS.git'
source 'https://cdn.cocoapods.org/'

SPM

Open your Xcode project.
Navigate to File > Add Packages.
In the search bar, paste the URL of this repository:

https://github.com/combateafraude/FaceLiveness.git

Instantiating the SDK

First, instantiate an object of type FaceLivenessSDK. This object is for you to configure all your business rules:

class FaceLivenessViewController: UIViewController {
    var faceLiveness: FaceLivenessSDK?

    func setupFaceLiveness() {
        faceLiveness = FaceLivenessSDK.Build()
        // the table below shows all the SDK configuration options
        .build()
        faceLiveness?.delegate = self
    }

    func startFaceLiveness() {
        faceLiveness?.startSDK(viewController: self, mobileToken:"yourMobileToken", personId: "personId")
    }
}

FaceLiveness Options

Parameter Required Default Value

Parameter	Required	Default Value
`.startSDK(viewController: UIViewController, mobileToken: String, personId: String)` `token`: Usage token associated with your CAF account `personId`: identifier of the user in which is registered the face of the user who will perform the facematch. Currently, this value only accepts the user's CPF.	Yes	You must provide this information.
`.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

.startSDK(viewController: UIViewController, mobileToken: String, personId: String)

token: Usage token associated with your CAF account
personId: identifier of the user in which is registered the face of the user who will perform the facematch. Currently, this value only accepts the user's CPF.

Yes

You must provide this information.

.setStage(stage: CAFStage)

Used to redirect the SDK to the desired environment in caf api. It has the following options: .beta or .prod.

.prod

.setFilter(filter: Filter)

Set the camera filter applied to the camera preview. It has the following options: .natural or .lineDrawing

.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.

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.

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.

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.

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.

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.

    faceLiveness = FaceLivenessSDK.Build()
    .setFaceLivenessBaseUrl("wss://my.proxy.io/ws/")
    .setCertificates(certificates: [
        "4d69f16113bed7d62ca56feb68d32a0fcb7293d3960=",
        "50f71c5dda30741ee4be1ac378e12539b0d1d511f99=",
        "9f85e26c1ae41f7ac97adc4099be7f2a40759510ab9="
    ])
    .build()

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.

    faceLiveness = FaceLivenessSDK.Build()
        .setAuthenticationBaseUrl("https://my.proxy.io/v1/faces/")
        .build();

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:

faceLiveness?.delegate = self

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.

extension FaceLivenessViewController: FaceLivenessDelegate {
    func didFinishLiveness(with livenessResult: FaceLiveness.LivenessResult) {
        //handle success result
    }
    
    func didFinishWithError(with sdkFailure: FaceLiveness.SDKFailure) {
        //handle error result
    }
    
    func didFinishWithCancelled() {
        //handle when user closes the SDK
    }
    
    func onConnectionChanged(_ state: FaceLiveness.LivenessState) {
        //handle loading screen display
    }
}

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.

state	description	loading screen
closed	SDK has been closed	dismiss
connecting	SDK is connecting to liveness server	display
connected	SDK has been connected with the liveness server	dismiss

state

description

loading screen

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.

  view.addSubview(loadingHUD)

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.

  livenessResult.signedResponse

Within the signedResponse, the parameter isAlive defines the execution of liveness, where true is approved and false is rejected (Error case will be returned).

SignedResponse params

Event Description

Event	Description
`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.

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 SDKFailure. This object encompasses an enum containing the errorType, and a description.

ErrorType Description

ErrorType	Description
`unsupportedDevice`	This error may occur if the device hardware or software does not meet the minimum requirements for facial recognition functionality.
`cameraPermission`	This error typically occurs when the user denies access to the camera or if the app lacks the necessary permissions.
`networkException`	This error may occur due to various network issues such as a lack of internet connection, server timeouts, or network congestion.
`tokenException`	This error may occur if the provided authentication token is invalid, expired, or lacks the necessary permissions to perform facial recognition tasks.
`serverException`	This error is typically returned when there is an issue with the server processing the facial recognition request. This could include server-side errors, misconfigurations, or service interruptions.

unsupportedDevice

This error may occur if the device hardware or software does not meet the minimum requirements for facial recognition functionality.

cameraPermission

This error typically occurs when the user denies access to the camera or if the app lacks the necessary permissions.

networkException

This error may occur due to various network issues such as a lack of internet connection, server timeouts, or network congestion.

tokenException

This error may occur if the provided authentication token is invalid, expired, or lacks the necessary permissions to perform facial recognition tasks.

serverException

This error is typically returned when there is an issue with the server processing the facial recognition request. This could include server-side errors, misconfigurations, or service interruptions.

Last updated 16 days ago