Tratando falhas

links: Face Liveness Lite

Quando uma verificação de liveness falha, o SDK retorna um evento LivenessLiteEvent.Failure evento. Esse evento contém um tipo parâmetro, CafFailureType enumeração que informa exatamente por que o processo não foi bem-sucedido.

Entender e lidar com o tipo 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.

O Modelo de Falha

O SDK entrega falhas por meio da LivenessLiteEvent interface selada. Tanto falhas no nível de captura quanto no nível de reconhecimento são relatadas como evento LivenessLiteEvent.Failure, garantindo que você sempre possa acessar a tipo e descrição.

LivenessLiteEvent.kt

public sealed interface LivenessLiteEvent {

    /**
     * Evento de falha de liveness com tipo de falha específico.
     *
     * @param response A resposta assinada do servidor
     * @param type O tipo específico de falha que ocorreu
     * @param description Descrição amigável da falha
     */
    public data class Failure(
        val response: String,
        val type: CafFailureType,
        val description: String
    ) : LivenessLiteEvent
}

Certifique-se de que a resposta JWT seja avaliada no backend. Esse processo deve incluir a validação da assinatura do token e a verificação dos isAlive e isMatch campos. Não realize essas validações no lado do cliente.

Usando o tipo Parâmetro

O tipo parâmetro retorna uma CafFailureType constante de enumeração (por exemplo, TOO_DARK ou FACE_TOO_FAR).

Prática recomendada: não exiba o nome bruto do enum ou o descrição diretamente para seus usuários finais. Em vez disso, intercepte o tipo e mapeie-o para uma mensagem localizada e amigável ao usuário na UI do seu app para orientá-los sobre como corrigir o problema.

Tipos de falha disponíveis

Se a captura da imagem for bem-sucedida, mas o mecanismo falhar ao autenticar ou processar o rosto, o SDK retorna um evento LivenessLiteEvent.Failure.

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

Tipo	Descrição
DESCONHECIDO	Falha genérica
MOVIMENTO_DEMAIS	Movimento excessivo da cabeça
MUITO_CLARO	Excesso de iluminação
TOO_DARK	Condições de pouca luz
ROSTO_DESALINHADO	Falha no alinhamento facial
FACE_TOO_FAR	Rosto muito distante
ROSTO_MUITO_PERTO	Rosto muito perto
ÓCULOS_ESCUROS	Óculos que ocultam os olhos
ROSTO_OBSCURECIDO	Obstrução parcial do rosto
OLHOS_FECHADOS	Olhos fechados durante a captura
VÁRIOS_ROSTOS	Vários rostos detectados
PROBLEMA_DE_FUNDO	Fundo inadequado
PROBLEMA_NO_DISPOSITIVO	Dispositivo incompatível
ÓCULOS	Óculos detectados
ROSTO_NÃO_ENCONTRADO	Falha na detecção do rosto
QUADROS_BORRADOS	Quadros borrados detectados
PROBLEMA_DE_MOVIMENTO	Erro de movimento do dispositivo
PROBLEMAS_DE_ILUMINAÇÃO	Condições de iluminação ruins
RECUSADO	Transação recusada
ERRO_DE_SISTEMA	Erro interno do sistema
TEMPO_ESGOTADO	Tempo limite da sessão
USUÁRIO_NÃO_ENCONTRADO	Falha na busca do usuário
REINICIALIZAÇÃO_DO_DISPOSITIVO	Erro de estado do dispositivo
FALHA_DE_PROCESSAMENTO	Erro de processamento
AUTENTICAÇÃO_FACIAL	Falha na autenticação facial

Exemplo de Implementação

Aqui está um exemplo de como você pode lidar com um evento LivenessLiteEvent.Failure e mapear o tipo parâmetro para orientações úteis ao usuário:

Kotlin

fun handleLivenessFailure(failure: LivenessLiteEvent.Failure) {
    // 1. A carga útil assinada do servidor está disponível, se necessário
    println("Resposta do servidor: ${failure.response}")

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

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

Java

public void handleLivenessFailure(LivenessLiteEvent.Failure failure) {
    // 1. A carga útil assinada do servidor está disponível, se necessário
    System.out.println("Resposta do servidor: " + failure.getResponse());

    // 2. Mapeie o 'type' para uma mensagem amigável ao usuário
    String userMessage;

    switch (failure.getType()) {
        case TOO_DARK:
            userMessage = "Está um pouco escuro demais. Por favor, vá para um ambiente mais claro.";
            break;
        case FACE_TOO_FAR:
            userMessage = "Aproxime o telefone do seu rosto.";
            break;
        case EYES_CLOSED:
            userMessage = "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 conseguimos verificar seu rosto. Tente novamente.";
            break;
        //...
        default:
            userMessage = "Ocorreu um erro inesperado (" + failure.getType() + "). Tente novamente.";
            break;
    }

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

Links:

Face Liveness LiteTratando falhasPersonalização da UIRegistro de alterações