> ## 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) no iOS
Esta página lista os erros emitidos pelo `LivenessFacetecSDK` para iOS, problemas comuns de build e dicas de diagnóstico.
## Erros de inicialização — `LivenessFacetecSDKInitError`
Lançados por `LivenessFacetecSDKClient.shared.initialize(config:)`:
```swift theme={"theme":"catppuccin-latte"}
public enum LivenessFacetecSDKInitError: Error {
case alreadyInitialized
case provisioningFailed(String)
case facetecInitializationFailed(String)
}
```
| Erro | Quando acontece | Ação recomendada |
| ------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `alreadyInitialized` | `initialize()` foi chamado mais de uma vez no mesmo ciclo de vida | Verifique `LivenessFacetecSDKClient.shared.isInitialized` antes de chamar `initialize()`. Para reinicializar (ex.: logout ou troca de ambiente), chame `stop()` primeiro. |
| `provisioningFailed(String)` | Falha na decifração AES-GCM das chaves internas — blob corrompido ou chaves ausentes no build | Verificar provisionamento de chaves com a equipe Valid. A mensagem fornece diagnóstico. Não está relacionado ao estado de lock do device — chaves são em memória, sem Keychain. |
| `facetecInitializationFailed(String)` | FaceTec SDK rejeitou as chaves internas durante a inicialização | Verificar provisionamento de chaves com a equipe Valid. A mensagem fornece diagnóstico do FaceTec. |
## Erros de fluxo — `LivenessFacetecSDKError`
Todo erro de captura chega via `LivenessFacetecSDKLivenessState.error(LivenessFacetecSDKError)`:
```swift theme={"theme":"catppuccin-latte"}
public enum LivenessFacetecSDKError: Error {
case captureError(String)
case submitError(String)
case networkError(String)
case cancelled
case unknown(String)
}
```
| 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 `String` associada contém o motivo do FaceTec. |
| `submitError` | Falha ao submeter a captura para o backend | Repetir após reconectar. Se persistir, registre a mensagem 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 a mensagem para a equipe da Valid. |
### Exemplo de tratamento
```swift theme={"theme":"catppuccin-latte"}
import LivenessFacetecSDK
func handleError(_ error: LivenessFacetecSDKError) {
let mensagem: String
switch error {
case .captureError(let detalhe):
mensagem = "A captura falhou: \(detalhe)"
case .submitError:
mensagem = "Falha ao enviar. Verifique sua conexão."
case .networkError:
mensagem = "Sem conexão com a internet."
case .cancelled:
return // usuário cancelou
case .unknown(let detalhe):
mensagem = "Erro inesperado: \(detalhe)"
}
mostrarAlerta(mensagem)
}
```
## Problemas comuns de build
### Crash em runtime ao iniciar a captura
O `Info.plist` não declara `NSCameraUsageDescription`. O iOS termina o processo assim que o SDK tenta acessar a câmera.
Adicione:
```xml theme={"theme":"catppuccin-latte"}
NSCameraUsageDescription
Esta permissão é necessária para verificação de identidade por biometria facial.
```
### Erro de link `library not found for -lLivenessFacetecSDK`
O XCFramework não está sendo embarcado no target. Cheque em **General → Frameworks, Libraries, and Embedded Content** que o pacote está listado e marcado como **Embed & Sign**.
### Erro de deployment target
```text theme={"theme":"catppuccin-latte"}
Module compiled with Swift X.Y cannot be imported by the Swift Z.W compiler
```
ou
```text theme={"theme":"catppuccin-latte"}
'LivenessFacetecSDK' requires iOS 14.0 or later
```
Garanta **iOS Deployment Target ≥ 14.0** no projeto e no target.
### `alreadyInitialized` em runtime
`initialize()` foi chamado enquanto o SDK já estava inicializado. Verifique `LivenessFacetecSDKClient.shared.isInitialized` antes de chamar. Para reinicializar (ex.: logout ou troca de ambiente), chame `stop()` primeiro.
## Limitação do simulador
O FaceTec SDK **não suporta execução real no simulador iOS**. Esta é uma limitação deliberada do vendor.
**Causa técnica:** o XCFramework do FaceTec inclui, no slice de simulador (`ios-arm64_x86_64-simulator`), um **binário stub** com a classe `ZoomStubs`. Os métodos de inicialização sempre invocam o completion handler com `false`, retornando status `neverInitialized` — independentemente de modo (`initializeInDevelopmentMode` ou `initializeInProductionMode`).
| Chamada em simulador | Retorno do FaceTec | Status |
| ---------------------------------- | ------------------ | ------------------ |
| `initializeInProductionMode(...)` | `false` | `neverInitialized` |
| `initializeInDevelopmentMode(...)` | `false` | `neverInitialized` |
O XCFramework inclui o slice de simulador (`arm64 + x86_64`) **apenas para permitir que o app consumidor compile e linke** sem erros. O fluxo de liveness, porém, jamais executa em simulador — ele apenas falha rapidamente.
**Testes** de fluxo completo de liveness devem ser realizados em **dispositivo físico**.
## Verificação de saúde
Use este checklist quando o SDK não inicializar:
Verifique se está usando `LivenessFacetecSDK-1.3.0-Release.xcframework` (não uma versão Debug ou um build anterior).
O dispositivo precisa alcançar os endpoints da Plataforma ID. Teste em uma rede sem proxy/firewall corporativo.
Verifique se `LivenessFacetecSDK-1.3.0-Release.xcframework/ios-arm64/LivenessFacetecSDK.framework/Frameworks/` contém `FaceTecSDK.framework` e `FingerprintPro.framework`.
Sem ela, qualquer instalação em device físico crasha logo no `dlopen`.
A captura é abortada pelo iOS se essa chave não estiver no `Info.plist`.
O simulador retorna `neverInitialized` por design (veja seção acima).
## Próximos passos
Volte para a referência de uso do SDK
Veja como personalizar a UI do FaceTec