Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

iOS

BCC Face is a library intended to be integrated into an iOS application from a .framework file.

It uses the device camera to take a photo of a face for biometric purposes. It provides a simple active liveness test, requiring the person to smile for about one second and/or look to the right or left. The liveness test includes an option to speak the instructions, making the workflow easier for users. In addition, it provides a passive liveness test that can be used to verify that the photo was taken of a real person without requiring user interaction.

This manual is up to date for BCC Face Mobile iOS version 4.12.2.

Requirements

Installation

Installing Dependencies

1 - Add the following Pods to the application's dependencies in the Podfile:

pod 'lottie-ios'

If the application does not have a Podfile, it can be created in the root folder of your Xcode project using the pod init command in the terminal. The Podfile will not appear directly in Xcode; it will be created in the project directory.

Using dynamic frameworks is preferred. This can be indicated using the use_frameworks! flag in the Podfile.

An example Podfile with a target named BCCs-Sample is shown below:

platform :ios, '15.5'

target 'BCCs-Sample' do
	use_frameworks!

	pod 'lottie-ios'
end

post_install do |installer|
	installer.pods_project.targets.each do |target|
		target.build_configurations.each do |config|
			config.build_settings['DEVELOPMENT_TEAM'] = "YOUR_DEVELOPMENT_TEAM_KEY"
			config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
		end
	end
end

2 - Close the Xcode project, open a terminal, go to the folder where the Podfile is located, and then run:

After the execution finishes, a file with the .xcworkspace extension will be created in the same folder.

3 - Open the new .xcworkspace file.

Importing and Configuring

Importing the Project

  • Open the project using the .xcworkspace file.

  • Add the BCCFace.framework file to the project, then add it to your application's list of frameworks.

    • Move the .framework file to the project's file tree.

    • If there is already a frameworks folder, it is recommended to move the file there.

    • Open the project settings.

    • Go to the General tab.

    • Click and drag the .framework from the project tree to the Frameworks, Libraries and Embedded Content section.

  • Change the BCCFace.framework setting from Do not embed to Embed & Sign.

  • Change your project's target version to a minimum of iOS 15.5.

It is recommended to disable iPad as a target.

Initial Configuration

This version has no Firebase dependencies, nor does it require an initial configuration called from the AppDelegate. The only initial configuration required is that the application must request permission to use the camera. To do so, add the following key to the info.plist file, in the Information Property List:

The key's value is a message shown to the user when camera usage permission is requested. This value can be left blank or filled with a custom message.

Usage

Parameters and Constructor

To use the BCC Face library correctly, there are some mandatory parameters.

A simple example of using the library is shown below:


The BCCFaceBuilder class constructor receives the following parameters:

  • hostVC: UIViewController - View controller that calls the capture screen.

  • delegate: BCCFaceDelegate - Interface responsible for notifying capture events (for example, failure or success).


The initializeCapture method also accepts an optional parameter, as shown below:

If you want navigation to happen through a navigation controller, you must provide it when calling the method.


BCCFaceBuilder is the class responsible for handling the usage configuration of BCCFace. The following parameters are accepted to configure the biometric capture and the software behavior:

  • buildSmileCheck(with smileProbability: ClosedRange<Float> = 0.5...1.0) - Adds the smile to the liveness test and sets the acceptance threshold. This feature is enabled by default.

  • removeSmileCheck() - Removes the smile from the liveness test.

  • buildRotationCheck(_ rotationChecks: [HeadRotationCheck], headRotationAngle: ClosedRange<Float> = -6.0...6.0) - Defines a list of head rotation liveness tests and the maximum rotation angle. This feature is enabled by default. The head rotation options are:

  • removeHeadRotation() - Removes head rotation from the liveness test.

  • addPassiveLiveness() - Adds the passive liveness test. This feature is used to verify that the captured photo is of a real person without requiring any user interaction. To use this feature, you MUST disable the active liveness checks (removeSmileCheck() and removeHeadRotation()), which are added by default.

  • buildSpeechSettings(_ speechSettings: SpeechSettings) - Defines the criteria for accessibility speech, using the following parameters:

  • volume - The audio volume between 0.0 and 1.0.

  • startsMuted - Defines whether the instructions start muted or not (true for muted).

  • pitch - Defines the voice pitch for the instructions between 0.5 (low) and 2.0 (high).

  • speed - Defines the voice speed for the instructions. This value must be positive.

The preset values can be accessed through the static variable:

  • removeSpeech() - Removes accessibility speech.

  • setInstructionEnable(_ enable: Bool) - Defines whether the instructions screen is enabled or disabled.

  • forceLanguage(_ language: BCCLanguages?) - Forces the instructions to be shown in a single language. If the device language is not supported, English will be used. The supported languages are:

  • enableFlashButton(_ enable: Bool) - Enables (true) or disables (false) the flash button on the rear camera. Default: disabled (false).

  • enableManualCapture(_ enable: Bool) - Enables (true) or disables (false) the manual capture button, which allows bypassing the automatic capture checks. When performing a manual capture, the user will be able to review the captured photo before finishing the process.

  • setImageCompressionFormat(_ format: ImageCompressionFormat) - Defines the compression format of a passive liveness capture. You can choose between .jpeg (default) or .jpeg2000.

  • enableIntegrityValidation(clientSecret: Data, nonce: Data) - Enables integrity validation for passive liveness, an extra layer of security to ensure the integrity of the payload.

For reference, here is a complete list of parameters and default values:

Here is a code snippet to initialize a capture using only the passive liveness test:

Return Values

The results of the last face capture can be retrieved using the faceCaptureDidFinish method of the BCCFaceDelegate interface:

The data object contains the images captured during the process:

The returned properties are:

  • originalPhoto (image) - The original photo taken by the camera.

  • croppedPhoto (image) - The cropped photo, which is the face image cropped from the original photo.

  • passiveResult (Data) - File content of the passive liveness collection. It is only present if captured successfully. It is the return of the passive liveness collection as JPEG Data or JPEG 2000. This data can be saved/exported directly to a file or sent over the network (for network transmission, the data can easily be encoded, e.g., as a Base64 string).

If the user aborts the capture or if any failure occurs during the process, the faceCaptureDidAbort method will be called. You can implement this method to handle this scenario.

Sample Project

This is a working sample project for face capture using BCC Mobile Face iOS:

Last updated

Was this helpful?