Troubleshooting

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

Erros Comuns

Erro: “No such module ‘HubLivenessSDK’”

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)

Erro: “FaceTecSDK not found” ou Crash na Inicialização

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

Erro: “SDK not initialized” ou “notInitialized”

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:

// ✅ 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 }

Erro: “cameraPermissionDenied”

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:

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

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)
    }
}

Erro: “invalidConfiguration”

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:

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

Erro: “networkError”

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:

curl -I https://api.yourserver.com/health

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

Erro: “livenessCheckFailed”

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

case .failure(let error):
    if case .livenessCheckFailed(let reason) = error {
        showRetryAlert(reason: reason)
    }

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:

1. Versão do SDK

   Confirme que está usando a versão mais recente do SDK

2. XCFrameworks

   Ambos HubLivenessSDK.xcframework e FaceTecSDK.xcframework estão incluídos

3. Build Phases

   Os frameworks estão em “Link Binary” E “Embed Frameworks”

4. Inicialização

   O SDK foi inicializado com await HubLiveness.shared.initialize(config:)

5. Permissões

   NSCameraUsageDescription está declarada no Info.plist

6. Credenciais

   As credenciais de API e CEK estão corretas e válidas

7. iOS Version

   O dispositivo/simulador está rodando iOS 17.0 ou superior

Logs de Debug

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

// Filtrar logs no Console
// Pesquise por: "HubLiveness" ou "FaceTec"

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

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:

@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

Instalação

Revise os requisitos e configurações

Implementação

Veja exemplos de código corretos