Solução de problemas

Esta página lista como diagnosticar uma captura que falhou, os problemas comuns de build e dicas de diagnóstico.

Diagnóstico por status

Na v10 não existe um tipo de erro separado — LivenessFacetecSDKError não existe. Toda falha chega como LivenessFacetecSDKLivenessState.Error(data), carregando o mesmo LivenessFacetecSDKResultData do caso de sucesso. A causa está inteiramente no data.status:

Status	Quando acontece	Ação recomendada
`REQUEST_ABORTED`	A aplicação abortou a requisição de sessão	Verifique se a sessão criada no backend é válida e não expirou. Crie uma sessão nova e tente novamente.
`USER_CANCELLED_FACE_SCAN`	Usuário fechou a UI do FaceTec antes de completar os scans	Retorno silencioso para a tela anterior; geralmente não é erro de UX.
`USER_CANCELLED_ID_SCAN`	Usuário cancelou antes de completar os scans de documento	Mesmo tratamento do caso anterior.
`LOCKED_OUT`	O limite de tentativas da sessão foi atingido	Não reabra a captura imediatamente. Informe o usuário e crie uma sessão nova depois de um intervalo.
`CAMERA_ERROR`	A câmera selecionada não está ativa	Oriente o usuário a fechar outros apps que estejam usando a câmera e apresente UI de “tentar novamente”.
`CAMERA_PERMISSIONS_DENIED`	Usuário não concedeu (ou negou anteriormente) a permissão de câmera	Direcione o usuário às configurações do app para habilitar a câmera.
`UNKNOWN_INTERNAL_ERROR`	Erro interno inesperado, incluindo falhas de rede e `stop()` chamado durante uma captura	Apresente UI de “tentar novamente”. Se persistir, registre o `sessionId` e abra chamado com a equipe da Valid.

Exemplo de tratamento

import com.vcc.vendor.facetec.sdk.models.LivenessFacetecSDKResultData
import com.vcc.vendor.facetec.sdk.models.LivenessFacetecSDKSessionStatus

fun tratarFalha(data: LivenessFacetecSDKResultData) {
    when (data.status) {
        LivenessFacetecSDKSessionStatus.USER_CANCELLED_FACE_SCAN,
        LivenessFacetecSDKSessionStatus.USER_CANCELLED_ID_SCAN ->
            return // usuário desistiu — sem mensagem de erro

        LivenessFacetecSDKSessionStatus.CAMERA_PERMISSIONS_DENIED ->
            abrirConfiguracoesDoApp()

        LivenessFacetecSDKSessionStatus.LOCKED_OUT ->
            mostrarSnackbar("Limite de tentativas atingido. Tente novamente mais tarde.")

        LivenessFacetecSDKSessionStatus.SESSION_COMPLETED ->
            return // não ocorre em Error

        else ->
            mostrarSnackbar(data.friendlyMessage)
    }
}

friendlyMessage já vem pronto para exibição e é fixo por status. Use-o como fallback e trate explicitamente apenas os status que exigem uma ação diferente no seu fluxo.

Problemas comuns de build

`ClassNotFoundException` em runtime para uma dependência externa

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

`Class not found` para as classes do Shield

O repositório do Shield não foi declarado no settings.gradle.kts. Garanta que estes estão presentes:

google()
mavenCentral()
maven(url = "https://cashshield-sdk.s3.amazonaws.com/release/")

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

O número de métodos do dex excedeu 65.535. Em defaultConfig:

multiDexEnabled = true

Erro de `minCompileSdk` na resolução da dependência

O aar-metadata do SDK exige compileSdk = 36 e isCoreLibraryDesugaringEnabled = true. Confira os dois em Instalação.

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

A captura foi coletada antes de init() completar com sucesso.

startLivenessCheck() devolve um Flow cold: a exceção surge no momento da coleta (.collect { }), não na chamada da função. Garanta que init() retornou Result.success(...) antes de habilitar o botão de captura, ou trate a exceção com .catch { } no coletor.

O fluxo não inicia em emulador

O SDK só distribui bibliotecas nativas para armeabi-v7a e arm64-v8a. Em emulador x86/x86_64 o fluxo não executa — teste em dispositivo físico ou em emulador com imagem ARM.

Logging

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.

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

As regras completas exigidas pelo build de release estão em Instalação — ProGuard / R8. Abaixo, os sintomas que indicam que elas estão faltando.

Mesmo com o problema corrigido, vale manter no seu roteiro de testes a validação de duas capturas consecutivas num build release minificado em device real. É a verificação mais barata contra qualquer regressão de minificação — que, por natureza, só aparece a partir da segunda captura.

NoClassDefFoundError em release com minificação ligada

Valide se o proguard.txt do AAR foi efetivamente mesclado abrindo o mapping.txt gerado pelo R8. Confira também se as regras do Koin (-keep class org.koin.** { *; }) estão presentes — o Koin 4.x não empacota regras consumer próprias.

Verificação de saúde

Use este checklist quando o SDK não inicializar:

Cheque a chave de API do seu backend do seu backend

A chave nunca é usada pelo app — ela vive no seu backend, na chamada de criação da sessão. Confirme queA chave nunca é usada pelo app — ela vive no seu backend, na chamada de criação da sessão. Confirme que está ativa na sua conta da Plataforma ID.

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 .aar em app/libs/ está íntegro e contém classes.jar, proguard.txt e a pasta jni/.

Valide as bibliotecas nativas por ABI

Confirme que o APK traz arm64-v8a e armeabi-v7a com libvccvendorkeys.so, libe14c.so e libPhoenixAndroid.so, e que o teste está rodando em hardware ARM.

Confirme as dependências externas

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

Colete o status da falha

Como o SDK não emite logs em release, use os retornos da própria API: confirme se init() devolveu Result.success(...) e, na captura, registre o data.status e o data.friendlyMessage recebidos em LivenessFacetecSDKLivenessState.Error. O Diagnóstico por status mapeia cada valor para a ação recomendada.

Primeiros Passos

Onboarding

Bureau

Liveness

Assinatura Digital

ID Check

Card Check

TrustPass

BPO

Extração Dados

Mensageria

Documentoscopia

Storage

Coleção Postman

Diagnóstico por status

Exemplo de tratamento

Problemas comuns de build

`ClassNotFoundException` em runtime para uma dependência externa

`Class not found` para as classes do Shield

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

Erro de `minCompileSdk` na resolução da dependência

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

O fluxo não inicia em emulador

Logging

Sentry

ProGuard / R8

NoClassDefFoundError em release com minificação ligada

Verificação de saúde

Próximos passos

Implementação

Customização

​Diagnóstico por status

​Exemplo de tratamento

​Problemas comuns de build

​ClassNotFoundException em runtime para uma dependência externa

​Class not found para as classes do Shield

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

​Erro de minCompileSdk na resolução da dependência

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

​O fluxo não inicia em emulador

​Logging

​Sentry

​ProGuard / R8

​NoClassDefFoundError em release com minificação ligada

​Verificação de saúde

​Próximos passos

Implementação

Customização

Diagnóstico por status

Exemplo de tratamento

Problemas comuns de build

`ClassNotFoundException` em runtime para uma dependência externa

`Class not found` para as classes do Shield

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

Erro de `minCompileSdk` na resolução da dependência

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

O fluxo não inicia em emulador

Logging

Sentry

ProGuard / R8

NoClassDefFoundError em release com minificação ligada

Verificação de saúde

Próximos passos