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

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

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

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

```kotlin theme={"theme":"catppuccin-latte"}
google()
mavenCentral()
maven { url = uri("https://maven.fpregistry.io/releases") }
```

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

Faltou habilitar `multiDex`. Em `defaultConfig`:

```kotlin theme={"theme":"catppuccin-latte"}
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](/plataforma/liveness/facetec/sdk/android/instalacao#configurar-app-build-gradle-kts).

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

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

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

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:

```proguard theme={"theme":"catppuccin-latte"}
# ── 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.**
```

<Info>
  Se o seu app usar Retrofit diretamente com interfaces anotadas, pode ser necessário preservar anotações em runtime:

  ```proguard theme={"theme":"catppuccin-latte"}
  -keepattributes RuntimeVisibleAnnotations, RuntimeVisibleParameterAnnotations
  ```
</Info>

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:

<Steps>
  <Step title="Cheque a chave de API">
    Confirme que a `apiKey` informada 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 arquivo `liveness-facetec-sdk-1.3.0.aar` em `app/libs/` está íntegro (\~12 MB+, contém `classes.jar` e `jni/`).
  </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/sdk/android/instalacao#configurar-app-build-gradle-kts).
  </Step>

  <Step title="Logs detalhados">
    Filtre o Logcat por `LivenessFacetecSDK` e `FaceTec` para inspecionar a sequência de inicialização.
  </Step>
</Steps>

## Próximos passos

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

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