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:
| 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
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:
DexArchiveBuilderException: method ID not in [0, 0xffff]
Faltou habilitar multiDex. Em defaultConfig:
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ívelBODY (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ênciaio.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 umconsumer-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
LivenessFacetecSDKemcom.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çajava.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:
-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.| 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 |
isMinifyEnabled = true, adicione ao seu proguard-rules.pro apenas as dependências que não empacotam regras próprias:
Se o seu app usar Retrofit diretamente com interfaces anotadas, pode ser necessário preservar anotações em runtime:
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:Confirme conectividade
O dispositivo precisa alcançar os endpoints da Plataforma ID. Teste em uma rede sem proxy/firewall corporativo.
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/).Confirme as dependências externas
Faltar qualquer dependência externa quebra o init com
ClassNotFoundException. Confira a lista completa em Instalação.Próximos passos
Implementação
Volte para a referência de uso do SDK
Customização
Veja como personalizar a UI do FaceTec