Face Liveness

Instale e inicie o Face Liveness para Flutter. Aprenda sobre os pré-requisitos, opções de CerttaLivenessConfiguration, fluxos de eventos, resultados de sucesso e falha e tratamento de erros.

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.

Pré-requisitos

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

Guia de Instalação

Ative faceLiveness (e faceLivenessUI se quiser a interface integrada) em caf-modules-config.json. Você deve incluir pelo menos um provedor de liveness.

Iniciando o Liveness

Para iniciar o fluxo de Liveness, chame certta.liveness.open() e passe um CerttaLivenessConfiguration objeto. Assine a eventStream antes de chamar open() para não perder resultados.

Defina useFaceLivenessUi para true para usar a interface integrada da Certta. Quando false, o SDK executa o módulo Face Liveness sem interface.

import 'dart:async';
import 'package:flutter/services.dart';
import 'package:caf_sdk/certta_sdk.dart';

final certta = CerttaSdk();

late final StreamSubscription<CerttaLivenessEvent> _livenessSub;

void listenToLiveness() {
  _livenessSub = certta.liveness.eventStream.listen((event) {
    if (event.success != null) {
      // Trate o sucesso — event.success!.response é um JWT
    } else if (event.failed != null) {
      // Trate a falha de negócio — veja Tratando falhas
    } else if (event.error != null) {
      // Trate o erro técnico
    }
  });
}

Future<void> startLiveness() async {
  try {
    await certta.liveness.open(
      const CerttaLivenessConfiguration(
        maxRetryAttempts: 3,
        faceAuthEnabled: false,
        showLoading: true,
        useFaceLivenessUi: true,
      ),
    );
  } on PlatformException catch (e) {
    // Trate BRIDGE_EXCEPTION
  }
}

open() lança uma PlatformException com o código BRIDGE_EXCEPTION quando o mapeador nativo rejeita a configuração.

CerttaLivenessConfiguration parâmetros

Parâmetro	Padrão	Descrição
maxRetryAttempts	3	Número máximo de tentativas após uma captura malsucedida.
faceAuthEnabled	false	Quando ativado, o SDK realiza autenticação facial.
showLoading	true	Exibe indicadores de carregamento durante o processamento quando true.
useFaceLivenessUi	false	Se ativado, o SDK usa a interface integrada do Certta Face Liveness.
payFaceDebugMode	false	Ativa o modo de depuração para o provedor PayFace (Fortface). Somente iOS.

Entendendo eventos e resultados do Liveness

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.

CerttaLivenessEvent tem exatamente um campo preenchido:

success (CerttaSuccess)

A captura e o pipeline de liveness foram concluídos com sucesso. response é um JWT com os dados de resultado da execução de Liveness (por exemplo, imagens capturadas ou resultados de validação).

failed (CerttaLivenessFailure)

O Liveness foi executado, mas o resultado foi uma falha de negócio.

Campo	Descrição
tipo	Modelo de falha: ImageCaptureFailure ou FaceRecognitionFailure.
causa	Identificador para diagnósticos ou mensagens de UX (por exemplo TOO_DARK).
descrição	Descrição opcional legível por humanos do SDK nativo.
response	Payload assinado. Presente para FaceRecognitionFailure quando a captura foi bem-sucedida, mas o reconhecimento falhou.

1. ImageCaptureFailure: problemas durante a captura (ambiente, tempo limite, ausência de rosto, falha específica do provedor). Normalmente não há um response.
2. FaceRecognitionFailure: a captura foi bem-sucedida, mas o reconhecimento facial / backend não aceitou o resultado.

Para entender e tratar o causa da falha, veja Tratando falhas.

erro (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 de hardware.

Campo	Descrição
tipo	Identificador do erro mapeado a partir do SDK nativo.
causa	Contexto adicional da falha, quando presente.

Evento	Causa típica
erro de inicialização	configurar não chamado, token ou ID de usuário vazio, ou inválido maxRetryAttempts.
erro de permissão	Permissão da câmera (ou relacionada) negada.
erro de rede	Problemas de conectividade ou do lado do servidor se manifestam como erros da classe de rede.
erro de segurança	As verificações de segurança falharam.
erro desconhecido	Outras falhas não mapeadas para um caso específico.
cancelado	Ocorre quando o usuário abandona o fluxo antes da conclusão, como ao pressionar o botão voltar ou enviar o aplicativo para segundo plano.