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

# Troubleshooting

> Resolução de problemas comuns na integração do Liveness Hub SDK para iOS

## Erros Comuns

### Erro: "No such module 'HubLivenessSDK'"

<Accordion title="Causa e Solução">
  **Causa:** O XCFramework não está linkado corretamente ao projeto.

  **Solução:**

  1. Verifique se `HubLivenessSDK.xcframework` está em **Build Phases > Link Binary With Libraries**
  2. Verifique se está em **Build Phases > Embed Frameworks**
  3. Limpe a build: `Cmd + Shift + K`
  4. Reconstrua: `Cmd + B`

  ```
  Build Phases > Link Binary With Libraries
    ✅ HubLivenessSDK.xcframework
    ✅ FaceTecSDK.xcframework

  Build Phases > Embed Frameworks
    ✅ HubLivenessSDK.xcframework (Code Sign On Copy)
    ✅ FaceTecSDK.xcframework (Code Sign On Copy)
  ```
</Accordion>

### Erro: "FaceTecSDK not found" ou Crash na Inicialização

<Accordion title="Causa e Solução">
  **Causa:** A dependência `FaceTecSDK.xcframework` está ausente.

  **Solução:**

  1. Certifique-se de que `FaceTecSDK.xcframework` está na mesma pasta que `HubLivenessSDK.xcframework`
  2. Adicione ambos os frameworks ao projeto
  3. Ambos devem estar em "Link Binary With Libraries" E "Embed Frameworks"

  ```
  seu-projeto/
    HubLivenessSDK.xcframework    ✅
    FaceTecSDK.xcframework        ✅ (obrigatório)
    SeuProjeto.xcodeproj
  ```
</Accordion>

### Erro: "SDK not initialized" ou "notInitialized"

<Accordion title="Causa e Solução">
  **Causa:** O método `initialize` não foi chamado antes de `startLiveness`.

  **Solução:**

  Sempre inicialize o SDK antes de usar:

  ```swift theme={"theme":"catppuccin-latte"}
  // ✅ Correto
  Task {
      do {
          try await HubLiveness.shared.initialize(config: config)
          // Agora pode usar startLiveness
      } catch {
          print("Erro: \(error)")
      }
  }

  // ❌ Incorreto - chamar startLiveness sem inicializar
  try await HubLiveness.shared.startLiveness(riskLevel: .high) { _ in }
  ```
</Accordion>

### Erro: "cameraPermissionDenied"

<Accordion title="Causa e Solução">
  **Causa:** Permissão de câmera não concedida ou não declarada.

  **Solução:**

  1. Adicione a chave no `Info.plist`:

  ```xml theme={"theme":"catppuccin-latte"}
  <key>NSCameraUsageDescription</key>
  <string>Este aplicativo precisa acessar a camera para realizar a verificacao de prova de vida.</string>
  ```

  2. Verifique a permissão antes de iniciar:

  ```swift theme={"theme":"catppuccin-latte"}
  import AVFoundation

  func checkCameraPermission() {
      switch AVCaptureDevice.authorizationStatus(for: .video) {
      case .authorized:
          startLiveness()
      case .notDetermined:
          AVCaptureDevice.requestAccess(for: .video) { granted in
              if granted {
                  DispatchQueue.main.async { self.startLiveness() }
              }
          }
      case .denied, .restricted:
          // Mostrar alerta para abrir configurações
          openSettings()
      @unknown default:
          break
      }
  }

  func openSettings() {
      if let url = URL(string: UIApplication.openSettingsURLString) {
          UIApplication.shared.open(url)
      }
  }
  ```
</Accordion>

### Erro: "invalidConfiguration"

<Accordion title="Causa e Solução">
  **Causa:** Parâmetros de configuração inválidos ou CEK expirado.

  **Solução:**

  1. Verifique se todos os parâmetros estão corretos:

  ```swift theme={"theme":"catppuccin-latte"}
  let config = HubConfig(
      apiBaseUrl: "https://api.example.com",  // URL válida com https
      apiKey: "sk_...",                        // API key válida
      appName: "MeuApp",                       // Nome não vazio
      cek: "eyJ2ZXJzaW9u...",                  // CEK válido em base64
      localization: .ptBR
  )
  ```

  2. Verifique se o CEK não expirou (campo `expiresAt` no JSON decodificado)
  3. Confirme que a URL da API está acessível
</Accordion>

### Erro: "networkError"

