Tratando Falhas

Referência para o tratamento de falhas do Face Liveness no Android. Saiba mais sobre os tipos de LivenessFailure, valores de causa, erros específicos do provedor e como mapear falhas para orientar o usuário de forma clara.

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

Quando uma verificação de vivacidade falha, o SDK retorna um LivenessFailure objeto. Este objeto contém um causa parâmetro, que é um identificador de string que informa exatamente por que o processo não teve sucesso.

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

Os Modelos de Falha

O SDK usa uma hierarquia de classes seladas para categorizar falhas. Tanto as falhas no nível de captura quanto as falhas no nível de reconhecimento herdam da classe base LivenessFailure para que você possa sempre acessar a causa string.

LivenessFailure.kt

public sealed class LivenessFailure(public open val cause: String) {
    
    // Disparado quando o processo de captura de imagem falha. Nenhuma imagem (resposta) disponível
    public data class ImageCaptureFailure(override val cause: String) : LivenessFailure(cause)
    
    // Disparado quando falha ao reconhecer ou autenticar o rosto.
    public data class FaceRecognitionFailure(
        public val response: String, 
        override val cause: String
    ) : LivenessFailure(cause)
}

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.

Usando o causa Parâmetro

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

Prática recomendada: não exiba essas strings brutas diretamente aos seus usuários finais. Em vez disso, interceptar a causa string e mapeá-la para uma mensagem amigável e localizada na interface do seu app, orientando-os sobre como corrigir o problema.

Causas de Falha Disponíveis

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

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

Causa	Descrição
UNKNOWN	Falha genérica
TOO_MUCH_MOVEMENT	Movimento excessivo da cabeça
TOO_BRIGHT	Iluminação excessiva
TOO_DARK	Condições de pouca luz
MISALIGNED_FACE	Falha no alinhamento do rosto
FACE_TOO_FAR	Rosto muito distante
FACE_TOO_CLOSE	Rosto muito próximo
SUNGLASSES	Óculos que obstruem os olhos
OBSCURED_FACE	Obstrução parcial do rosto
EYES_CLOSED	Olhos fechados durante a captura
MULTIPLE_FACES	Vários rostos detectados
BACKGROUND_ISSUE	Plano de fundo inadequado
DEVICE_ISSUE	Dispositivo incompatível
EYEWEAR	Óculos detectados
FACE_NOT_FOUND	Falha na detecção do rosto
FRAMES_BLURRY	Quadros borrados detectados
MOTION_ISSUE	Erro de movimento do dispositivo
LIGHTING_ISSUES	Condições de iluminação ruins
REJECTED	Transação rejeitada
SYSTEM_ERROR	Erro interno do sistema
TIMEOUT	Tempo limite da sessão
USER_NOT_FOUND	Falha na busca do usuário
DEVICE_RESTART	Erro de estado do dispositivo
PROCESSING_FAULT	Erro de processamento

Exemplo de implementação

Aqui está um exemplo de como você pode lidar com um LivenessFailure e mapear o causa parâmetro para uma orientação útil ao usuário:

Kotlin

fun handleLivenessError(failure: LivenessFailure) {
    // 1. Você pode verificar o tipo específico da falha, se necessário
    when (failure) {
        is LivenessFailure.ImageCaptureFailure -> {
            println("A captura falhou antes de chegar ao servidor.")
        }
        is LivenessFailure.FaceRecognitionFailure -> {
            println("O servidor rejeitou a captura. Resposta: ${failure.response}")
        }
    }

    // 2. Mapear o 'cause' para uma mensagem amigável ao usuário
    val userMessage = when (failure.cause) {
        "TOO_DARK" -> "Está um pouco escuro demais. Por favor, vá para um local mais claro."
        "FACE_TOO_FAR" -> "Por favor, aproxime o celular do seu rosto."
        "EYES_CLOSED" -> "Por favor, mantenha os olhos abertos e olhe diretamente para a câmera."
        "MULTIPLE_FACES" -> "Certifique-se de que você seja a única pessoa no enquadramento."
        "TIMEOUT" -> "O tempo acabou. Tente novamente quando estiver pronto."
        "REJECTED", "FACE_AUTHENTICATION" -> "Não foi possível verificar seu rosto. Tente novamente."
        //...
        else -> "Ocorreu um erro inesperado (${failure.cause}). Tente novamente."
    }

    // 3. Exiba a mensagem na sua interface
    showErrorDialog(userMessage)
}

Java

public void handleLivenessError(LivenessFailure failure) {
    // 1. Você pode verificar o tipo específico da falha, se necessário
    if (failure instanceof LivenessFailure.ImageCaptureFailure) {
        System.out.println("A captura falhou antes de chegar ao servidor.");
    } else if (failure instanceof LivenessFailure.FaceRecognitionFailure) {
        // Faça o cast para acessar propriedades específicas, como response
        LivenessFailure.FaceRecognitionFailure recognitionFailure = 
            (LivenessFailure.FaceRecognitionFailure) failure;
        System.out.println("O servidor rejeitou a captura. Resposta: " + recognitionFailure.getResponse());
    }

    // 2. Mapear o 'cause' para uma mensagem amigável ao usuário
    String userMessage;
    String cause = failure.getCause();

    switch (cause) {
        case "TOO_DARK":
            userMessage = "Está um pouco escuro demais. Por favor, vá para um local mais claro.";
            break;
        case "FACE_TOO_FAR":
            userMessage = "Por favor, aproxime o celular do seu rosto.";
            break;
        case "EYES_CLOSED":
            userMessage = "Por favor, mantenha os olhos abertos e olhe diretamente para a câmera.";
            break;
        case "MULTIPLE_FACES":
            userMessage = "Certifique-se de que você seja a única pessoa no enquadramento.";
            break;
        case "TIMEOUT":
            userMessage = "O tempo acabou. Tente novamente quando estiver pronto.";
            break;
        case "REJECTED":
        case "FACE_AUTHENTICATION":
            userMessage = "Não foi possível verificar seu rosto. Tente novamente.";
            break;
        //...
        default:
            userMessage = "Ocorreu um erro inesperado (" + cause + "). Tente novamente.";
            break;
    }

    // 3. Exiba a mensagem na sua interface
    showErrorDialog(userMessage);
}