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

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

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

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:

<key>NSCameraUsageDescription</key>
<string>Esta permissão é necessária para verificação de identidade por biometria facial.</string>

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

Module compiled with Swift X.Y cannot be imported by the Swift Z.W compiler

ou

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

1. Confirme o XCFramework correto

   Verifique se está usando LivenessFacetecSDK-1.3.0-Release.xcframework (não uma versão Debug ou um build anterior).

2. Confirme conectividade

   O dispositivo precisa alcançar os endpoints da Plataforma ID. Teste em uma rede sem proxy/firewall corporativo.

3. Valide o XCFramework

   Verifique se LivenessFacetecSDK-1.3.0-Release.xcframework/ios-arm64/LivenessFacetecSDK.framework/Frameworks/ contém FaceTecSDK.framework e FingerprintPro.framework.

4. Confirme a build phase de re-assinatura

   Sem ela, qualquer instalação em device físico crasha logo no dlopen.

5. Confirme `NSCameraUsageDescription`

   A captura é abortada pelo iOS se essa chave não estiver no Info.plist.

6. Teste em dispositivo físico

   O simulador retorna neverInitialized por design (veja seção acima).

Próximos passos

Implementação

Volte para a referência de uso do SDK

Customização

Veja como personalizar a UI do FaceTec