Face Capture - Selphi

This component requires a minimum iOS version of iOS9

Introduction

Face Capture is performed through the Selphi Component.

This component is responsible for capturing a user's selfie and extracting their main facial features. It includes the following processes:

• Internal camera and permission management.

• Assistance during face capture.

• Generation of facial templates and the user's image.

In the section of Simplified Launch The steps required for the basic integration of the SDK are described. On this page, specific information for launching this component is detailed.

---

Dependencies

To avoid conflicts and compatibility issues, if the project contains old versions of Facephi libraries (Widgets), they must be completely removed before installing the components of SDKMobile.

CocoaPods

Facephi libraries are distributed remotely via dependency managers. On iOS, it is used CocoaPods. The dependencies required that must already have been installed beforehand (by adding them to the project's Podfile) are:

  pod 'FPHISDKMainComponent', '~> $VERSION'

To install the component Selphi, add the corresponding dependency in the Podfile of the project, together with the mandatory dependencies of the SDK.

  pod 'FPHISDKSelphiComponent', '~> $VERSION'

Swift Package Manager (SPM)

If you use SPM, make sure the SDK's required dependencies are installed beforehand.

//HTTPS
https://github.com/facephi-clienters/SDK-SdkPackage-SPM.git
//SSH
[email protected]:facephi-clienters/SDK-SdkPackage-SPM.git

To install the component Selphi, include it in the project's modules.

//HTTPS
https://github.com/facephi-clienters/SDK-Selphi_component-SPM.git
//SSH
[email protected]:facephi-clienters/SDK-Selphi_component-SPM.git

---

Permissions

In the client application where the components are to be integrated, it is necessary to include the following item in the file Info.plist:

It is necessary to allow use of the camera (Privacy - Camera Usage Description)

Available controllers

Controller	Description
SelphiController	Main Facial Recognition controller
RawTemplateController	Controller for generating a RawTemplate from an image
SignatureSelphiController	Controller for signing a process with a Capture

---

Simplified Launch

Once the SDK has been initialized and a new operation has been created, the component can be launched using any of its available controllers, depending on the required functionality.

let controller = SelphiController(data: selphiConfigurationData, output: { sdkResult in
        // Do whatever with the result
        ...
    }, viewController: viewController)
SDKController.shared.launch(controller: controller)

---

Receiving the result

The component launch returns a result in the format SdkResult, which includes:

• selphiResult.finishStatus

• selphiResult.errorType

• selphiResult.data

Receiving errors

finishStatus: Indicates whether the operation completed successfully. Possible values:

FinishStatus.STATUS_OK
FinishStatus.STATUS_ERROR

errorType: Widget-specific errors.

In iOS, errorType is an ErrorType of the SDK. In a timeout, the Swift enum can be .SDK_TIMEOUT, .SELPHI_TIMEOUT(LivenessDiagnostic?) or, if interpolated directly, display names such as SDK_TIMEOUT or SELPHI_TIMEOUT. In iOS, there is no case TIMEOUT without a prefix.

To serialize the error, use:

sdkResult.errorType.toString(addComponentPrefix: "SPI_")

This returns SPI_TIMEOUT whether the enum is SDK_TIMEOUT and SELPHI_TIMEOUT.

Behavior on timeout

On a timeout, the result has:

• finishStatus: STATUS_ERROR

• data: nil (does not return a SelphiResult)

• errorType: .SDK_TIMEOUT or .SELPHI_TIMEOUT(LivenessDiagnostic?)

The case SELPHI_TIMEOUT retains, when available, the widget's liveness diagnostic. That information do not is part of data; it can only be read in iOS via pattern matching on errorType:

if case .SELPHI_TIMEOUT(let diagnostic) = sdkResult.errorType {
    // diagnostic: LivenessDiagnostic? (puede ser nil)
}

If the timeout comes as SDK_TIMEOUT, it does not include liveness diagnostic. If it comes as SELPHI_TIMEOUT, the associated diagnostic can be nil when the timeout occurs through the Widget error path (FWETimeout) instead of the delegate extractionTimeout().

For native iOS integrations, the serialized value should be treated as SPI_TIMEOUT (includes both SDK_TIMEOUT and SELPHI_TIMEOUT of the enum).

If showDiagnostic is active, the callback output is not invoked at the moment of the timeout: the diagnostic screen is shown first and the result is delivered when Close is pressed. With showDiagnostic disabled, the callback runs immediately.

The following list includes errors from the cross-platform contract; some do not occur in iOS.

• SPI_APPLICATION_CONTEXT_ERROR: The required application context is null.

• SPI_BAD_EXTRACTOR_CONFIGURATION_ERROR: Widget: Incorrect extractor configuration.

• SPI_CAMERA_PERMISSION_DENIED: The user has rejected the permissions.

• SPI_CANCEL_BY_USER: The user has canceled the process.

• SPI_COMPONENT_LICENSE_ERROR: The component License is not correct.

• SPI_EMPTY_LICENSE: The License String is empty.

• SPI_EXTRACTION_LICENSE_ERROR: Widget: License error.

• SPI_ACTIVE_LIVENESS_ERROR: Widget: Error in the Active Liveness process.

• SPI_HARDWARE_ERROR: Widget: Hardware error.

• SPI_INITIALIZATION_ERROR: Initialization error.

• SPI_MANAGER_NOT_INITIALIZED: The managers are null.

• SPI_NO_DATA_ERROR: The input data are null.

• SPI_OPERATION_NOT_CREATED: There is no operation in progress.

• SPI_RESOURCES_FILE_NOT_FOUND: The resource zip was not found.

• SPI_SETTINGS_PERMISSION_ERROR: Widget: Permission error.

• SPI_TEMPLATE_ERROR:

• SPI_TIMEOUT: Timeout in the process (SDK_TIMEOUT or SELPHI_TIMEOUT of the enum).

• SPI_UNEXPECTED_CAPTURE_ERROR: Widget: Capture error.

• SPI_UNKNOWN_ERROR: Unknown error.

• SPI_WIDGET_RESULT_DATA_ERROR: Error in the widget output data.

Successful execution response - data

The content of the field data depends on the launched component. In Selphi, it may include:

• template Facial template generated after extraction. Valid for authentication.

• templateRaw Raw facial template generated after the extraction process. Valid for authentication.

• bestImageData Best captured image, in byte array format and original size. Valid for liveness.

• bestImageCroppedData Cropped image centered on the face. Recommended as the user's avatar.

• qrData Information obtained from QR reading in format String.

• bestImageTokenized Encrypted image resulting from the process. Valid for liveness.

---

Advanced information

Additional controllers

SignatureSelphiController Works the same as SelphiController, but generates a process signature file.

RawTemplateController Allows generating a RawTemplate from an image (bitmap).

Usage example:

let controller = RawTemplateController(
	base64: bestImageData.base64EncodedString(),
	output: { sdkResult in
		guard let result = sdkResult.data else {return}
		print(result.base64EncodedString())
	})
SDKController.shared.launchMethod(controller: controller)

or

let controller = RawTemplateController(
	data: bestImageData,
	output: { sdkResult in
		guard let result = sdkResult.data else {return}
		print(result.base64EncodedString())
	})
SDKController.shared.launchMethod(controller: controller)

Advanced configuration

To launch the component, an object must be created SelphiConfigurationData. This object defines the component's behavior and configuration.

Available parameters

• resourcesPath Relative path to the folder Resources where the resource file is located.

• showTutorial Shows the tutorial before capture.

• showDiagnostic Displays a diagnostic screen in case of error or insufficient permissions.

• showResultAfterCapture Shows the captured image and allows repeating the process.

• debug Enables debug mode.

• fullscreen Prioritizes full-screen display.

• cropPercent Face crop percentage.

• livenessMode Liveness detection mode:

  • NONE

  • PASSIVE

  • MOVE

• stabilizationMode Forces the user to keep their head steady before starting the process.

• templateRawOptimized Indicates whether the templateRaw should be optimized.

• qrMode Enables or disables QR reading.

• videoFilename Absolute path to record the process video.

• cameraFlashEnabled Enables the camera flash.

• translationsContent Advanced text configuration via XML.

• viewsContent Advanced view configuration via XML.

• vibrationEnabled Enables vibration on errors and successful results.

• animateDismiss Indicates whether the SDK closing is animated when the process finishes. Available from 2.8.1.

Component customization

In addition to the changes that can be made at the SDK level (explained in SDK Customization), this component allows its own customization.

Texts

Texts are customized by overriding keys in Localizable.strings, within the folder Resources.

The keys with suffix _alt are used for accessibility (VoiceOver).

Text modification example START for es:

You need to go to the file Localizable.strings of the folder es.lproj (if this folder does not exist, it will need to be created).

"selphi_component_tip_button_message" = "EMPEZAR";

If a key is not defined, the default value will be used.

Name	Value
selphi_component_tutorial_message_1	Place your face in the center and look straight at the camera.
selphi_component_tutorial_message_2	Remove any object that covers your face.
selphi_component_tutorial_message_3	Look for a well-lit environment, with no shadows on your face.
selphi_component_tip_message	Place your face in the center of the circle
selphi_component_tip_title	Facial Recognition
selphi_component_tip_button	START
selphi_component_tip_button_alt	Start face capture
selphi_component_tip_anim_alt	A person shows their face inside the circle and the app takes a photo.
selphi_component_tip_move_anim_alt	Animation of a mobile phone screen with the front camera activated. A circle appears in the center of the screen. A person shows their face inside the circle, moves it slightly to one side and the app takes a photo.
selphi_component_tutorial_1_anim_alt	The photo is taken when the person is centered.
selphi_component_tutorial_2_anim_alt	A person removes their sunglasses and moves their hair away from their eyes.
selphi_component_tutorial_3_anim_alt	The image appears dark and a person turns on the light.
selphi_component_tip_move_message	Place your face in the center of the circle and follow the instructions.
selphi_component_timeout_title	Time exceeded
selphi_component_timeout_desc	We were unable to identify you. Try again

Animations

The animations for the previous tip and tutorials are Lottie (.json).

To replace them:

• Add the file to the folder Resources.

• Keep exactly the same file name.

If they are not replaced, the default animations will be shown.

Name	Function
selphi_anim_tip	LivenessMode animation: None, Passive
selphi_anim_tip_move	LivenessMode animation: Move
selphi_anim_tuto_1	First tutorial animation
selphi_anim_tuto_2	Second tutorial animation
selphi_anim_tuto_3	Third tutorial animation