Tratamento de Falhas

Referência para o tratamento de falhas do Face Liveness no Flutter. Aprenda sobre os tipos de CerttaLivenessFailure, valores de causa e como mapear falhas para orientações claras ao usuário.

Este guia aborda caf_sdk 2.4.0 e superiores (Certta DevX). Para a versão anterior CafSdk fluxo sequencial, consulte a documentação legada.

Quando uma verificação de vivacidade falha, o SDK emite CerttaLivenessEvent.failed com um CerttaLivenessFailure objeto. Este objeto contém um causa parâmetro (um código estável para lógica de mapeamento) e, para falhas de reconhecimento, um description campo com texto exibido ao usuário.

Entender e lidar com esses campos é fundamental para fornecer feedback claro e acionável, para que os usuários possam corrigir o problema e tentar novamente.

Os modelos de falha

Tanto as falhas de captura quanto as de reconhecimento compartilham o mesmo CerttaLivenessFailure tipo. Use type para distingui-las:

type	Significado
ImageCaptureFailure	A captura de imagem falhou. Nenhuma imagem assinada (response) está disponível.
FaceRecognitionFailure	A captura foi bem-sucedida, mas o reconhecimento ou a autenticação falharam. response contém o payload assinado. description fornece uma mensagem legível por humanos.

Para FaceRecognitionFailure, causa é normalizado para maiúsculas pelo plugin do Flutter. Use causa para lógica condicional e description (ou sua própria versão localizada) para mensagens exibidas aos usuários finais.

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.

Ao usar causa e description

A causa o parâmetro retorna uma string constante estável (por exemplo "TOO_DARK" ou "FACE_TOO_FAR"). Não exiba causa diretamente aos usuários finais.

Para FaceRecognitionFailure, prefira description como fallback quando você não mantiver um mapeamento personalizado. Caso contrário, mapeie causa para uma mensagem localizada e amigável ao usuário na sua interface.

Causas de falha disponíveis

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

Possíveis causa valores:

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 cobrem os olhos
OBSCURED_FACE	Obstrução parcial do rosto
EYES_CLOSED	Olhos fechados durante a captura
MULTIPLE_FACES	Vários rostos detectados
BACKGROUND_ISSUE	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

A documentação anterior do CafSdk também indicava quais causas se aplicam aos provedores GPA vs LA. Considere a tabela acima como o conjunto completo de identificadores que você pode receber; mapeie valores desconhecidos para uma mensagem genérica de nova tentativa.

Exemplo de implementação

String messageForLivenessFailure(CerttaLivenessFailure failure) {
  if (failure.type == 'ImageCaptureFailure') {
    debugPrint('A captura falhou antes de chegar ao servidor.');
  } else if (failure.type == 'FaceRecognitionFailure') {
    debugPrint('O servidor rejeitou a captura. Resposta: ${failure.response}');
    if (failure.description != null && failure.description!.isNotEmpty) {
      return failure.description!;
    }
  }

  switch (failure.cause) {
    case 'TOO_DARK':
      return "Está um pouco escuro. Por favor, vá para um ambiente mais iluminado.";
    case 'FACE_TOO_FAR':
      return 'Por favor, aproxime o celular do seu rosto.';
    case 'EYES_CLOSED':
      return 'Por favor, mantenha os olhos abertos e olhe diretamente para a câmera.';
    case 'MULTIPLE_FACES':
      return 'Certifique-se de ser a única pessoa no enquadramento.';
    case 'TIMEOUT':
      return 'O tempo acabou. Por favor, tente novamente quando estiver pronto.';
    case 'REJECTED':
    case 'FACE_AUTHENTICATION':
      return "Não foi possível verificar seu rosto. Tente novamente.";
    default:
      return 'Ocorreu um erro inesperado (${failure.cause}). Tente novamente.';
  }
}