Android Liveness¶

Overview¶

BiometridStandardLiveness provides facial liveness detection capabilities for Android. It supports two liveness providers: Face01 and Face06. The module handles the full liveness session lifecycle including initialization, capture, and result retrieval.

Prerequisites¶

BiometridStandardCore must be initialized first
Android minSdk 24 or higher
Camera permission granted

Initialization¶

Create an instance of BiometridStandardLiveness by providing a callback that contains provider configuration and handles liveness events.

import com.biometrid.biometridstandardliveness.BiometridStandardLiveness
import com.biometrid.biometridstandardliveness.BiometridStandardLivenessCallback
import com.biometrid.biometridstandardliveness.LivenessState
import com.biometrid.faceliveness.model.ErrorInfo
import com.biometrid.faceliveness.model.HeaderOptions
import com.biometrid.faceliveness.model.LivenessResponse
import com.biometrid.faceliveness.facetec.FaceLivenessCustomization

val livenessCallback = object : BiometridStandardLivenessCallback {
    override val validateApi: HeaderOptions? = HeaderOptions(url = "processes/", headers = mapOf("biometrid-credential" to "biometrid-credential"), process = "processToken")
    override val sessionApi: HeaderOptions? = HeaderOptions(url = "providers/custom/face01/", headers = mapOf("biometrid-credential" to "biometrid-credential"), process = "processToken")
    override val enrollmenApi: HeaderOptions? = null
    override val searchApi: HeaderOptions? = null
    override val baseURL: String = "https://your-api-url.com"
    override val productionKey: String = "your-production-key"
    override val deviceKey: String = "your-device-key"
    override val publicKey: String = "your-public-key"
    override val customization: FaceLivenessCustomization? = null
    override val i18n: Map<Any?, *>? = null

    override fun livenessFailure(error: ErrorInfo) {
        // Handle liveness error
    }

    override fun livenessState(state: LivenessState) {
        // Handle state changes (Started, Stopped)
    }

    override fun livenessResult(response: LivenessResponse?) {
        // Handle liveness result
    }

    override fun livenessSuccess() {
        // Handle liveness success
    }
}

val liveness = BiometridStandardLiveness(livenessCallback)

Available Methods¶

initialise / initialiseFace06¶

Initializes and starts the liveness provider. After successful initialization, the liveness session starts automatically. You must choose one of the two providers.

Face01Face06

fun initialise(context: Context)

Initializes the Face01 liveness provider. On successful initialization, the SDK automatically calls startLiveness internally to begin the liveness session.

Parameter	Type	Description
`context`	`Context`	Android Context for the liveness UI

Lifecycle:

initialise(context) is called
SDK initializes the Face01 provider
On success, startLiveness(context) is triggered automatically
livenessState(LivenessState.Started) callback fires
User completes the liveness check
livenessSuccess() and livenessResult(response) callbacks fire
livenessState(LivenessState.Stopped) callback fires

Example:

val liveness = BiometridStandardLiveness(callback)
liveness.set(retry = true, attempts = 3, auditTrail = true)
liveness.initialise(context) // initializes and starts the liveness session

fun initialiseFace06(context: Context)

Initializes the Face06 liveness provider. The SDK initializes and immediately calls startFace06 internally to begin the liveness session.

Parameter	Type	Description
`context`	`Context`	Android Context for the liveness UI

Lifecycle:

initialiseFace06(context) is called
SDK initializes the Face06 provider
startFace06(context) is triggered automatically
livenessState(LivenessState.Started) callback fires
User completes the liveness check
livenessSuccess() callback fires (via genuinePresence)
livenessState(LivenessState.Stopped) callback fires

Example:

val liveness = BiometridStandardLiveness(callback)
liveness.set(retry = true, attempts = 3, auditTrail = true)
liveness.initialiseFace06(context) // initializes and starts the Face06 liveness session

set¶

fun set(retry: Boolean = true, attempts: Int = 6, auditTrail: Boolean = true)

Configures liveness session parameters. Call this before initialise or initialiseFace06.

Parameter	Type	Default	Description
`retry`	`Boolean`	`true`	Whether to allow retries on failure
`attempts`	`Int`	`6`	Maximum number of retry attempts
`auditTrail`	`Boolean`	`true`	Whether to include audit trail images

getResponse¶

fun getResponse()

Retrieves the liveness session result. The result is delivered through the livenessResult callback method.

Callback Interface¶

BiometridStandardLivenessCallback¶

interface BiometridStandardLivenessCallback {
    val validateApi: HeaderOptions?
    val sessionApi: HeaderOptions?
    val enrollmenApi: HeaderOptions?
    val searchApi: HeaderOptions?
    val baseURL: String
    val productionKey: String
    val deviceKey: String
    val publicKey: String
    val customization: FaceLivenessCustomization?
    val i18n: Map<Any?, *>?
    fun livenessFailure(error: ErrorInfo)
    fun livenessState(state: LivenessState)
    fun livenessResult(response: LivenessResponse?)
    fun livenessSuccess()
}

