Skip to main content
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)
}
ErroQuando aconteceAção recomendada
alreadyInitializedinitialize() foi chamado mais de uma vez no mesmo ciclo de vidaVerifique 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 buildVerificar 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çãoVerificar 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)
}
ErroQuando aconteceAção recomendada
captureErrorA 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.
submitErrorFalha ao submeter a captura para o backendRepetir após reconectar. Se persistir, registre a mensagem e abra chamado.
networkErrorSem conectividade ou timeout HTTPCheque rede do dispositivo. SDK não tenta retry automático.
cancelledUsuário fechou a UI do FaceTecConsidere retorno silencioso para a tela anterior; geralmente não é erro de UX.
unknownExceção não mapeadaReporte 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>
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 simuladorRetorno do FaceTecStatus
initializeInProductionMode(...)falseneverInitialized
initializeInDevelopmentMode(...)falseneverInitialized
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