FaceAuth

Incorporate facial authentication with proof of life verification and fingerprint authentication technology into your iOS application. This integration is ideal for enhancing login flows and securing

Current Version

Name	Version
FaceAuth	6.1.0

Requirements

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

• A valid caf mobileToken.

• Cocoapods installed

SDK Dependencies

FaceAuth leverages the following external SDKs:

SDK	Version
FaceLiveness	5.0.0

• FaceLiveness iOS: Enables the integration of live facial verification and fingerprint authentication technology.

Transitive dependencies

SDK	Version
iProov	11.0.3
FingerprintPro	2.2.0

• iProov Biometrics iOS: Enables the integration of live facial verification technology.

• FingerprintPro iOS: Provides fingerprint authentication capabilities to enhance security features in your app.

Runtime permissions

In the info.plist file, add the permissions below:

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

Installation

In your Podfile, specify the reference to our framework. Replacing <version> with the current version:

target 'your-project' do
  use_frameworks!

  pod 'FaceAuth', '<version>'

You must also include these additional sources in the Podfile:

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

Instantiating the SDK

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

class FaceAuthViewController: UIViewController {
    var faceAuthenticator: FaceAuthSDK?

    func setupFaceAuthenticator() {
        faceAuthenticator = FaceAuthSDK.Builder()
        // the table below shows all the SDK configuration options
        .build()
        faceAuthenticator?.delegate = self
    }

    func startFaceAuthenticator() {
        faceAuthenticator?.startFaceAuthSDK(viewController: self, mobileToken:"yourMobileToken", personId: "personId")
    }
}

FaceAuth Options

Parameter	Required	Default Value
startFaceAuthSDK(viewController: UIViewController, mobileToken: String, personId: String) mobileToken: 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

Getting the Results

You must implement the FaceAuthSDKDelegate class to get the SDK results. To do that, you should provide a UIViewController to your SDK instance:

faceAuthenticator?.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 FaceAuthViewController: FaceAuthSDKDelegate {
  func didFinishSuccess(with faceAuthenticatorResult: FaceAuth.FaceAuthenticatorResult) {
    //handle success result
  }
    
  func didFinishWithError(with faceAuthenticatorErrorResult: FaceAuth.FaceAuthenticatorErrorResult) {
    //handle error result
  }
    
  func didFinishFaceAuthWithCancelled() {
    //handle when user closes the SDK
  }
    
  func openLoadingScreenStartSDK() {
    //handle loading screen - display
  }
    
  func closeLoadingScreenStartSDK() {
    //handle loading screen - dismiss
  }
    
  func openLoadingScreenValidation() {
    //handle loading screen - display
  }
    
  func closeLoadingScreenValidation() {
    //handle loading screen - dismiss
  }
}   

Loading Screen

To create a loading screen during the SDK validation processes, you need to implement a view with the loading screen and display it in the open and close delegate functions. openLoadingScreenStartSDK(), closeLoadingScreenStartSDK(), openLoadingScreenValidation(), closeLoadingScreenValidation()

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

SDK Returns

Success cases

At the end of a successful execution, you will receive an object of type FaceAuthenticatorResult. 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.

faceAuthenticatorResult.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
requestId	Request identifier.
isAlive	Validation of a living person, identifies whether the user passed successfully or not.
isMatch	Face match validation result.
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.
message	Return message.

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. Additionally, the isMatch parameter indicates the success or failure of the face match, returning isMatch: true for successful matches and isMatch: false otherwise. This parameters 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 FaceAuthenticatorErrorResult. This object encompasses an enum containing the errorType, and a 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.