Implementação

Este guia mostra a API pública do LivenessFacetecSDK e o fluxo completo de uma verificação de vivacidade.

API pública

A fachada do SDK fica em com.vcc.vendor.facetec.sdk.LivenessFacetecSDK e tem quatro funções:

object LivenessFacetecSDK {
    suspend fun init(
        application: Application,
        config: LivenessFacetecSDKConfig
    ): Result<Unit>

    suspend fun getSessionData(): Result<LivenessFacetecSDKSessionData>

    fun startLivenessCheck(
        activity: Activity,
        sessionId: String,
        sessionToken: String
    ): Flow<LivenessFacetecSDKLivenessState>

    fun stop()
}

init recebe a Application (não um Context) e devolve Result<Unit>. É idempotente — chamadas subsequentes retornam sucesso imediatamente, sem reinicializar a FaceTec, desde que o SDK não tenha sido parado com stop().
getSessionData coleta o ssid de perimeter security, usado pelo seu backend na criação da sessão.
startLivenessCheck requer uma Activity chamadora porque o FaceTec abre sua própria UI a partir dela.
stop para a execução do SDK e libera recursos do sistema.

As chaves internas do SDK são embutidas no AAR em tempo de compilação. Nenhuma chave precisa ser fornecida pelo app consumidor em init ou em qualquer outra chamada.

Configuração

data class LivenessFacetecSDKConfig(
    val customization: LivenessFacetecSDKCustomization? = null,
    val lowLightCustomization: LivenessFacetecSDKCustomization? = null,
    val dynamicDimmingCustomization: LivenessFacetecSDKCustomization? = null,
)

Parâmetro	Tipo	Obrigatório	Descrição
`customization`	`LivenessFacetecSDKCustomization?`	Não	Personalização da UI do FaceTec aplicada em condições normais. Veja Customização
`lowLightCustomization`	`LivenessFacetecSDKCustomization?`	Não	Customização alternativa que a FaceTec aplica automaticamente em baixa luminosidade
`dynamicDimmingCustomization`	`LivenessFacetecSDKCustomization?`	Não	Customização alternativa aplicada durante o dimming dinâmico da tela

Dados de sessão

Depois de init, chame getSessionData() para obter o ssid — o identificador de perimeter security que seu backend repassa na criação da sessão:

data class LivenessFacetecSDKSessionData(
    val ssid: String
)

Campo	Tipo	Descrição
`ssid`	`String`	Identificador de sessão de dispositivo. Vem vazio (`""`) se a coleta falhar.

A coleta é best-effort e nunca bloqueia o fluxo: qualquer falha interna devolve Result.success com ssid vazio, apenas registrando o erro internamente. Um ssid vazio não é um erro — siga o fluxo normalmente.

Criação de sessão — responsabilidade do consumer app

O SDK não cria sessões nem se comunica diretamente com o backend de autenticação. Após init(), o consumer app deve:

Chamar getSessionData() e obter o ssid.
Encaminhar o ssid ao seu backend, que cria a sessão e devolve sessionId e sessionToken.
Passar os dois tokens para startLivenessCheck().

O SDK não tem acesso às credenciais do backend do consumer nem conhece o contexto de negócio necessário para criar uma sessão válida. Manter a criação de sessão no consumer app garante flexibilidade (autenticação, multi-tenant) sem acoplar o SDK a uma topologia específica de backend.

O contrato da chamada de criação de sessão está documentado em Serviço.

Estados do `Flow`

startLivenessCheck retorna um Flow<LivenessFacetecSDKLivenessState> que emite um único caminho Loading → Success ou Loading → Error antes de completar:

sealed class LivenessFacetecSDKLivenessState {
    object Loading : LivenessFacetecSDKLivenessState()
    data class Success(val data: LivenessFacetecSDKResultData) : LivenessFacetecSDKLivenessState()
    data class Error(val data: LivenessFacetecSDKResultData) : LivenessFacetecSDKLivenessState()
}

