Skip to main content
Esta página lista os erros emitidos pelo LivenessFacetecSDK, problemas comuns de build e dicas de diagnóstico.

Hierarquia LivenessFacetecSDKError

Todo erro chega via LivenessFacetecSDKLivenessState.Error(error: LivenessFacetecSDKError). A sealed class cobre seis categorias:
sealed class LivenessFacetecSDKError(val message: String) {
    class CaptureError(message: String) : LivenessFacetecSDKError(message)
    class SubmitError(message: String) : LivenessFacetecSDKError(message)
    class NetworkError(message: String) : LivenessFacetecSDKError(message)
    class Cancelled : LivenessFacetecSDKError("User cancelled")
    class Unknown(message: String) : LivenessFacetecSDKError(message)
}
ErroQuando aconteceAção recomendada
CaptureErrorA captura biométrica do FaceTec falhou (ex.: timeout, falha de qualidade, erro interno do motor)Apresente UI de “tentar novamente”. A message do erro contém o motivo do FaceTec.
SubmitErrorFalha ao submeter a captura para o backendRepetir após reconectar. Se persistir, registre message e abra chamado.
NetworkErrorSem conectividade ou timeout HTTPCheque rede do dispositivo. SDK não tenta retry automático.
CancelledUsuário fechou a UI do FaceTecConsidere retorno silencioso para a tela anterior; geralmente não é erro de UX.
UnknownExceção não mapeadaReporte com message para a equipe da Valid.

Exemplo de tratamento

import com.vcc.vendor.facetec.sdk.models.LivenessFacetecSDKError

fun handleError(error: LivenessFacetecSDKError) {
    val msg = when (error) {
        is LivenessFacetecSDKError.CaptureError -> "A captura falhou: ${error.message}"
        is LivenessFacetecSDKError.SubmitError -> "Falha ao enviar. Verifique sua conexão."
        is LivenessFacetecSDKError.NetworkError -> "Sem conexão com a internet."
        is LivenessFacetecSDKError.Cancelled -> return // usuário cancelou
        is LivenessFacetecSDKError.Unknown -> "Erro inesperado: ${error.message}"
    }
    showSnackbar(msg)
}

Problemas comuns de build

Class not found em runtime para uma dependência externa

Algum repositório obrigatório não foi declarado no settings.gradle.kts. Garanta que estes estão presentes:
google()
mavenCentral()
maven { url = uri("https://maven.fpregistry.io/releases") }

DexArchiveBuilderException: method ID not in [0, 0xffff]

Faltou habilitar multiDex. Em defaultConfig:
multiDexEnabled = true

ClassNotFoundException em runtime para uma dependência externa

As bibliotecas de terceiros não são incluídas no Fat AAR. Você precisa declará-las como implementation no seu app — veja a lista completa em Instalação.

IllegalStateException: LivenessFacetecSDK not initialized. Call init() first.

startLivenessCheck foi chamado antes de init completar. Sempre aguarde o Result.success(Unit) do init antes de habilitar o botão de captura.

Logging em builds debug

Em builds debug, o SDK registra as requisições HTTP via interceptor do OkHttp no nível BODY (método, URL, status, headers e corpo). Os headers x-api-key e Authorization são automaticamente substituídos por ***REDACTED*** antes de chegar ao Logcat — o valor real nunca aparece em logs. Em builds release, todas as chamadas a android.util.Log do SDK são removidas pelo R8 via -assumenosideeffects. Nenhum log do SDK chega ao Logcat em produção, independentemente do nível configurado pelo seu app. Para inspecionar a sequência de inicialização ou requisições, filtre o Logcat por LivenessFacetecSDK, OkHttp e FaceTec em uma build debug.

Sentry

A dependência io.sentry:sentry-android deve ser declarada no app cliente — o AAR referencia classes do Sentry em tempo de compilação e a ausência da dependência quebra a build com NoClassDefFoundError.

ProGuard / R8

