Android

BCC Face is an Android library intended to be integrated into an Android application.

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 play the instructions by voice, making the flow 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 Android version 4.12.2.

The passive liveness test is only available from version 4.4.0 onwards.

Requirements

BCC Face is an Android library and must be imported into the target project.

• Minimum Android version: Android 6.0 (SDK 23), "Marshmallow".

• The mobile device must have a camera.

• The native application must be built with Android technology.

• Development environment: an Android IDE is required, such as Android Studio (recommended).

• Additional external dependencies:

  • Google ML Kit, face detection version 16.1.7;

  • Lottie, version 3.0.0;

  • RootBeer, version 0.1.1;

  • Gson, version 2.8.5;

  • Google Tink, version 1.11.0;

  • Material Components, version 1.6.1.

• External services:

  • Firebase, by Google. An account is required, but no charges will apply since the library only uses on-device APIs.

Installation

Adding the Library to the App Project

BCC Face is provided by Griaule as an .aar file.

To add the libraries, go to your project directory, open the app folder and create the directories: libs/bccface. Then add the bccfacelib-release.aar dependency. The folder structure should look similar to this:

The next step is to make these files visible to the Gradle dependencies. To do so, add the following line to the build.gradle (:app) file, inside the dependencies object:

dependencies {
	[...]
	implementation fileTree(dir: 'libs/bccface', include: ['*.aar'])
}

Inside the build.gradle (:app) file, also add the compile options and set Source Compatibility and Target Compatibility to use 1.8 (Java 8):

compileOptions {
	sourceCompatibility JavaVersion.VERSION_17
	targetCompatibility JavaVersion.VERSION_17
}

Configuring Google ML Kit

It is recommended to follow the instructions provided in "Option 1: Use the Firebase console setup workflow" from the Firebase for Android documentation: Add Firebase to your Android project.

An account is required, but no charges will apply since the library only uses on-device APIs: See Firebase pricing details.

If Option 1 was chosen, make sure to generate the google-services.json file and place it in the android/app/ directory.

Make changes to the following files:

• android/build.gradle

  buildscript {
  	// ...
  	dependencies {
  		// ...
  		classpath 'com.google.gms:google-services:4.4.2'
  	}
  }

• android/app/build.gradle, add to the end of the file:

  // ...

  apply plugin: 'com.android.application'
  apply plugin: 'kotlin-android'
  apply plugin: 'kotlin-kapt'
  apply plugin: 'com.google.gms.google-services'

  // ...

  android {
  	// ...
  	buildFeatures {
  		viewBinding = true
  		dataBinding = true
  	}
  }

  // ...

  dependencies {
  	// ...
  	implementation 'com.google.firebase:firebase-analytics:17.2.2'
  	// Add the line above if using analytics
  }

Configuring All Dependencies

Make changes to the following files:

• android/build.gradle

  allprojects {
  	repositories {
  		// ...
  		google()
  		mavenCentral()
  		maven { url 'https://jitpack.io' }
  	}
  }

• android/app/build.gradle

  // ...
  dependencies {
  	// ...
  	implementation project(path: ':bccfacelib')

  	// ANDROIDX //
  	implementation 'androidx.appcompat:appcompat:1.7.0'
  	implementation 'androidx.core:core-ktx:1.13.1'
  	implementation 'androidx.constraintlayout:constraintlayout:2.1.4'

  	// Google MLKIT //
  	implementation 'com.google.mlkit:face-detection:16.1.7'

  	// LOTTIE //
  	implementation 'com.airbnb.android:lottie:3.0.0'

  	// CAMERA X //
  	def camerax_version = "1.5.1"
  	implementation "androidx.camera:camera-camera2:$camerax_version"
  	implementation "androidx.camera:camera-lifecycle:$camerax_version"
  	implementation "androidx.camera:camera-view:$camerax_version"

  	// MATERIAL //
  	implementation 'com.google.android.material:material:1.6.1'
  }

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:

BCCFaceBuilder(this, this).initializeCapture()

---

BCCFaceBuilder is the class constructor and receives the following parameters:

• context: Context - The application context.

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

---

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

• buildSmileCheck(smileProbability: Float = 0.8f) - 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(livenessConfigList: List<HeadRotationCheck>, headRotationAngle: Float = 20f) - Defines a list of head rotation liveness tests and the maximum rotation angle. This feature is enabled by default. The head rotation options are:

  enum class HeadRotationCheck {
  	randomRotation,
  	leftRotation,
  	rightRotation;
  }

• 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 only this feature, the active liveness tests (removeSmileCheck() and removeHeadRotation()), which are enabled by default, must be disabled. It is also possible to combine both types of test, using passive and active liveness simultaneously.

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

  class SpeechSettings(
  	val volume: Float = 1.0f,
  	val startsMuted: Boolean = true,
  	val pitch: Float = 1.0f,
  	val speed: Float = 1.0f
  )

• 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:

  class SpeechSettings {
  	companion object {
  		val defaultSpeechSettings = SpeechSettings()
  	}
  }