Estado	Descrição
`Loading`	Captura FaceTec em andamento
`Success(data)`	`data.status == SESSION_COMPLETED`
`Error(data)`	`data.status` com qualquer outro valor

Success e Error carregam o mesmo tipo, LivenessFacetecSDKResultData. O que os diferencia é apenas o status: SESSION_COMPLETED sempre chega como Success; qualquer outro valor (cancelamento pelo usuário, erro de câmera, lockout etc.) chega como Error. Não existe um tipo de erro separado — a causa da falha está inteiramente no status.

O estado terminal é decidido pelo status que a própria FaceTec retorna ao fechar a UI de captura, e é emitido imediatamente — sem depender de nenhuma chamada de rede adicional e sem estados intermediários durante a captura.

Retentativa dentro da captura: enquanto a UI do FaceTec está aberta, ela pode pedir ao usuário que tente de novo quantas vezes julgar necessário. Esse retry é interno ao FaceTec e não é exposto ao seu app — o Flow entrega apenas o desfecho final.

Fluxo de uso

Inicializar o SDK

Chame LivenessFacetecSDK.init uma única vez, preferencialmente no onCreate() da Application:

import android.app.Application
import android.util.Log
import com.vcc.vendor.facetec.sdk.LivenessFacetecSDK
import com.vcc.vendor.facetec.sdk.models.LivenessFacetecSDKConfig
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.launch

class MyApplication : Application() {

    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Main)

    override fun onCreate() {
        super.onCreate()

        scope.launch {
            LivenessFacetecSDK.init(
                application = this@MyApplication,
                config = LivenessFacetecSDKConfig() // customization é opcional
            ).onSuccess {
                Log.d("LivenessFacetecSDK", "SDK inicializado com sucesso")
            }.onFailure { e ->
                Log.e("LivenessFacetecSDK", "Falha ao inicializar: ${e.message}")
            }
        }
    }
}

init() é idempotente — é seguro chamá-lo em múltiplas Activities ou no onCreate() da Application.

Criar sessão no backend

Colete o ssid e chame seu backend para obter os tokens necessários para a captura:

val sessionData = LivenessFacetecSDK.getSessionData().getOrThrow()

// Exemplo — adapte ao seu cliente HTTP
val session = mySessionApi.createSession(
    body = SessionRequest(ssid = sessionData.ssid)
)
// session: { sessionId, sessionToken }

Iniciar a verificação

startLivenessCheck() retorna um Flow cold. Se ele for coletado antes de init() ter retornado sucesso, a coleta lança IllegalStateException — a exceção surge no momento da coleta (.collect { } / .catch { }), não na chamada de startLivenessCheck() em si, já que nada roda até haver um coletor. Garanta que init() retornou Result.success(...) antes de iniciar a captura, ou trate a exceção com .catch { }.

import androidx.lifecycle.lifecycleScope
import com.vcc.vendor.facetec.sdk.LivenessFacetecSDK
import com.vcc.vendor.facetec.sdk.LivenessFacetecSDKLivenessState
import kotlinx.coroutines.flow.catch
import kotlinx.coroutines.launch

lifecycleScope.launch {
    LivenessFacetecSDK.startLivenessCheck(
        activity = this@VerificationActivity,
        sessionId = session.sessionId,
        sessionToken = session.sessionToken
    )
        .catch { e ->
            Log.e("LivenessFacetecSDK", "Erro inesperado: ${e.message}")
        }
        .collect { state ->
            when (state) {
                is LivenessFacetecSDKLivenessState.Loading -> mostrarProgresso()
                is LivenessFacetecSDKLivenessState.Success -> tratarSucesso(state.data)
                is LivenessFacetecSDKLivenessState.Error -> tratarFalha(state.data)
            }
        }
}

Tratar o resultado

No caso de sucesso, use o sessionId para reconciliar a captura no backend. No caso de falha, use o status para decidir a ação e o friendlyMessage para exibir ao usuário — veja Solução de problemas.

