Tratando Falhas

Referência para eventos de delegate do Certta Liveness, erros bloqueantes e mapeamento de falhas no iOS, incluindo tratamento de sucesso, diagnóstico e orientação de UI.

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

Quando uma verificação de vivacidade falha, o SDK retorna um LivenessFailure objeto. Esse objeto contém um causa parâmetro, que é um identificador de string que informa exatamente por que o processo não foi bem-sucedido.

Entender e lidar com o causa parâmetro é fundamental para fornecer feedback claro e acionável aos seus usuários, para que eles possam corrigir o problema e tentar novamente.

---

Callbacks do delegado (CerttaLivenessDelegate)

Delegado	Significado
didFail(_:)	Falha de negócio: o fluxo foi concluído, mas o resultado não foi aceito (LivenessFailure).

---

Ao usar o causa Parâmetro

O causa parâmetro, retorna uma string literal constante bruta (por exemplo, "TOO_DARK" ou "FACE_TOO_FAR").

Melhor prática: não exiba essas strings brutas diretamente aos seus usuários finais. Em vez disso, interceptar o causa string e mapeá-la para uma mensagem localizada e amigável ao usuário na interface do seu app para orientá-los sobre como corrigir o problema.

Causas de falha disponíveis

Ao usar o iProov provedor, se a captura da imagem for bem-sucedida, mas o mecanismo falhar ao autenticar ou processar o rosto, o SDK retorna um FaceRecognitionFailure.

Abaixo está a lista dos possíveis causa valores retornados especificamente durante esta fase:

Estável causa valores

causa	Dica
unknown	Não classificado
too_much_movement	Movimento excessivo da cabeça
too_bright, too_dark, lighting_issues	Iluminação
misaligned_face	Não alinhado com o guia
eyes_closed	Olhos fechados
face_too_far, face_too_close	Distância
sunglasses, eyewear	Óculos
obscured_face	Rosto coberto
multiple_faces	Mais de um rosto
face_not_found	Nenhum rosto na região
frames_blurry	Muito desfocado
motion_issue	Movimento
background_issue	Plano de fundo / contraste
device_issue, device_restart	Dispositivo
system_error	Sistema
rejeitado, timeout, user_not_found, processing_fault	Transação / servidor

---

Exemplo de implementação

Aqui está um exemplo de como você pode tratar um LivenessFailure e mapear o causa parâmetro para orientações úteis ao usuário:

func mapFailureToUX(_ failure: LivenessFailure) -> (code: String, message: String) {
    switch failure {
    case .imageCaptureFailure(let text):
        return ("image_capture", text)
    case .faceRecognitionFailure(_, let cause):
        let code = cause.lowercased()
        let message = localizedHint(forCause: code) ?? "Falha na verificação. Tente novamente."
        return (code, message)
    }
}

private func localizedHint(forCause cause: String) -> String? {
    switch cause {
    case "too_dark", "too_bright", "lighting_issues":
        return "Melhore a iluminação e tente novamente."
    case "multiple_faces":
        return "Apenas uma pessoa deve estar na câmera."
    case "timeout":
        return "O tempo acabou. Tente novamente."
    default:
        return nil
    }
}