Solução de problemas

Hierarquia de erros e diagnóstico do LivenessFacetecSDK (FaceTec)

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)
}

Erro	Quando acontece	Ação recomendada
CaptureError	A 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.
SubmitError	Falha ao submeter a captura para o backend	Repetir após reconectar. Se persistir, registre message e abra chamado.
NetworkError	Sem conectividade ou timeout HTTP	Cheque rede do dispositivo. SDK não tenta retry automático.
Cancelled	Usuário fechou a UI do FaceTec	Considere retorno silencioso para a tela anterior; geralmente não é erro de UX.
Unknown	Exceção não mapeada	Reporte 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ência	Regras consumer embutidas desde
Retrofit 3.x	2.9.0+
OkHttp 5.x	embutido no AAR do projeto
kotlinx-serialization 1.11.x	1.5.0+
kotlinx-coroutines 1.10.x	1.7.0+
Sentry Android 8.x	embutido no artefato
FaceTec 9.7.117	consumer-rules.pro do SDK
FingerprintJS Pro 2.x	consumer-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