Campos de `LivenessFacetecSDKResultData`

Carregado por ambas as variantes do Flow — Success(data) e Error(data) usam exatamente o mesmo tipo:

Campo	Tipo	Descrição
`sessionId`	`String`	Identificador da sessão — o mesmo passado para `startLivenessCheck()`
`status`	`LivenessFacetecSDKSessionStatus`	Status final da sessão FaceTec. Veja a tabela abaixo
`friendlyMessage`	`String`	Mensagem legível para o usuário final, fixa por `status`
`ageGroup`	`Int?`	Valor retornado nativamente pela FaceTec. Só preenchido quando `status == SESSION_COMPLETED`
`auditTrailImage`	`String?`	Imagem do audit trail em base64. Só preenchida quando `status == SESSION_COMPLETED` e a API a envia

friendlyMessage é definido no lado do cliente e é fixo por status — não vem do backend. Use-o como texto pronto para exibição, e o status como a chave de decisão do seu fluxo.

`LivenessFacetecSDKSessionStatus`

Enum fechado com os 8 valores possíveis. Apenas SESSION_COMPLETED resulta em Success; todos os outros resultam em Error:

Valor	Situação	`friendlyMessage`
`SESSION_COMPLETED`	Sucesso — único valor que resulta em `Success`	”The Session was performed successfully.”
`REQUEST_ABORTED`	A aplicação abortou a requisição de sessão	”The application aborted on session request.”
`USER_CANCELLED_FACE_SCAN`	Usuário cancelou antes de completar os scans de rosto necessários	”The user cancelled before performing enough Scans to Succeed.”
`USER_CANCELLED_ID_SCAN`	Usuário cancelou antes de completar os scans de documento necessários	”The user cancelled before performing enough Scans to Complete.”
`LOCKED_OUT`	O limite de tentativas da sessão foi atingido	”SDK is in a lockout state, the limit of tries for this session has been reached.”
`CAMERA_ERROR`	A câmera selecionada não está ativa	”Session cancelled because selected camera is not active.”
`CAMERA_PERMISSIONS_DENIED`	Usuário não concedeu (ou negou anteriormente) a permissão de câmera	”The user did not enable the camera after prompting for camera permissions or camera permissions were previously denied.”
`UNKNOWN_INTERNAL_ERROR`	Erro interno inesperado, não relacionado ao veredito de liveness (ex.: SDK parado via `stop()` durante uma captura)	“The Session was cancelled because of an Unknown Error.”

Como o enum é fechado, um when (data.status) exaustivo compila sem else — e passa a falhar na build se a Valid introduzir um valor novo, o que é intencional: você fica sabendo em tempo de compilação.

Exemplos de retorno

Sucesso — liveness aprovado

LivenessFacetecSDKLivenessState.Success(
    data = LivenessFacetecSDKResultData(
        sessionId = "8f3a9c10-2b7d-4e1f-9c2a-5d6e7f8a9b01",
        status = LivenessFacetecSDKSessionStatus.SESSION_COMPLETED,
        friendlyMessage = "The Session was performed successfully.",
        ageGroup = 7,
        auditTrailImage = "..."
    )
)

Falha — usuário cancelou a captura

LivenessFacetecSDKLivenessState.Error(
    data = LivenessFacetecSDKResultData(
        sessionId = "8f3a9c10-2b7d-4e1f-9c2a-5d6e7f8a9b01",
        status = LivenessFacetecSDKSessionStatus.USER_CANCELLED_FACE_SCAN,
        friendlyMessage = "The user cancelled before performing enough Scans to Succeed.",
        ageGroup = null,
        auditTrailImage = null
    )
)

Cancelamento pelo usuário não é erro técnico — o SDK funcionou corretamente. Trate como desistência no seu app (voltar à tela anterior ou oferecer nova tentativa), sem reportar como falha do SDK.

Exemplo completo

package com.example.myapp

