> ## 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 LivenessIdentySDK (IDENTY Face AI)

Esta página lista os erros emitidos pelo `LivenessIdentySDK`, problemas comuns de build e dicas de diagnóstico.

## Hierarquia `LivenessIdentySDKError`

Todo erro chega via `LivenessIdentySDKLivenessState.Error(error: LivenessIdentySDKError)`:

```kotlin theme={"theme":"catppuccin-latte"}
sealed class LivenessIdentySDKError(override val message: String) : Exception(message) {
    class CaptureError(message: String) : LivenessIdentySDKError(message)
    class SubmitError(message: String) : LivenessIdentySDKError(message)
    class NetworkError(message: String) : LivenessIdentySDKError(message)
    class Cancelled : LivenessIdentySDKError("User cancelled")
    class CameraPermissionDenied : LivenessIdentySDKError("Camera permission denied")
    class CameraPermissionPermanentlyDenied : LivenessIdentySDKError("Camera permission permanently denied")
    class Unknown(message: String) : LivenessIdentySDKError(message)
}
```

| Erro | Quando acontece | Ação recomendada |
| - | - | - |
| `CaptureError` | A captura do IDENTY Face AI falhou: tempo da sessão de captura esgotado, limite de transações excedido, a captura não conseguiu iniciar, ou erro ao configurar o vendor | Apresente UI de "tentar novamente". A `message` contém o motivo informado pelo vendor. |
| `SubmitError` | Falha ao enviar a captura ao backend — inclui erro HTTP e falha de rede ou timeout **durante o envio** | Repita após reconectar. Se persistir, registre `message` e abra chamado. |
| `NetworkError` | O IDENTY Face AI não conseguiu falar com o servidor de liveness ou de licença | Cheque a rede do dispositivo (proxy/firewall). |
| `Cancelled` | Usuário voltou (back) na UI de captura, ou a captura foi pausada (ex.: app foi para segundo plano) | Considere retorno silencioso para a tela anterior; geralmente não é erro de UX. |
| `CameraPermissionDenied` | Usuário recusou o pedido de permissão de câmera feito pelo SDK (a permissão ainda pode ser pedida de novo) | Explique por que a câmera é necessária e permita tentar novamente. |
| `CameraPermissionPermanentlyDenied` | Permissão de câmera negada permanentemente — o sistema não exibe mais o pedido | Redirecione o usuário para as configurações do app (`openAppSettings()`). |
| `Unknown` | `startLivenessCheck()` chamado antes de `init()`; licença IDENTY ausente ou duplicada (veja [Licença IDENTY](#licença-identy)); falha ao inicializar o IDENTY Face AI; demais erros do vendor não mapeados | Confira a ordem `init()` → `startLivenessCheck()`. Se persistir, reporte com `message` para a equipe da Valid. |

### Exemplo de tratamento

```kotlin theme={"theme":"catppuccin-latte"}
import com.vcc.vendor.identy.sdk.models.LivenessIdentySDKError

fun handleError(error: LivenessIdentySDKError) {
    when (error) {
        is LivenessIdentySDKError.Cancelled                          -> return // usuário cancelou
        is LivenessIdentySDKError.CaptureError                       -> showError("Falha na captura: ${error.message}")
        is LivenessIdentySDKError.SubmitError                        -> showError("Falha ao enviar: ${error.message}")
        is LivenessIdentySDKError.NetworkError                       -> showError("Sem conexão: ${error.message}")
        is LivenessIdentySDKError.CameraPermissionDenied             -> showMessage("A câmera é necessária — tente de novo")
        is LivenessIdentySDKError.CameraPermissionPermanentlyDenied  -> openAppSettings()
        is LivenessIdentySDKError.Unknown                            -> showError("Erro desconhecido: ${error.message}")
    }
}
```

## Problemas comuns de build

### `Dependency ... requires core library desugaring to be enabled`

O SDK é compilado com *core library desugaring*, e o Android Gradle Plugin exige o mesmo no app (task `checkAarMetadata`). Habilite-o conforme [Instalação](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/android/instalacao.md):

```kotlin theme={"theme":"catppuccin-latte"}
android {
    compileOptions {
        isCoreLibraryDesugaringEnabled = true
    }
}

dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.4")
}
```

### `Duplicate class org.bouncycastle...`

O seu app já usa outra variante do BouncyCastle além da `bcprov-jdk16` trazida pelo SDK. Exclua a transitiva do SDK, conforme o aviso em [Instalação](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/android/instalacao.md).

### `Manifest merger failed ... android:networkSecurityConfig`

O seu app e o SDK declaram `networkSecurityConfig`. Adicione `tools:replace="android:networkSecurityConfig"` ao `<application>` do seu manifest — veja [Manifest merge](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/android/instalacao.md#manifest-merge).

### `401 Unauthorized` ao resolver `liveness-identy-sdk` ou `identy-face`

As credenciais do repositório Maven da Valid estão ausentes, incorretas ou expiradas. Confira `vccMobileSdksUsername`/`vccMobileSdksPassword` no `~/.gradle/gradle.properties` (ou as variáveis `ORG_GRADLE_PROJECT_*` no CI) e solicite novas credenciais à equipe da Valid se necessário.

### `Could not find com.shield.android:partner-fraud`

O repositório da biblioteca de fingerprint (`https://cashshield-sdk.s3.amazonaws.com/release/`) não está declarado no `settings.gradle.kts`. Veja [Instalação](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/android/instalacao.md).

## Licença IDENTY

A licença do IDENTY Face AI vai dentro do AAR. Quando há problema com ela, a captura termina com `LivenessIdentySDKError.Unknown`:

| Mensagem | Causa | Ação |
| - | - | - |
| `Nenhum arquivo .lic encontrado em assets/ ...` | A licença não está no APK final | Reporte à equipe da Valid com a versão do SDK |
| `Mais de um arquivo .lic em assets/ (...) — exatamente um é esperado.` | Seu app (ou outra dependência) também coloca um `.lic` em `assets/` | Remova o `.lic` extra do seu app |

Se a captura falhar logo após trocar o package ID ou a chave de assinatura do app, confirme com a equipe da Valid se a licença cobre os novos valores.

## Comportamento de logging

O AAR distribuído é sempre o build de release do SDK, **independentemente do build type do seu app**: o log HTTP fica desligado e todas as chamadas a `android.util.Log` do SDK são removidas pelo R8. Nenhum log do SDK chega ao Logcat, nem em builds debug do seu app.

## Timeouts de rede

O SDK usa OkHttp com timeouts fixos, não configuráveis pelo consumer:

| Tipo | Valor |
| - | - |
| Connect timeout | 30 segundos |
| Read timeout | 30 segundos |
| Write timeout | 30 segundos |

## Sentry

O SDK usa o Sentry para reportar apenas as exceções que ele mesmo captura internamente — sem rastreamento de sessão, sem breadcrumbs e sem handler global de crash. Ele usa uma instância **isolada** do Sentry e não interfere no Sentry do seu app, exceto pelo meta-data `io.sentry.auto-init` descrito em [Manifest merge](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/android/instalacao.md#manifest-merge).

> [!NOTE]
>
> A dependência `sentry-android` chega transitivamente pelo `liveness-identy-sdk` — não é preciso declará-la no seu app.

## ProGuard / R8

O AAR já contém um `consumer-rules.pro` aplicado automaticamente pelo AGP ao app cliente. Ele cobre as classes públicas do SDK, o vendor IDENTY Face AI e as demais dependências internas — nenhuma regra manual para esses itens é necessária.

### Configuração obrigatória para apps com `isMinifyEnabled = true`

```proguard theme={"theme":"catppuccin-latte"}
-dontoptimize
```

> [!WARNING]
>
> Mantenha `-dontoptimize` no ProGuard do app consumidor em R8 Full Mode. A recomendação é uma precaução: o R8 emite um aviso de *stack map table* inválida no código do IDENTY Face AI durante a minificação, o mesmo tipo de sintoma que já causou falhas de runtime em outro SDK de liveness. Mantenha a regra até que a Valid comunique o contrário.

## Próximos passos

> **[Implementação](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/android/implementacao.md)**
>
> Volte para a referência de uso do SDK

> **[Customização](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/android/customizacao.md)**
>
> Veja como personalizar a UI do vendor Identy


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.