Face Session Flow

Note: this feature requires an additional permission and must be explicitly requested

This feature can be used to initiate a facial recognition session based on an image (e.g. id photo) provided through our API (see "Face Session API" in the API documentation). Below you can find an example to initiate the face session.

You require an authorisation token from the Uqudo API using the credentials for your account.

The example below assumes that you have already initialised the SDK:

Objective-C

UQBuilderController *builderController = [UQBuilderController defaultBuilder];
builderController.delegate = self;
builderController.appViewController = self;
 
UQFaceSessionBuilder *faceSessionBuilder = [[UQFaceSessionBuilder alloc] init];   	 
faceSessionBuilder.appViewController = self;
faceSessionBuilder.authorizationToken = <"Your authorization token">;
faceSessionBuilder.sessionId =  <"Your sessionId">;
faceSessionBuilder.nonce = <"Your nonce">
faceSessionBuilder.minimumMatchLevel = 1;

[builderController setFaceSession:faceSessionBuilder];
[builderController performFaceSession];

Swift

let uqudoBuilder = UQBuilderController.defaultBuilder()
uqudoBuilder.delegate = self
let faceSessionBuilder = UQFaceSessionBuilder()
faceSessionBuilder.appViewController = self
faceSessionBuilder.authorizationToken =  <"Your authorization token">
faceSessionBuilder.sessionId = <"Your session id">
faceSessionBuilder.nonce =  <"Your nonce">
faceSessionBuilder.minimumMatchLevel = 1
uqudoBuilder.setFaceSession(faceSessionBuilder)
uqudoBuilder.performFaceSession()

Configuration options

The configuration options are described below:

Property	Type	Optional	Default	Description
authorizationToken	String	No	None	See Authorisation
nonce	String	Yes	None	Nonce provided by the customer mobile application when the SDK is initiated. It is useful to make sure the process has been initiated by the customer mobile application. It should be generated server side.
sessionId	String	No	None	The session id returned by the “Face Session API”, see API documentation
minimumMatchLevel	Integer	Yes	None	Defines the minimum match level that the facial recognition has to meet.
enableAuditTrailImageObfuscation(obfuscationType)	ObfuscationType	Yes	None	Enables audit trail image background obfuscation leaving only the face visible. It can be used when there are privacy concerns related to the background of the selfie taken by the user and shared in the SDK result. There are two types of obfuscations: FILLED: the background is entirely replaced FILLED_WHITE: the background is entirely replaced with a wihte background BLURRED: the background is heavily blurred, making sure the objects in the background are not clearly recognizable, but still giving a perception of the environment surrounding the user and therefore still being able to validate the reality of the image. If privacy is a concern we recommend using this option
setMaxAttempts(maxAttempts)	Int	Yes	3	Set the max failed facial recognition attempts before dropping the session. Note.: only values between 1 and 3 are taken into consideration.
returnDataForIncompleteSession	Boolean	Yes	false	When enabled, if the user or the SDK drops the session before completion and there was at least one failed facial recognition attempt, the SDK will return the partial data together with the SessionStatus object in the data attribute, that will contain the same JWS string that is returned in a successful scenario
allowClosedEyes	Boolean	Yes	false	Allows to have closed eyes during facial recognition
enableActiveLiveness	Boolean	Yes	False	Enable active liveness when performing facial recognition. There are three gestures: LivenessGesture.FACE_MOVE LivenessGesture.FACE_TILT LivenessGesture.FACE_TURN Every gesture has two actions associated resulting in a total of six possible actions (move closer, move further, tilt right, tilt left, turn right, turn left). During verification, the SDK will randomly prompt the user to perform one of these actions to continue. The configuration allows you to disable one gesture type (see below), reducing the pool to four actions. Warning: We recommend enabling this feature only if required for regulatory or compliance purposes, as it may significantly impact user conversion rates.
disableLivenessGesture	LivenessGesture	Yes	None

Handling the Result

The face session result will be available to the builder delegate if the operation succeeds and you get the result with the following method. See "SDK result (Face Object)" for the details about the JWS string:

- (void)didFaceSessionCompleteWithInfo:(NSString *)info {}

A failure scenario can be handled with the following methods:

- (void)didFaceSessionIncompleteWithStatus:(UQSessionStatus *)status {}

See the details about the UQSessionStatus below.

Session Status Handling

The UQSessionStatus is used to identify the status of the enrollment task. The object contains the following properties:

@property (nonatomic, assign) NSInteger statusCode;
@property (nonatomic, assign) NSInteger statusTask;
@property (nonatomic, strong) NSString *message;
@property (nonatomic, strong) NSString *data;

statusCode contains the following error codes:

• USER_CANCEL = User cancel the operation

• SESSION_EXPIRED = Session expired or not found

• UNEXPECTED_ERROR = Something went wrong. In the message the details of the error

• SESSION_INVALIDATED_FACE_RECOGNITION_TOO_MANY_ATTEMPTS = Session gets invalidated because of too many failed facial recognition attempts

statusTask contains the following codes:

• FACE = The facial recognition task

message contains the details of the status code

data as String that contains the JWS object with the partial data of an incomplete KYC session. Returning the partial data for an incomplete Account Recovery session is disabled by default, please see the "Configuration Options" for details.