• removeSpeech() - Removes accessibility speech.

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

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

  enum class BCCLanguages(val locale: Locale) {
  	ptBR(Locale("pt", "br")),
  	enUS(Locale.US),
  	esMX(Locale("es", "mx")),
  	deviceLanguage(Locale.getDefault());
  }

• removeLanguage() - Removes the forced language.

• enableFlipCameraButton(enable: Boolean) - Enables (true) or disables (false) the camera flip button (front or rear camera). Default: enabled (true).

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

• enableManualCapture(enable: Boolean) - 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.

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

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

• setCameraInitialDirection(CameraFacingDirection.<FRONT or BACK>) - Defines the initial camera direction; choose between:

  • CameraFacingDirection.FRONT - Front camera (default setting).

  • CameraFacingDirection.BACK - Rear camera.

---

All camera direction settings are achieved by combining the enableFlipCameraButton and setCameraInitialDirection methods. For example:

• Start with the front camera and enable the camera flip button:

  BCCFaceBuilder(this, this)
  	.enableFlipCameraButton(true)
  	.setCameraInitialDirection(CameraFacingDirection.FRONT)

• Start with the rear camera and disable the camera flip button:

  BCCFaceBuilder(this, this)
  	.enableFlipCameraButton(false)
  	.setCameraInitialDirection(CameraFacingDirection.BACK)

---

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

var showInstructionScreen: Boolean = false,
var stopVerifyEyesOpenTimeout: Long = 20,   // Deprecated as of 4.12.2
var useICAO: Boolean = false,
var smilingProbabilityThreshold: Float = 0.8f,
var rotateAngle: Float = 20f,
var livenessList: MutableList<LivenessTypes> = mutableListOf(LivenessTypes.SMILE),
var rotationChecks: MutableList<HeadRotationCheck> = mutableListOf(HeadRotationCheck.randomRotation),
var language: BCCFaceAPI.BCCLanguages? = null,
var speechSettings: SpeechSettings? = SpeechSettings(),
var activityResults: FaceCaptureActivityResults? = null,
var enableFlipCameraButton: Boolean = false,
var enableManualCapture: Boolean = false,
var initCameraFaceDirection: Int = CameraSelector.LENS_FACING_FRONT,
var imageCompressionFormat: ImageCompressionFormat = ImageCompressionFormat.JPEG,
var integrityValidationData: IntegrityValidationData? = null

The active liveness test (using smile and random head rotation) is enabled by default. To use only the passive liveness test, before adding it, you must remove the active liveness methods from the builder:

BCCFaceBuilder(this, this)
	.removeSmileCheck()
	.removeHeadRotation()
	.addPassiveLiveness()

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

// From the desired Activity...

// Create the builder
BCCFaceBuilder faceBuilder = new BCCFaceBuilder(this, this);

// Configure the builder
faceBuilder
	.removeSmileCheck()
	.removeHeadRotation()
	.addPassiveLiveness();

// Initialize the capture from the builder
faceBuilder.initializeCapture();

Return Values

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

fun faceCaptureDidFinish(
	data: BCCFaceReturnData,
	analytics: BCCFaceReturnAnalytics
)

The data object contains both images captured during the process:

class BCCFaceReturnData {
	val originalPhoto: Bitmap?
	val croppedPhoto: Bitmap?

	// Passive Liveness Result
	val passiveResult: ByteArray?
}

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 (ByteArray) - File content of the passive liveness collection. It is only present if captured successfully. It is the return of the passive liveness collection as a JPEG ByteArray 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).

The originalPhoto and croppedPhoto properties return null when the capture is performed for passive tests only (i.e., without including an active test).

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 Android:

package com.example.bccfaceexample

import android.os.Bundle
import android.util.Log
import androidx.appcompat.app.AppCompatActivity
import com.example.bccfaceexample.databinding.ActivityMainBinding
import com.griaule.bccfacelib.analytics.BCCFaceReturnAnalytics
import com.griaule.bccfacelib.faceApi.BCCFaceBuilder
import com.griaule.bccfacelib.faceApi.BCCFaceDelegate
import com.griaule.bccfacelib.faceApi.BCCFaceReturnData

class MainActivity : AppCompatActivity(), BCCFaceDelegate {
	private lateinit var binding: ActivityMainBinding

	override fun onCreate(savedInstanceState: Bundle?) {
		super.onCreate(savedInstanceState)
		binding = ActivityMainBinding.inflate(layoutInflater)
		setContentView(binding.root)
		setupListeners()
	}

	private fun setupListeners() {
		binding.startCaptureButton.setOnClickListener { initializeCapture() }
	}

	private fun initializeCapture() {
		BCCFaceBuilder(this, this)
			.removeSmileCheck()
			.removeHeadRotation()
			.addPassiveLiveness()
			.enableFlipCameraButton(true)
			.enableFlashButton(true)
			.initializeCapture()
	}

	override fun faceCaptureDidFinish(
		data: BCCFaceReturnData,
		analytics: BCCFaceReturnAnalytics
	) {
		// ...
	}

	override fun faceCaptureDidAbort(
		analytics: BCCFaceReturnAnalytics
	) {
		// ...
	}
}