Face Liveness

Instale e configure o Face Liveness para iOS com os SDKs do CafSDK. Saiba mais sobre requisitos, configuração de sessão, fluxo de verificação de vida facial, configuração de UI, delegates, temas e suporte.

Este guia abrange a versão 7.0.0 e superiores. Para versões anteriores à 7.0.0, consulte a documentação legada.

Visão geral

Este guia abrange a instalação do SDK, a inicialização da sessão e como acionar o fluxo de Face Liveness.

Pré-requisitos

Antes de prosseguir, certifique-se de que o CAF SDK esteja instalado corretamente. Se você ainda não fez isso, consulte nosso Guia de Instalação.

Iniciando o Face Liveness

Para iniciar o fluxo de liveness, use a instância singleton e forneça os parâmetros de configuração necessários. Use o handler de conclusão para gerenciar os eventos e resultados da sessão.

CerttaLiveness.shared.open(
    from: self, // Este é o view controller e o delegate
    configuration: LivenessConfiguration(
        maxRetryAttempts: 3,
        faceAuthEnabled: false,
        showLoading: true,
        useFaceLivenessUi: true 
    )
) 

---

LivenessConfiguration Parâmetros

Todos os parâmetros têm padrões; substitua apenas o que você precisar.

Parâmetro	Padrão	Descrição
maxRetryAttempts	3	Número máximo de tentativas após uma tentativa de captura com falha.
faceAuthEnabled	false	Quando ativado, o SDK executa autenticação facial.
showLoading	true	Exibe indicadores de carregamento durante o processamento quando true.
useFaceLivenessUi	false	Se ativado, o SDK usa a UI integrada da Certta.

Entendendo Eventos e Resultados do Liveness

A CerttaLiveness.instance.open() atribui seu controller a um delegate, para o qual você precisa declarar estes métodos:

Garanta que a resposta JWT seja avaliada no backend. Esse processo deve incluir a validação da assinatura do token e a verificação dos estáVivo e éCorrespondente campos. Não realize essas validações no lado do cliente.

extension CerttaViewController: CerttaLivenessDelegate, CerttaDelegate {
    func didFinish(signedResponse: String) {
        let out = formView.outputView
        out.text += "✅ Captura concluída com sucesso\n"    
    }

    func didFail(_ failure: LivenessFailure) {
    let out = formView.outputView
    switch failure {
    case .faceRecognitionFailure(let result, let cause):
        out.text += "❌ Falha no liveness (face): causa=\(cause), resultado=\(result)\n\n"
    case .imageCaptureFailure(let message):
        out.text += "❌ Falha no liveness (captura): \(message)\n\n"
        }
    }
  
    func didFinishWith(_ error: CerttaError) {
        let out = formView.outputView
        switch error {
        case .initializationError(let message): out.text += "❌ Erro: \(message)\n\n"
        case .permissionError(let message): out.text += "❌ Erro: permissão - \(message)\n\n"
        case .securityError(let message): out.text += "❌ Erro: segurança - \(message)\n\n"
        case .unknownError(let message): out.text += "❌ Erro: \(message)\n\n"
        case .networkError(let message): out.text += "❌ Erro: rede - \(message)\n\n"
        }
    }
    func didLog(level: String, message: String) {
        print("nível: \(level), mensagem: \(message)")
    }
}

didFinish(signedResponse: String)

A string é o resultado assinado do módulo. Sua documentação de integração do backend ou do CAF define como validar, decodificar, e armazenar isso. Não registre o token completo em builds de produção.

didFail(_ failure: LivenessFailure)

Existem dois tipos de LivenessFailure:

Caso	Quando
.imageCaptureFailure(String)	Problemas durante a captura (ambiente, timeout, sem rosto, mensagens específicas do provedor, etc.). A string é destinada a diagnóstico ou mensagens de UX.
.faceRecognitionFailure(response: String, cause: String)	A captura foi bem-sucedida, mas o reconhecimento facial / backend não aceitou o resultado. causa explica a rejeição e resultado é o payload assinado

didFinishWith(_ error: CerttaError)

Disparado quando um bloqueio técnico impede o SDK de iniciar ou concluir o processo, como permissões de câmera negadas, ausência de conexão com a internet ou falhas na inicialização do hardware.

Evento	Causa típica
initializationError	configure não chamado, token ou ID de usuário vazio, ou inválido maxRetryAttempts.
permissionError	Permissão da câmera (ou relacionada) negada.
networkError	Problemas de conectividade ou do lado do servidor são apresentados como erros da classe network.
securityError	As verificações de segurança falharam.
unknownError	Outras falhas não mapeadas para um caso específico.

CerttaError conforma-se a LocalizedError. Use localizedDescription (ou message) em alertas.

didLog(level: String, message: String)

Usado para eventos de progresso e informativos ; por exemplo:

• Estados Loading / Loaded: mensagens que você pode mapear para a UI ou analytics.

---

Permissões e experiência do usuário

• Solicite acesso à câmera antes de abrir o Face Liveness se o fluxo do seu app permitir; caso contrário, o SDK pode retornar permissionError.
• Garanta boa iluminação e um texto que explique por que o usuário precisa concluir uma breve captura ao vivo.

---

Temas de cores

• Certta: use a colorConfiguration e useFaceLivenessUi em LivenessConfiguration da sessão para personalizar a UI do Face Liveness.
• Modo escuro / claro: construa CafColorConfiguration usando UITraitCollection.current.userInterfaceStyle se você precisar de paletas diferentes

Certta.shared.setColorConfiguration(CafColorConfiguration(
        primaryColor: "#FFFFFF",
        secondaryColor: "#222222",
        contentColor: "#FFFFFF",
        backgroundColor: "#000000",
        mediumColor: "#555555",
        dialogBackgroundColor: "#1C1C1E",
        dialogBorderColor: "#E5E5E7"
      )
)

Propriedade	Tipo	Descrição	Formato
primaryColor	String	Botões principais, destaques.	Código hexadecimal (ex.: #FF0000)
secondaryColor	String	Elementos secundários, bordas.	Código hexadecimal
contentColor	String	Texto e ícones.	Código hexadecimal
backgroundColor	String	Fundo da tela.	Código hexadecimal
mediumColor	String	Elementos neutros (por exemplo, barras de progresso).	Código hexadecimal
dialogBackgroundColor	String	Cor de fundo de diálogos e pop-ups.	Código hexadecimal
dialogBorderColor	String	Cor da borda de diálogos e pop-ups.	Código hexadecimal

---

Notas de versão

Veja Registro de alterações para versões, alterações que quebram compatibilidade e Xcode / iOS mínimos.

---

Suporte Técnico e Dicas de Uso

Para mais detalhes e cenários de uso avançado, consulte os seguintes recursos:

• Repositório GitHub: acesse o código-fonte, o acompanhamento de issues e as notas de versão no repositório GitHub do CafSDK.
• FAQs e solução de problemas: confira nossa seção de FAQ para problemas comuns e dicas de solução de problemas.
• Suporte: para assistência adicional, entre em contato com nossa equipe de suporte ou participe do fórum da nossa comunidade de desenvolvedores.

Atualizamos continuamente a documentação à medida que novos recursos e melhorias são lançados. Fique por dentro das próximas atualizações!