> ## Documentation Index
> Fetch the complete documentation index at: https://docs-platform.services-valid.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Solução de problemas

> Diagnóstico por status e problemas comuns do LivenessFacetecSDK v10 no Android

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

```kotlin theme={"theme":"catppuccin-latte"}
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)
    }
}
```

<Info>
  `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.
</Info>

## 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](/plataforma/liveness/facetec/v10/sdk/android/instalacao#configurar-app-build-gradle-kts).

### `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:

```kotlin theme={"theme":"catppuccin-latte"}
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`:

```kotlin theme={"theme":"catppuccin-latte"}
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](/plataforma/liveness/facetec/v10/sdk/android/instalacao#requisitos-minimos).

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

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

<Info>
  `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.
</Info>

### 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](/plataforma/liveness/facetec/v10/sdk/android/instalacao#proguard-r8). Abaixo, os sintomas que indicam que elas estão faltando.

<Info>
  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.
</Info>

### 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:

<Steps>
  <Step title="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.
  </Step>

  <Step title="Confirme conectividade">
    O dispositivo precisa alcançar os endpoints da Plataforma ID. Teste em uma rede sem proxy/firewall corporativo.
  </Step>

  <Step title="Valide o AAR">
    Verifique se o `.aar` em `app/libs/` está íntegro e contém `classes.jar`, `proguard.txt` e a pasta `jni/`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Confirme as dependências externas">
    Faltar qualquer dependência externa quebra o init com `ClassNotFoundException`. Confira a lista completa em [Instalação](/plataforma/liveness/facetec/v10/sdk/android/instalacao#configurar-app-build-gradle-kts).
  </Step>

  <Step title="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](#diagnostico-por-status) mapeia cada valor para a ação recomendada.
  </Step>
</Steps>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Implementação" icon="code" iconType="regular" href="/plataforma/liveness/facetec/v10/sdk/android/implementacao">
    Volte para a referência de uso do SDK
  </Card>

  <Card title="Customização" icon="palette" iconType="regular" href="/plataforma/liveness/facetec/v10/sdk/android/customizacao">
    Veja como personalizar a UI do FaceTec
  </Card>
</CardGroup>