Biometric Capture
Implementing the Biometric Capture Session in a View-based UI using a fragment for the camera preview with all its defined functionalities.
This example shows how to integrate the Biometric Capture Session to your project. The Biometric Capture Session extracts a frames collection from the camera preview.
This Example app uses ViewBinding
, so enable it with the following (at the end of the android{}
block):
buildFeatures {
viewBinding true
}
When prompted, click Sync Now, and we will be ready to use the Biometric Capture Session in our app.
Create an activity to host MBCaptureSessionFragment
.
OverlayActivity.kt
class OverlayActivity : AppCompatActivity(){
}
fragment_capture_overlay.xml
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto"
xmlns:tools="http://schemas.android.com/tools"
android:layout_width="match_parent"
android:layout_height="match_parent"
tools:context=".OverlayActivity">
<!-- res/layout/example_activity.xml -->
<androidx.fragment.app.FragmentContainerView
android:id="@+id/fragment_container_view"
android:layout_width="match_parent"
android:layout_height="match_parent" />
</FrameLayout>
Add a fragment container.
<androidx.fragment.app.FragmentContainerView
android:id="@+id/fragment_container_view"
android:layout_width="match_parent"
android:layout_height="match_parent" />
OverlayActivity.kt
class OverlayActivity : AppCompatActivity()) {
private lateinit var binding: ActivityOverlayBinding
}
Create an ActivityOverlayBinding
instance.
private lateinit var binding: ActivityOverlayBinding
Invoke onCreate
method.
@SuppressLint("UnsafeOptInUsageError")
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
binding = ActivityOverlayBinding.inflate(layoutInflater)
setContentView(binding.root)
verifyCameraPermission()
}
Initialize binding
.
binding = ActivityOverlayBinding.inflate(layoutInflater)
setContentView(binding.root)
Request camera permission.OverlayActivity
is the activity host forCaptureOverlayFragment
.
verifyCameraPermission()
Extend OverlayActivityt
from MBCaptureSessionFragmentListener
.
class OverlayActivity : AppCompatActivity(), MBCaptureSessionFragmentListener {
private lateinit var binding: ActivityOverlayBinding
@SuppressLint("UnsafeOptInUsageError")
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
binding = ActivityOverlayBinding.inflate(layoutInflater)
setContentView(binding.root)
verifyCameraPermission()
}
override fun onCaptureFinished(result: MBCaptureSessionResult?) { }
override fun onFailure(errorEnum: MBCaptureSessionError) { }
override fun onStateChanged(stateEnum: MBCaptureState) { }
}
Display camera by inflating MBCaptureSessionFragment
.
class OverlayActivity : AppCompatActivity(), MBCaptureSessionFragmentListener {
private lateinit var binding: ActivityOverlayBinding
@SuppressLint("UnsafeOptInUsageError")
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
binding = ActivityOverlayBinding.inflate(layoutInflater)
setContentView(binding.root)
verifyCameraPermission()
val captureSessionOptions = MBCaptureSessionOptions.Builder().build()
val cameraOptions = MBUIOptions.Builder().build()
val captureSessionFragment = MBCaptureSessionFragment(captureSessionOptions,cameraOptions, this)
if (savedInstanceState == null) {
supportFragmentManager.commit {
add(R.id.fragment_container_view, captureSessionFragment)
setReorderingAllowed(true)
}
}
}
override fun onCaptureFinished(result: MBCaptureSessionResult?) { }
override fun onFailure(errorEnum: MBCaptureSessionError) { }
override fun onStateChanged(stateEnum: MBCaptureState) { }
}
Build an MBCaptureSessionOption.Builder
instance.. All arguments are optional. It contains the default options for performing the capture session. Those default options can be redefined. In this case the capture process is set to automatic.
val options = MBCaptureSessionOptions.Builder().build()
MBCaptureSessionOptions
Inside the library we have some options for changing behaviour of capturing data:
Variable Name | Type | Default Value |
---|---|---|
numberOfFrameToCollect | number | 3 |
timeBeforeAutomaticCapture | number | 4 |
isDebugging | boolean | false |
autoCaptureEnabled | boolean | true |
payloadOptimization | boolean | false |
cameraQuality | MBCameraOptions | MBCameraOptions |
MBCaptureSessionOption.Builder
arguments are optional.
Options description:
numberOfFrameToCollect
Describes the number of frames to collect during the capture sessionautoCaptureEnabled
Tells whether the capture is automatic or manualtimeBeforeAutomaticCapture
Is the set time in seconds the capture should wait to start collecting frames The text for the countdownLabel can be set using thecountdownLabelText
option.isDebugging
If it is set to false will just display the overlay on the top of the camera. If it is set to true will display all components available ont the top of the camera(timer text, progress bar and face status text).payloadOptimization
It is use to enable or disable the optimization of the payload you send to the backend | reduces the payload size.cameraQuality
It is used to set the options for the camera. It accepts three parameters: A MBTargetResolution instance, this is the resolution in witch the frames are collected. It accepts a MBPreviewScaleTyp instance that is the mode used to scale the camera preview in the view. It can be set to either FIT_CENTER or FILL_CENTER. MBPreviewScaleType.FILL_CENTER will ensure the camera preview is taking up the whole view in both width and height. However, this means that some parts of the image will be cropped from the preview. This does not have any impact on the images captured from the camera. MBPreviewScaleType.FIT_CENTER will ensure that exactly what is captured from the camera is shown in the view. And a MBCameraPosition that describes whether is displayed front or rear camera.
MBTargetResolution
Field | Value |
---|---|
QHD | Size(540, 960) |
HD_720 | Size(720, 1280) |
HD_1080 | Size(1080, 1920) |
HD_4K | Size(2160, 3840) |
MBUIOptions
Variable Name | Type | Default Value |
---|---|---|
textLocalizations | MBTextLocalizations | MBTextLocalizations |
showCountdownTimerLabel | boolean | false |
showProgressBar | boolean | false |
showFaceStatusLabel | boolean | false |
MBUIOptions.Builder
arguments are optional.
Options description:
If no input is provided to faceStatusTexts
default values are used.
showCountdownTimerLabel
Is used to show or hide the label displayed during countdown before capture starts. The text for the countdownLabel can be set using thecountdownLabelText
option.showProgressBar
Is used to show or hide the progress bar. The progress bar indicates to the user how far in the capture process we are.faceStatusTexts
Is used to show or hide the face status label. The face status label is used to indicate to the user if the face is in the correct position or not.textLocalizations
it is used to Describe the text that is displayed on the top of the camera. It receives a string that is used to customize the text shown in the countdown label and aMBFaceStatusTexts
.
MBTextLocalizations
Variable Name | Type | Default Value |
---|---|---|
countdownLabelText | string | 'Hold Still' |
faceStatusTexts | MBFaceStatusTexts | MBFaceStatusTexts() |
MBFaceStatusTexts
- MBFaceStatusTexts class containing the default face status strings
Member | Type | Description |
---|---|---|
faceTooFarAway | string | Text to display when the face is too far away from the camera |
faceTooFarUp | string | Text to display when the face i too far up in the camera |
faceTooFarDown | string | Text to display when the face is too far down in the camera |
faceTooFarLeft | string | Text to display when the face is too far left in the camera |
faceTooFarRight | string | Text to display when the face is too far right in the camera |
faceTooClose | string | Text to display when the face is too close to the camera |
faceNotFound | string | Text to display when no face is found |
tooManyFaces | string | Text to display when too many faces are found in the camera |
validFace | string | Text to display when the face is in a valid position in the camera |
Create a MBCaptureSessionFragment
instance.
val captureSessionFragment = MBCaptureSessionFragment(options = options,CaptureSessionFragmentListener = this)
Add MBCaptureSessionFragment
to the activity.
if (savedInstanceState == null) {
supportFragmentManager.commit {
add(R.id.fragment_container_view, captureSessionFragment)
setReorderingAllowed(true)
}
}
onCaptureFinished
is executed for MBCaptureSessionService
when the capture session has successfully finished.
override fun onCaptureFinished(result: MBCaptureSessionResult?) { }
MBCaptureSessionResult
arguments description:
faceImage
A high quality image captured after collecting frames.frames
Is the frame collection.serializedData()
Is thefaceImage
andframes
in Protobuf serialization.
Function onFailure
is executed when the capture process fails. MBCaptureSessionError
tells the type of error that occurred.
override fun onFailure(errorEnum: MBCaptureSessionError) { }
MBCaptureSessionError
entries:
UNABLE_TO_OPEN_CAMERA
Describes failure while opening the cameraUNABLE_TO_COLLECT_FRAMES
The capture has is aborted
The function onStateChanged
is executed every time the capture state changes. The parameterstateEnum
is a representation of the current state.
MBCaptureState
- INITIALIZING Is the first state and tell when the camera is ready.
- VALIDATING Is the second state and tell when the frames start being analyzed.
- COUNT_DOWN Is the third state and tell when a valid face is found in a single frame. If there is an invalid face in the following frames the state return to VALIDATING.
- CAPTURING CAPTURING is the fourth state and tell when the frames start being collected.If there is an invalid face in the following frames the stage return to VALIDATING.
- CAPTURE_FINISHED Is the last state and tell when the capturing is successfully finished.
- PROCESSING Is the state that tells when the captured frames are being precessed
override fun onStateChanged(stateEnum: MBCaptureState) { }