import android.os.Bundle
import android.util.Log
import android.view.View
import android.widget.Button
import android.widget.ProgressBar
import android.widget.TextView
import androidx.appcompat.app.AppCompatActivity
import androidx.lifecycle.lifecycleScope
import com.vcc.vendor.facetec.sdk.LivenessFacetecSDK
import com.vcc.vendor.facetec.sdk.LivenessFacetecSDKLivenessState
import com.vcc.vendor.facetec.sdk.models.LivenessFacetecSDKSessionStatus
import kotlinx.coroutines.flow.catch
import kotlinx.coroutines.launch

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        val btnStart = findViewById<Button>(R.id.btn_start)
        val progress = findViewById<ProgressBar>(R.id.progress)
        val tvResult = findViewById<TextView>(R.id.tv_result)

        btnStart.setOnClickListener {
            btnStart.isEnabled = false
            tvResult.text = ""

            lifecycleScope.launch {
                // 1. Coletar o ssid e criar a sessão no backend
                val sessionData = LivenessFacetecSDK.getSessionData().getOrNull()
                if (sessionData == null) {
                    tvResult.text = "SDK não inicializado"
                    btnStart.isEnabled = true
                    return@launch
                }

                val session = mySessionApi.createSession(
                    body = SessionRequest(ssid = sessionData.ssid)
                )

                // 2. Iniciar a captura com os tokens da sessão
                LivenessFacetecSDK.startLivenessCheck(
                    activity = this@MainActivity,
                    sessionId = session.sessionId,
                    sessionToken = session.sessionToken
                )
                    .catch { e ->
                        Log.e("MainActivity", e.message.orEmpty())
                        progress.visibility = View.GONE
                        tvResult.text = "Erro: ${e.message}"
                        btnStart.isEnabled = true
                    }
                    .collect { state ->
                        when (state) {
                            is LivenessFacetecSDKLivenessState.Loading -> {
                                progress.visibility = View.VISIBLE
                                tvResult.text = "Processando…"
                            }
                            is LivenessFacetecSDKLivenessState.Success -> {
                                progress.visibility = View.GONE
                                tvResult.text = buildString {
                                    appendLine("Liveness finalizado")
                                    appendLine("Session: ${state.data.sessionId}")
                                    appendLine("Age group: ${state.data.ageGroup ?: "n/d"}")
                                }
                                btnStart.isEnabled = true
                            }
                            is LivenessFacetecSDKLivenessState.Error -> {
                                progress.visibility = View.GONE
                                tvResult.text = when (state.data.status) {
                                    LivenessFacetecSDKSessionStatus.USER_CANCELLED_FACE_SCAN,
                                    LivenessFacetecSDKSessionStatus.USER_CANCELLED_ID_SCAN ->
                                        "Verificação cancelada"
                                    LivenessFacetecSDKSessionStatus.LOCKED_OUT ->
                                        "Limite de tentativas atingido"
                                    else -> state.data.friendlyMessage
                                }
                                btnStart.isEnabled = true
                            }
                        }
                    }
            }
        }
    }
}

Timeouts de rede

O SDK usa timeouts fixos, não configuráveis pelo consumer:

Tipo	Valor
Connect timeout	30 segundos
Read timeout	30 segundos
Write timeout	30 segundos

Dimensione a UX de loading e o timeout de fallback do seu app considerando esses valores. Em condições de rede ruim, o Flow pode permanecer em Loading por até 30 segundos antes de emitir o estado terminal.

Parando o SDK

LivenessFacetecSDK.stop() libera os recursos internos do SDK e reseta seu estado, deixando-o como estava antes do primeiro init(). Uma chamada subsequente a init() se comporta como primeiro uso.

LivenessFacetecSDK.stop()

Situação	Ação
Teardown de tela ou sessão (ex.: `onDestroy()` da Activity)	Chame `stop()` para liberar recursos
Entre capturas (fluxo multi-etapa)	Opcional — `init()` é idempotente; use `stop()` apenas se quiser liberar memória
Antes de encerrar o processo	`stop()` garante limpeza ordeira das chaves em memória