O AAR já distribui um consumer-rules.pro que mantém a API pública do LivenessFacetecSDK (com.vcc.vendor.facetec.sdk.**), as classes do FaceTec (com.facetec.sdk.**) e o que é necessário em runtime.
  • A API pública do LivenessFacetecSDK em com.vcc.vendor.facetec.sdk.**.
  • As classes do FaceTec SDK em com.facetec.sdk.**.
  • As demais classes do SDK e de suas dependências necessárias em runtime.

VerifyError na segunda captura (R8 Full Mode / AGP 9.x+)

Sintoma: a primeira captura FaceTec funciona normalmente; a segunda lança java.lang.VerifyError em classes internas do motor (ex: nc.e(int, int)). Causa: o R8 Full Mode (ativado por padrão no AGP 9.x+) aplica passes de otimização de bytecode sobre o .jar pré-compilado do FaceTec, corrompendo atribuições de registradores em algumas classes internas. Correção: adicione ao proguard-rules.pro do app cliente:
# ── FaceTec SDK — OBRIGATÓRIO com R8 Full Mode (AGP 9.x+) ─────────────────────
# Desativa apenas os passes de otimização do R8; shrinking e obfuscation
# permanecem ativos. Sem essa regra, o FaceTec lança VerifyError na segunda
# captura em builds release.
-dontoptimize
-dontoptimize desativa somente a etapa de otimização do R8. Shrinking (remoção de código não usado) e obfuscation (renomeação) continuam funcionando normalmente — o tamanho do APK não é afetado de forma significativa.
As dependências externas abaixo empacotam suas próprias regras consumer dentro dos respectivos artefatos — você não precisa de regras manuais para elas:
DependênciaRegras consumer embutidas desde
Retrofit 3.x2.9.0+
OkHttp 5.xembutido no AAR do projeto
kotlinx-serialization 1.11.x1.5.0+
kotlinx-coroutines 1.10.x1.7.0+
Sentry Android 8.xembutido no artefato
FaceTec 9.7.117consumer-rules.pro do SDK
FingerprintJS Pro 2.xconsumer-rules.pro do SDK
Se o app cliente tiver isMinifyEnabled = true, adicione ao seu proguard-rules.pro apenas as dependências que não empacotam regras próprias:
# ── Koin 4.x — não empacota consumer ProGuard rules ───────────────────────────
-keep class org.koin.** { *; }
-dontwarn org.koin.**

# ── FingerprintJS Pro — não empacota consumer ProGuard rules ──────────────────
-keep class com.fingerprintjs.** { *; }
-dontwarn com.fingerprintjs.**
Se o seu app usar Retrofit diretamente com interfaces anotadas, pode ser necessário preservar anotações em runtime:
-keepattributes RuntimeVisibleAnnotations, RuntimeVisibleParameterAnnotations
Se observar NoClassDefFoundError em release com minificação ligada, valide se o consumer-rules.pro do AAR foi efetivamente mesclado abrindo o mapping.txt gerado pelo R8.

Verificação de saúde

Use este checklist quando o SDK não inicializar:
1

Cheque a chave de API

Confirme que a apiKey informada está ativa na sua conta da Plataforma ID.
2

Confirme conectividade

O dispositivo precisa alcançar os endpoints da Plataforma ID. Teste em uma rede sem proxy/firewall corporativo.
3

Valide o AAR

Verifique se o arquivo liveness-facetec-sdk-1.3.0.aar em app/libs/ está íntegro (~12 MB+, contém classes.jar e jni/).
4

Confirme as dependências externas

Faltar qualquer dependência externa quebra o init com ClassNotFoundException. Confira a lista completa em Instalação.
5

Logs detalhados

Filtre o Logcat por LivenessFacetecSDK e FaceTec para inspecionar a sequência de inicialização.

Próximos passos

Implementação

Volte para a referência de uso do SDK

Customização

Veja como personalizar a UI do FaceTec