Property	Type	Description
`validateApi`	`HeaderOptions?`	API endpoint and headers for validation
`sessionApi`	`HeaderOptions?`	API endpoint and headers for session management
`enrollmenApi`	`HeaderOptions?`	API endpoint and headers for enrollment (optional)
`searchApi`	`HeaderOptions?`	API endpoint and headers for face search (optional)
`baseURL`	`String`	Base URL for the liveness API
`productionKey`	`String`	Production license key for the liveness provider
`deviceKey`	`String`	Device-specific key for authentication
`publicKey`	`String`	Public key for secure communication
`customization`	`FaceLivenessCustomization?`	Optional UI customization
`i18n`	`Map<Any?, *>?`	Optional internationalization strings

Method	Description
`livenessFailure(error)`	Called when the liveness session fails
`livenessState(state)`	Called when the liveness session state changes
`livenessResult(response)`	Called with the liveness result data
`livenessSuccess()`	Called when the liveness check completes successfully

Data Models¶

ErrorInfo¶

data class ErrorInfo(
    val code: String?,
    val message: String?
)

LivenessResponse¶

Contains the liveness session result including audit trail data and session identifiers. Delivered through the livenessResult callback.

HeaderOptions¶

data class HeaderOptions(
    val url: String?,
    val headers: Map<String, String>?,
    val process: String?
)

Enums¶

LivenessState¶

enum class LivenessState {
    Started,   // Liveness session has started
    Stopped    // Liveness session has stopped
}

Error Handling¶

Errors are returned as ErrorInfo objects through the livenessFailure callback. Error codes are prefixed with MSL (Liveness module).

Code	Description
`MSLBSLIN001`	BiometridStandard SDK not initialized (Face01)
`MSLBSLIN002`	BiometridStandard SDK not initialized (Face06)

Usage Example¶

Face01Face06

class LivenessActivity : AppCompatActivity() {

    private lateinit var liveness: BiometridStandardLiveness

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val callback = object : BiometridStandardLivenessCallback {
            override val validateApi = HeaderOptions(
                url = "processes/",
                headers = mapOf("biometrid-credential" to "biometrid-credential"),
                process = "processToken"
            )
            override val sessionApi = HeaderOptions(
                url = "providers/custom/face01/",
                headers = mapOf("biometrid-credential" to "biometrid-credential"),
                process = "processToken"
            )
            override val enrollmenApi: HeaderOptions? = null
            override val searchApi: HeaderOptions? = null
            override val baseURL = "https://api.biometrid.com"
            override val productionKey = "production-key"
            override val deviceKey = "device-key"
            override val publicKey = "public-key"
            override val customization: FaceLivenessCustomization? = null
            override val i18n: Map<Any?, *>? = null

            override fun livenessFailure(error: ErrorInfo) {
                Log.e("Liveness", "Failed: ${error.message}")
            }

            override fun livenessState(state: LivenessState) {
                when (state) {
                    LivenessState.Started -> Log.d("Liveness", "Session started")
                    LivenessState.Stopped -> Log.d("Liveness", "Session stopped")
                }
            }

            override fun livenessResult(response: LivenessResponse?) {
                // Get liveness data
            }

            override fun livenessSuccess() {
                Log.d("Liveness", "Liveness check succeeded")
            }
        }

        liveness = BiometridStandardLiveness(callback)

        // Configure session parameters
        liveness.set(retry = true, attempts = 3, auditTrail = true)

        // Initialize Face01 liveness provider
        liveness.initialise(this)
    }

    // Call this to start the Face01 liveness session after initialization
    private fun startLiveness() {
        liveness.initialise(this)
    }

    // Call this to retrieve the liveness result after success
    private fun fetchResult() {
        liveness.getResponse()
    }
}

class LivenessActivity : AppCompatActivity() {

    private lateinit var liveness: BiometridStandardLiveness

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val callback = object : BiometridStandardLivenessCallback {
            override val validateApi = HeaderOptions(
                url = "processes/",
                headers = mapOf("biometrid-credential" to "biometrid-credential"),
                process = "processToken"
            )
            override val sessionApi = HeaderOptions(
                url = "providers/custom/face06/",
                headers = mapOf("biometrid-credential" to "biometrid-credential"),
                process = "processToken"
            )
            override val enrollmenApi: HeaderOptions? = null
            override val searchApi: HeaderOptions? = null
            override val baseURL = "https://api.biometrid.com"
            override val productionKey = "production-key"
            override val deviceKey = "device-key"
            override val publicKey = "public-key"
            override val customization: FaceLivenessCustomization? = null
            override val i18n: Map<Any?, *>? = null

            override fun livenessFailure(error: ErrorInfo) {
                Log.e("Liveness", "Failed: ${error.message}")
            }

            override fun livenessState(state: LivenessState) {
                when (state) {
                    LivenessState.Started -> Log.d("Liveness", "Session started")
                    LivenessState.Stopped -> Log.d("Liveness", "Session stopped")
                }
            }

            override fun livenessResult(response: LivenessResponse?) {
                // Get liveness data
            }

            override fun livenessSuccess() {
                Log.d("Liveness", "Liveness check succeeded")
            }
        }

        liveness = BiometridStandardLiveness(callback)

        // Configure session parameters
        liveness.set(retry = true, attempts = 3, auditTrail = true)

        // Initialize Face06 liveness provider
        liveness.initialiseFace06(this)
    }

    // Call this to start the Face06 liveness session after initialization
    private fun startFace06() {
        liveness.initialiseFace06(this)
    }

    // Call this to retrieve the liveness result after success
    private fun fetchResult() {
        liveness.getResponse()
    }
}