Se stop() for chamado durante uma captura em andamento, ela é cancelada imediatamente e o Flow em coleta recebe um Error com status = UNKNOWN_INTERNAL_ERROR — sem travar e sem exceção não tratada. Chamar stop() antes de init(), ou duas vezes seguidas, é um no-op seguro.

O que muda em relação à v9

Área	v9	v10
`init`	`init(applicationContext: Context, config): Result<LivenessFacetecSDKInitData>`	`init(application: Application, config): Result<Unit>` — recebe a `Application` e não devolve mais dados
Device signal	`LivenessFacetecSDKInitData` com `visitorId`/`requestId` (FingerprintJS)	`getSessionData()` devolve `ssid` (perimeter security)
`startLivenessCheck`	`(activity, sessionId, sessionToken, facetecSessionToken)`	`(activity, sessionId, sessionToken)` — não existe mais `facetecSessionToken`
Resultado	12 campos (`status: String`, `result`, `scanResultBlob`, `transactionId`, `replayCheck`, `livenessCheck`, entre outros)	5 campos: `sessionId`, `status` (enum), `friendlyMessage`, `ageGroup?`, `auditTrailImage?`
Veredito	`Success` sempre; conferir `livenessCheck == true` para saber se passou	`status == SESSION_COMPLETED` chega como `Success`; qualquer outro valor chega como `Error`
Erros	`LivenessFacetecSDKError` com `CaptureError`, `SubmitError`, `NetworkError`, `Cancelled`, `Unknown`	O tipo deixou de existir. `Error` carrega o mesmo `LivenessFacetecSDKResultData` de `Success`; a causa está no `status`
Retry	Controlado pelo backend via `canRetry`, dentro da mesma sessão	Acontece dentro da UI do FaceTec e não é exposto ao app — o `Flow` emite apenas o desfecho final. Para tentar de novo depois de um `Error`, crie uma sessão nova no seu backend e chame `startLivenessCheck()` outra vez

Se o seu código v9 lia livenessCheck, result, scanResultBlob ou fazia when sobre subclasses de LivenessFacetecSDKError, esses caminhos precisam ser reescritos — nenhum deles existe na v10.

Primeiros Passos

Onboarding

Bureau

Liveness

Assinatura Digital

ID Check

Card Check

TrustPass

BPO

Extração Dados

Mensageria

Documentoscopia

Storage

Coleção Postman

API pública

Configuração

Dados de sessão

Criação de sessão — responsabilidade do consumer app

Estados do `Flow`

Fluxo de uso

Campos de `LivenessFacetecSDKResultData`

`LivenessFacetecSDKSessionStatus`

Exemplos de retorno

Sucesso — liveness aprovado

Falha — usuário cancelou a captura

Exemplo completo

Timeouts de rede

Parando o SDK

O que muda em relação à v9

Próximos passos

Customização

Solução de problemas

​API pública

​Configuração

​Dados de sessão

​Criação de sessão — responsabilidade do consumer app

​Estados do Flow

​Fluxo de uso

​Campos de LivenessFacetecSDKResultData

​LivenessFacetecSDKSessionStatus

​Exemplos de retorno

​Sucesso — liveness aprovado

​Falha — usuário cancelou a captura

​Exemplo completo

​Timeouts de rede

​Parando o SDK

​O que muda em relação à v9

​Próximos passos

Customização

Solução de problemas

API pública

Configuração

Dados de sessão

Criação de sessão — responsabilidade do consumer app

Estados do `Flow`

Fluxo de uso

Campos de `LivenessFacetecSDKResultData`

`LivenessFacetecSDKSessionStatus`

Exemplos de retorno

Sucesso — liveness aprovado

Falha — usuário cancelou a captura

Exemplo completo

Timeouts de rede

Parando o SDK

O que muda em relação à v9

Próximos passos