<Accordion title="Causa e Solução">
  **Causa:** Problemas de conectividade ou URL da API incorreta.

  **Solução:**

  1. Verifique a conexão com a internet
  2. Confirme que a `apiBaseUrl` está correta
  3. Verifique se a API está acessível:

  ```bash theme={"theme":"catppuccin-latte"}
  curl -I https://api.yourserver.com/health
  ```

  4. Para debug, habilite logs de rede no simulador/dispositivo
</Accordion>

### Erro: "livenessCheckFailed"

<Accordion title="Causa e Solução">
  **Causa:** A verificação de liveness falhou (possível spoofing detectado).

  **Solução:**

  1. Certifique-se de que o ambiente tem boa iluminação
  2. Peça ao usuário para:
     * Remover óculos escuros ou bonés
     * Olhar diretamente para a câmera
     * Manter expressão neutra
  3. Permita que o usuário tente novamente

  ```swift theme={"theme":"catppuccin-latte"}
  case .failure(let error):
      if case .livenessCheckFailed(let reason) = error {
          showRetryAlert(reason: reason)
      }
  ```
</Accordion>

## Configuração de Build

### Erro de Assinatura do Framework

Se encontrar erros de code signing:

1. No Xcode, selecione o xcframework em **Build Phases > Embed Frameworks**
2. Marque **"Code Sign On Copy"**
3. Limpe e reconstrua o projeto

### Erro "Unsupported Architecture"

Para projetos que precisam suportar simulador e dispositivo:

```
Build Settings:
  EXCLUDED_ARCHS[sdk=iphonesimulator*] = arm64  // Para Macs Intel
  // OU
  EXCLUDED_ARCHS[sdk=iphonesimulator*] =        // Para Macs Apple Silicon
```

## Checklist de Verificação

Antes de reportar um problema, verifique os itens abaixo:

<Steps>
  <Step title="Versão do SDK">
    Confirme que está usando a versão mais recente do SDK
  </Step>

  <Step title="XCFrameworks">
    Ambos `HubLivenessSDK.xcframework` e `FaceTecSDK.xcframework` estão incluídos
  </Step>

  <Step title="Build Phases">
    Os frameworks estão em "Link Binary" E "Embed Frameworks"
  </Step>

  <Step title="Inicialização">
    O SDK foi inicializado com `await HubLiveness.shared.initialize(config:)`
  </Step>

  <Step title="Permissões">
    `NSCameraUsageDescription` está declarada no `Info.plist`
  </Step>

  <Step title="Credenciais">
    As credenciais de API e CEK estão corretas e válidas
  </Step>

  <Step title="iOS Version">
    O dispositivo/simulador está rodando iOS 17.0 ou superior
  </Step>
</Steps>

## Logs de Debug

Para debug durante o desenvolvimento, você pode observar os logs do SDK no Console do Xcode:

```swift theme={"theme":"catppuccin-latte"}
// Filtrar logs no Console
// Pesquise por: "HubLiveness" ou "FaceTec"
```

<Warning>
  Em builds de produção, os logs detalhados são automaticamente desabilitados
  para evitar exposição de informações sensíveis.
</Warning>

## Erros de Runtime Específicos

### Crash: "Thread 1: signal SIGABRT"

**Causa comum:** Inicialização em thread incorreta.

**Solução:** Use `@MainActor` para operações do SDK:

```swift theme={"theme":"catppuccin-latte"}
@MainActor
func initializeSDK() async {
    try await HubLiveness.shared.initialize(config: config)
}
```

### Crash ao apresentar câmera

**Causa comum:** View controller não está na hierarquia.

**Solução:** Certifique-se de chamar o liveness de uma view que está visível e ativa.

## Compatibilidade

| iOS Version | Suporte         |
| ----------- | --------------- |
| iOS 17.0+   | ✅ Total         |
| iOS 16.x    | ❌ Não suportado |
| iOS 15.x    | ❌ Não suportado |

| Device    | Suporte                      |
| --------- | ---------------------------- |
| iPhone    | ✅ Total                      |
| iPad      | ✅ Total                      |
| Simulator | ✅ Limitado (sem câmera real) |

## Referências

<CardGroup cols={2}>
  <Card title="Instalação" icon="download" href="/plataforma/liveness/hub/sdk/ios/installation">
    Revise os requisitos e configurações
  </Card>

  <Card title="Implementação" icon="code" href="/plataforma/liveness/hub/sdk/ios/implementation">
    Veja exemplos de código corretos
  </Card>
</CardGroup>