Introdução ao SDK

Sobre o CafSDK

Esta documentação técnica aborda a implementação do CafSDK para Flutter, detalhando a configuração, inicialização, execução dos fluxos de captura e personalizações avançadas.

O CafSDK é um SDK unificado que integra vários módulos para verificação de identidade: Face Liveness (FL) e Document Detector (DD), executados sequencialmente com uma interface de configuração unificada.

O que é Face Liveness

Face Liveness é o módulo que valida a autenticidade de um rosto capturado por um aplicativo de fotos, garantindo que a imagem corresponda a uma pessoa real e não a uma tentativa de spoofing.

Características técnicas:

• Configuração da URL para autenticação (authBaseUrl) e verificação de liveness (livenessBaseUrl)
• Suporte à configuração de proxy reverso com pinagem de certificado
• Flags para habilitar captura de tela e modo de depuração
• Tentativas de repetição configuráveis e execução da autenticação facial
• Suporte a múltiplos provedores de autenticação

O que é Document Detector

Document Detector é o módulo que permite a captura e o processamento de documentos (por exemplo, RG, cartão do INSS, passaporte etc.).

Características técnicas:

• Configuração de um fluxo passo a passo definido por CafDocumentDetectorFlow para captura de documentos
• Suporte a vários tipos de documentos (RG, CNH, passaporte etc.)
• Parâmetros operacionais, como timeout, flags de captura manual e outras configurações
• Possibilidade de usar a câmera para validações de enquadramento ou upload de arquivo de documento
• Opções avançadas de personalização para UI, mensagens e comportamento

---

Exemplo

Confira o aplicativo de exemplo para um exemplo completo de implementação.

---

Instalação

Requisitos

Para usar os módulos CafSDK no Flutter, certifique-se de que seu projeto atenda aos requisitos mínimos:

Flutter

Requisito	Versão
Versão do Flutter	3.3.0+
Dart	3.9.0+

Android

Requisito	Versão
API do SDK Android - versão mínima (minSdk)	26
API do SDK Android - versão de compilação (compileSdk)	36+
Kotlin	1.8+
Gradle	8.0+
Android Gradle Plugin (AGP)	8.0+

iOS

Requisito	Versão
Target de implantação do iOS	13.0+
Xcode	14.0+
Swift	5.0+

Passo 1: Instale o SDK

Instale o pacote principal do SDK:

flutter pub add caf_sdk

Passo 2: Configure a seleção de módulos

Crie um caf-modules-config.json arquivo na raiz do seu projeto para especificar quais módulos incluir:

Observação: Se você omitir este arquivo, todos os módulos serão ativados por padrão e iproov-lite será usado como provedor padrão de Face Liveness.

{
  "documentDetector": true,
  "faceLiveness": true,
  "documentDetectorUI": true,
  "faceLivenessUI": true,
  "livenessProviders": "iproov-lite",
  "fingerprint": true
}

Defina os true módulos que você deseja usar em sua aplicação.

Para um único provedor, livenessProviders pode ser uma string. Os valores permitidos são iproov-lite, iproov-full, payface, e facetec. Para usar vários provedores, use um array (veja o exemplo abaixo).

{
  "documentDetector": true,
  "faceLiveness": true,
  "documentDetectorUI": true,
  "faceLivenessUI": true,
  "livenessProviders": [
    "iproov-lite",
    "payface",
    "facetec"
  ],
  "fingerprint": true
}

iProov e Protobuf

• iproov-lite: use quando seu app tiver como alvo Protobuf JavaLite—a escolha usual para uma pegada binária menor no Android.
• iproov-full: use quando você precisar de Protobuf Java (completo) junto com iProov.

Você pode declarar mais de um provedor definindo livenessProviders como um array quando sua integração exigir isso.

Se você incluir o provedor PayFace , você também deve usar iProov Lite (iproov-lite). O PayFace é compilado com base em Protobuf JavaLite; misturá-lo com iproov-full causa conflitos de dependência do Protobuf no momento da compilação.

Defina os true módulos que você deseja usar em sua aplicação.

Fingerprint

O módulo Fingerprint é opcional e é configurado em caf-modules-config.json por meio da fingerprint propriedade (boolean). O padrão é false, então você não precisa adicionar a propriedade, a menos que queira usá-la. Para habilitar o módulo, defina explicitamente "fingerprint": true.

Requer um módulo Face Liveness. O Fingerprint é coletado como parte do fluxo de liveness, então só é incluído quando faceLiveness ou faceLivenessUI também está habilitado. Definir "fingerprint": true sem um módulo de liveness habilitado não tem efeito.

Importante: Entre em contato com o Suporte da CAF para solicitar a ativação. Se isso não estiver habilitado do nosso lado, o SDK não acionará a biblioteca de fingerprint e nenhum dado será enviado, mesmo que a propriedade esteja definida como true localmente.

Passo 3: Configuração do Android

Adicionar repositórios Maven

Configure o projeto build.gradle.kts do projeto (normalmente localizado na raiz):

repositories {
    // Repositório CAF
    maven { url = uri("https://repo.combateafraude.com/android/release") }
    
    // Repositório iProov (necessário para Face Liveness)
    maven { url = uri("https://raw.githubusercontent.com/iProov/android/master/maven/") }
    
    // Repositório FingerPrintJS
    maven { setUrl("https://maven.fpregistry.io/releases") }
    
    // JitPack
    maven { setUrl("https://jitpack.io") }

    // Repositório Fortface - necessário para usar o provedor PayFace
    maven {
        url = uri("https://cdn-fortface-sdk.fortface.com.br")
        credentials(HttpHeaderCredentials::class) {
            name = "X-Sdk"
            value = "CAF"
        }
        authentication {
            create<HttpHeaderAuthentication>("header")
        }
    }
}

Passo 4: Configuração do iOS

Acesse o ios/ diretório do seu projeto Flutter e execute:

pod install

• Este passo é obrigatório para que o iOS vincule corretamente os módulos nativos e suas dependências necessárias.
• Sempre execute novamente pod install sempre que dependências nativas forem adicionadas ou atualizadas.

---

Permissões

Android

Para que os módulos operem corretamente, você deve declarar as seguintes permissões no seu AndroidManifest.xml:

Para Face Liveness

Permissão	Descrição	Necessidade
android.permission.CAMERA	Permite acesso à câmera para capturar imagens e realizar a verificação facial (liveness).	Obrigatória
android.permission.INTERNET	Permite a comunicação com serviços de autenticação e verificação (HTTPS/WSS).	Obrigatória

Para Document Detector

Permissão	Descrição	Necessidade
android.permission.CAMERA	Permite acesso à câmera para capturar imagens de documentos.	Apenas para captura
android.permission.INTERNET	Permite que imagens capturadas sejam enviadas aos servidores para processamento e validação.	Obrigatória
android.permission.READ_EXTERNAL_STORAGE	Permite acesso a arquivos e imagens armazenados para processamento, se necessário.	Apenas para upload

iOS

Para que os módulos do SDK funcionem corretamente, você deve declarar as seguintes permissões no seu Info.plist:

Para Face Liveness:

Permissão	Descrição	Necessidade
NSCameraUsageDescription	Permite acesso à câmera para capturar imagens e realizar a verificação facial (liveness).	Obrigatória
Acesso à rede	Permite a comunicação com serviços de autenticação e verificação (HTTPS/WSS).	Obrigatória

Para Document Detector:

Permissão	Descrição	Necessidade
NSCameraUsageDescription	Permite acesso à câmera para capturar imagens de documentos.	Apenas para captura
Acesso à rede	Permite que imagens capturadas sejam enviadas aos servidores para processamento e validação.	Obrigatória
NSPhotoLibraryUsageDescription	Permite acesso a arquivos e imagens armazenados para processamento, se necessário.	Apenas para upload

---

Implementação básica

Exemplo simples

Aqui está um exemplo básico de implementação:

import 'dart:async';
import 'package:caf_sdk/types/index.dart';
import 'package:flutter/material.dart';
import 'package:caf_sdk/caf_sdk.dart';

void main() => runApp(const App());

class App extends StatelessWidget {
  const App({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Exemplo do CAF SDK',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue),
        useMaterial3: true,
      ),
      home: const SimpleExamplePage(),
    );
  }
}

class SimpleExamplePage extends StatefulWidget {
  const SimpleExamplePage({super.key});

  @override
  State<SimpleExamplePage> createState() => _SimpleExamplePageState();
}

class _SimpleExamplePageState extends State<SimpleExamplePage> {
  final _cafSdk = CafSdk();
  StreamSubscription<CafResponse>? _eventSubscription;

  @override
  void initState() {
    super.initState();
    _initializeEventStream();
  }

  @override
  void dispose() {
    _eventSubscription?.cancel();
    super.dispose();
  }

  void _initializeEventStream() {
    _eventSubscription = _cafSdk.eventStream.listen((event) {
      if (!mounted) return;

      if (event.success != null) {
        print('Sucesso: ${event.success!.moduleName} -> ${event.success!.signedResponse}');
      } else if (event.error != null) {
        print('Erro: ${event.error!.type} - ${event.error!.description}');
      } else if (event.failure != null) {
        print('Falha: ${event.failure!.type} - ${event.failure!.description}');
      }
    });
  }

  Future<void> _initialize() async {
    try {
      // Configuração do SDK
      final config = CafSdkConfiguration(
        mobileToken: 'token',
        personId: 'personId',
        environment: CafEnvironment.dev,
        configuration: CafSdkBuilderConfiguration(
          presentationOrder: [
            CafModuleType.faceLiveness,
            CafModuleType.documentDetector,
          ],
          enableSecurityModule: true,
          waitForAllServices: true,
        ),
      );

      // Configuração do Face Liveness
      final faceLivenessConfig = CafFaceLivenessConfiguration(
        loading: true,
        debugModeEnabled: true,
        payFaceDebugMode: false,
      );

      // Configuração do Document Detector
      final documentDetectorConfig = CafDocumentDetectorConfiguration(
        flow: [
          CafDocumentDetectorFlow(document: CafDocument.rgFront),
          CafDocumentDetectorFlow(document: CafDocument.rgBack),
        ],
        uploadSettings: CafDocumentDetectorUploadSettings(enable: false),
        manualCaptureEnabled: false,
        manualCaptureTime: 45,
        showPopup: true,
        previewShow: false,
        securitySettings: CafDocumentDetectorSecuritySettings(
          useAdb: true,
          useDebug: true,
          useDevelopmentMode: true,
        ),
      );

      await _cafSdk.initializeCafSdk(
        cafSdkConfiguration: config,
        faceLivenessConfiguration: faceLivenessConfig,
        documentDetectorConfiguration: documentDetectorConfig,
      );
    } catch (e) {
      print('Erro: $e');
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Exemplo simples do CAF SDK'),
        backgroundColor: Theme.of(context).colorScheme.inversePrimary,
      ),
      body: SafeArea(
        child: Padding(
          padding: const EdgeInsets.all(16.0),
          child: Column(
            crossAxisAlignment: CrossAxisAlignment.center,
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              Center(
                child: ElevatedButton(
                  onPressed: _initialize,
                  child: Text('Iniciar')
                ),
              ),
            ],
          ),
        ),
      ),
    );
  }
}

---

Configuração

Idioma

Android

O idioma é definido automaticamente de acordo com o idioma configurado no dispositivo, sem nenhuma configuração adicional.

iOS

De acordo com a documentação da Apple, configurar Localizações e CFBundleLocalizations deve ser feito no Xcode:

Adicionando suporte a idiomas e regiões

CFBundleLocalizations

Após essas configurações, o SDK reconhecerá o idioma do dispositivo.

Configuração global

A CafSdk classe serve como o contêiner central para todas as configurações. Essa configuração define a ordem de execução dos módulos e a identidade visual.

Parâmetros essenciais:

• mobileToken: Token que autentica a requisição e garante que apenas clientes autorizados iniciem o fluxo
• personId: Identificador único do usuário para o qual o fluxo será executado
• environment: Define o ambiente de execução (PROD, BETA, DEV)
• presentationOrder: Define a sequência em que os módulos serão executados
• enableSecurityModule: Habilita ou desabilita o módulo de segurança. Opcional, o padrão é true

Exemplo de código para criar a configuração global:

final _cafSdk = CafSdk();

// Configuração do SDK
final config = CafSdkConfiguration(
  mobileToken: "mobile-token",
  personId: "person-id",
  environment: CafEnvironment.prod,
  configuration: CafSdkBuilderConfiguration(
    presentationOrder: [
      CafModuleType.faceLiveness,    // ou CafModuleType.faceLivenessUi
      CafModuleType.documentDetector // ou CafModuleType.documentDetectorUi
    ],
    enableSecurityModule: true,       // Opcional, o padrão é true
    waitForAllServices: true,         // Opcional, o padrão é true
    enableTransitionScreens: true,    // Opcional, o padrão é true
    colorConfiguration: CafColorConfiguration(
      primaryColor: "#0000FF",
      secondaryColor: "#00FF00",
      backgroundColor: "#FFFFFF",
      contentColor: "#000000",
      mediumColor: "#CCCCCC",
      dialogBackgroundColor: "#FFFFFF",
      dialogBorderColor: "#E5E5E7",
    ),
  ),
);

// Inicialize o SDK
await _cafSdk.initializeCafSdk(
  cafSdkConfiguration: config,
  documentDetectorConfiguration: documentDetectorConfig,
  documentDetectorUIConfiguration: documentDetectorUIConfig,
  faceLivenessConfiguration: faceLivenessConfig,
  faceLivenessUIConfiguration: faceLivenessUIConfig,
);

Configuração Específica do Módulo

Configuração do Face Liveness

Você pode configurar o módulo Face Liveness criando um CafFaceLivenessConfiguration. Ao usar o provedor opcional PayFace (Fortface), use payFaceDebugMode para ativar o modo de depuração para esse provedor.

final faceLivenessConfig = CafFaceLivenessConfiguration(
  loading: true,                                                  // Exibe a tela de carregamento durante o processamento
  authBaseUrl: 'https://base-url.com',                            // Opcional, endpoint para autenticação
  livenessBaseUrl: 'wss://base-url.com',                          // Opcional, endpoint para verificação de liveness
  certificates: ['4d69f16113bed7d62ca56feb68d32a0fcb7293d3960='], // Opcional, apenas ao usar proxy reverso
  screenCaptureEnabled: true,                                     // Permite captura de tela, se necessário
  debugModeEnabled: true,                                         // Ativa logs de depuração
  executeFaceAuth: false,                                         // Ativa autenticação facial
  maxRetryAttempts: 2,                                            // Número máximo de tentativas de repetição
  payFaceDebugMode: false,                                        // Opcional, ativa o modo de depuração para o provedor PayFace (Fortface)
);

Configuração do Detector de Documentos

Você pode configurar o módulo Detector de Documentos criando um CafDocumentDetectorConfiguration:

final documentDetectorConfig = CafDocumentDetectorConfiguration(
  flow: [
    CafDocumentDetectorFlow(document: CafDocument.rgFront),
    CafDocumentDetectorFlow(document: CafDocument.rgBack),
  ],
  securitySettings: CafDocumentDetectorSecuritySettings(
    useAdb: true,
    useDebug: true,
    useDevelopmentMode: true,
  ),
  manualCaptureEnabled: true,
  manualCaptureTime: 30,
  requestTimeout: 60,
  showPopup: true,
  maxRetryAttempts: 2,
  uploadSettings: CafDocumentDetectorUploadSettings(
    enable: true,
    compress: true,
    fileFormats: [CafFileFormat.png, CafFileFormat.jpg],
    maxFileSize: 5, // 5MB
  ),
);

---

Tratamento de Eventos

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.

A eventStream da CafSdk classe fornece um tipado Stream<CafResponse> gerado durante a execução do fluxo de captura. Cada CafResponse tem exatamente um campo preenchido, o que indica o tipo de evento:

Campo	Tipo	Descrição
loading	bool	Indica o início do processamento do módulo
loaded	bool	Indica que o módulo foi processado
success	CafSuccessResponse?	Após conclusão bem-sucedida; contém moduleName e signedResponse
error	CafErrorResponse?	Ocorreu um problema durante a execução; contém type e description
failure	CafFailureResponse?	Indica uma falha do Face Liveness; contém type, description, e response
log	CafLog?	Mensagens de log com diferentes níveis; contém level (DEBUG, USAGE, INFO) e message
cancelled	bool	Indica que o usuário ou o sistema interrompeu o fluxo

Nota de migração (v2.0.0): eventStream agora emite objetos CafResponse tipados em vez de Map payloads brutos. Substitua qualquer acesso event['eventName'] / event['response'] pelos campos tipados mostrados acima.

Exemplo de tratamento de eventos:

final _cafSdk = CafSdk();
StreamSubscription<CafResponse>? _eventSubscription;

void _initializeEventStream() {
  _eventSubscription = _cafSdk.eventStream.listen((event) {
    if (!mounted) return;

    if (event.loading) {
      print('Carregando...');
    } else if (event.loaded) {
      print('Sessão carregada');
    } else if (event.success != null) {
      print('Sucesso: ${event.success!.moduleName} -> ${event.success!.signedResponse}');
    } else if (event.error != null) {
      print('Erro: ${event.error!.type} - ${event.error!.description}');
    } else if (event.failure != null) {
      print('Falha: ${event.failure!.type} - ${event.failure!.description}');
    } else if (event.log != null) {
      print('Log: ${event.log!.level} - ${event.log!.message}');
    } else if (event.cancelled) {
      print('Cancelado pelo usuário');
    }
  });
}

@override
void dispose() {
  _eventSubscription?.cancel();
  super.dispose();
}

Tipos de Erro (CafErrorType)

Caso do Enum	Condição de Disparo
CAMERA_PERMISSION	Acesso à câmera negado
UNSUPPORTED_DEVICE	Especificações do dispositivo não suportadas
NETWORK_EXCEPTION	Problemas de conectividade de rede
SERVER_EXCEPTION	Falha no processamento do backend
TOKEN_EXCEPTION	Token inválido/expirado
CAPTURE_ALREADY_ACTIVE_EXCEPTION	Sessão de captura simultânea
UNEXPECTED_ERROR_EXCEPTION	Erro crítico irrecuperável
USER_TIMEOUT_EXCEPTION	Tempo limite de captura excedido
IMAGE_NOT_FOUND_EXCEPTION	Dados da imagem ausentes
TOO_MANY_REQUESTS_EXCEPTION	Limite de requisições da API excedido
UNKNOWN_EXCEPTION	Erro não classificado
LIBRARY_EXCEPTION	Erro de baixo nível do framework
PERMISSION_EXCEPTION	Permissões do sistema ausentes
INVALID_EXCEPTION	Resposta inválida recebida
SEQUENCE_INVALID	Sequência de operação inválida
LIVENESS_EXCEPTION	Erro específico de Face Liveness
FINGERPRINT_EXCEPTION	Erro relacionado à impressão digital
STORAGE_EXCEPTION	Erro de acesso ao armazenamento
PROXY_EXCEPTION	Erro de configuração do proxy
SECURITY_EXCEPTION	Erro de validação de segurança
INVALID_RESPONSE_EXCEPTION	Payload de resposta inválido recebido de um módulo
CAMERA_EXCEPTION	Falha na inicialização ou em tempo de execução da câmera
FACE_AUTHENTICATION	Erro durante a autenticação facial (executeFaceAuth)
BRIDGE_EXCEPTION	Erro de comunicação na ponte nativa ↔ Flutter

Tipos de Falha (CafFailureType)

Caso do Enum	Condição de Disparo	GPA	LA
DESCONHECIDO	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 no estado do dispositivo	❌	✅
PROCESSING_FAULT	Erro de processamento	❌	✅

---

Tipos de Documento

Documentos Suportados (CafDocument)

Nome	Descrição
RG_FRONT	Frente do documento RG, onde a foto está localizada
RG_BACK	Verso do documento RG
RG_FULL	Documento RG aberto, exibindo a frente e o verso juntos
CNH_FRONT	Frente do documento CNH, onde a foto está localizada
CNH_BACK	Verso do documento CNH
CNH_FULL	Documento CNH aberto, exibindo a frente e o verso juntos
CRLV	Documento CRLV
RNE_FRONT	Frente do documento RNE ou RNM
RNE_BACK	Verso do documento RNE ou RNM
CTPS_FRONT	Frente do documento CTPS, onde a foto está localizada
CTPS_BACK	Verso do documento CTPS
PASSPORT	Documento de passaporte, exibindo a foto e os dados pessoais
ANY	Permite o envio de qualquer tipo de documento, incluindo todos os listados acima ou qualquer outro documento não classificado

Formatos de Arquivo Suportados (CafFileFormat)

Tipo	Valor
PNG	image/png
JPG	image/jpg
JPEG	image/jpeg
PDF	application/pdf
HEIF	image/heif
HEIC	image/heic

---

Configuração Avançada

Configuração da UI do Face Liveness

Ao usar o módulo de UI, você pode personalizar as telas de instrução:

final faceLivenessUIConfig = CafFaceLivenessUIConfiguration(
  loading: true,
  authBaseUrl: "https://my.proxy.io/v1/faces/", 
  livenessBaseUrl: "wss://my.proxy.io/ws/",    
  certificates: [
    "4d69f16113bed7d62ca56feb68d32a0fcb7293d3960=",
    "50f71c5dda30741ee4be1ac378e12539b0d1d511f99=",
    "9f85e26c1ae41f7ac97adc4099be7f2a40759510ab9=",
  ],
  screenCaptureEnabled: true,
  debugModeEnabled: true,
  executeFaceAuth: false, 
  maxRetryAttempts: 2,
  payFaceDebugMode: false,
  instructionScreen: CafFaceLivenessUIInstructionScreenConfiguration(
    image: "scan_icon", // URL da imagem ou nome do recurso local
    title: "Título personalizado",
    description: "Siga as etapas abaixo:",
    steps: ["Mantenha o telefone estável", "Garanta uma boa iluminação"],
    buttonText: "Iniciar leitura",
  ),
);

Configuração da UI do Detector de Documentos

final documentDetectorUIConfig = CafDocumentDetectorUIConfiguration(
  flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)], 
  manualCaptureEnabled: true,
  manualCaptureTime: 45,
  requestTimeout: 60,
  showPopup: true,
  securitySettings: CafDocumentDetectorSecuritySettings(
    useDebug: true,
    useDevelopmentMode: true,
    useAdb: true,
  ),
  maxRetryAttempts: 2,
  instructionScreen: CafDocumentDetectorUIInstructionScreenConfiguration(
    enable: true,
    captureTitle: "Capture seu documento",
    captureSteps: [
      "Mantenha o telefone estável",
      "Garanta uma boa iluminação",
      "Evite reflexos"
    ],
    buttonText: "Iniciar",
  ),
  documentSelectionScreen: CafDocumentDetectorUIDocumentSelectionScreenConfiguration(
    title: "Selecione o tipo de documento",
    description: "Escolha qual documento você deseja enviar",
  ),
);

Configuração de Proxy

Para as configurações de proxy do Detector de Documentos:

final documentDetectorConfig = CafDocumentDetectorConfiguration(
  flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)],
  proxySettings: CafDocumentDetectorProxySettings(
    hostname: "proxy.example.com",
    port: 8080,
    authentication: CafDocumentDetectorProxySettingsAuthentication(
      user: "username",
      password: "password"
    ),
  ),
);

Personalização de Mensagens

Personalize as mensagens exibidas durante o fluxo de captura:

final documentDetectorConfig = CafDocumentDetectorConfiguration(
  flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)],
  messageCustomization: CafDocumentDetectorMessageCustomization(
    waitMessage: "Preparando a câmera...",
    fitTheDocumentMessage: "Posicione o documento dentro da moldura",
    holdItMessage: "Mantenha firme...",
    verifyingQualityMessage: "Verificando a qualidade do documento...",
    lowQualityDocumentMessage: "A qualidade do documento está muito baixa. Tente novamente.",
    uploadingImageMessage: "Enviando documento...",
    positiveButtonMessage: "Continuar",
  ),
);

---

Exemplo de Implementação Completa

Aqui está um exemplo completo mostrando tanto a UI do Face Liveness quanto a UI do Detector de Documentos:

import 'dart:async';
import 'package:flutter/material.dart';
import 'package:caf_sdk/caf_sdk.dart';
import 'package:caf_sdk/types/index.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Exemplo do CAF SDK',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue),
        useMaterial3: true,
      ),
      home: const CafSdkExamplePage(),
    );
  }
}

class CafSdkExamplePage extends StatefulWidget {
  const CafSdkExamplePage({super.key});

  @override
  State<CafSdkExamplePage> createState() => _CafSdkExamplePageState();
}

class _CafSdkExamplePageState extends State<CafSdkExamplePage> {
  final _cafSdk = CafSdk();
  StreamSubscription<CafResponse>? _eventSubscription;

  final String _mobileToken = "token";
  final String _personId = "personId";
  final CafEnvironment _environment = CafEnvironment.dev;

  @override
  void initState() {
    super.initState();
    _initializeEventStream();
  }

  @override
  void dispose() {
    _eventSubscription?.cancel();
    super.dispose();
  }

  void _initializeEventStream() {
    _eventSubscription = _cafSdk.eventStream.listen((event) {
      if (!mounted) return;

      if (event.loading) {
        print('[CAF SDK EVENT]: loading');
      } else if (event.loaded) {
        print('[CAF SDK EVENT]: loaded');
      } else if (event.success != null) {
        print('[CAF SDK EVENT]: success');
        print('[CAF SDK EVENT]: ${event.success!.moduleName} -> ${event.success!.signedResponse}');
      } else if (event.error != null) {
        print('[CAF SDK EVENT]: error');
        print('[CAF SDK EVENT]: ${event.error!.type} - ${event.error!.description}');
      } else if (event.failure != null) {
        print('[CAF SDK EVENT]: failure');
        print('[CAF SDK EVENT]: ${event.failure!.type} - ${event.failure!.description}');
      } else if (event.log != null) {
        print('[CAF SDK EVENT]: log');
        print('[CAF SDK EVENT]: ${event.log!.level} - ${event.log!.message}');
      } else if (event.cancelled) {
        print('[CAF SDK EVENT]: cancelled');
      }
    });
  }

  Future<void> _initializeCafSdk() async {
    try {
      // Configuração do SDK
      final config = CafSdkConfiguration(
        mobileToken: _mobileToken,
        personId: _personId,
        environment: _environment,
        configuration: CafSdkBuilderConfiguration(
          presentationOrder: [
            CafModuleType.faceLivenessUi,
            CafModuleType.documentDetectorUi,
          ],
          enableSecurityModule: true,
          waitForAllServices: true,
        ),
      );

      // Configuração da interface do Face Liveness
      CafFaceLivenessUIConfiguration?
      faceLivenessUIConfig = CafFaceLivenessUIConfiguration(
        loading: true,
        debugModeEnabled: true,
        payFaceDebugMode: false,
        instructionScreen:
            CafFaceLivenessUIInstructionScreenConfiguration(
              title: "Vivacidade facial",
              description:
                  "Posicione seu rosto no centro e siga as instruções",
              steps: [
                "Centralize seu rosto",
                "Siga as instruções",
                "Fique imóvel",
              ],
              buttonText: "Iniciar",
            ),
      );

      // Configuração da interface do Document Detector
      CafDocumentDetectorUIConfiguration?
      documentDetectorUIConfig = CafDocumentDetectorUIConfiguration(
        flow: [
          CafDocumentDetectorFlow(document: CafDocument.rgFront),
          CafDocumentDetectorFlow(document: CafDocument.rgBack),
          CafDocumentDetectorFlow(document: CafDocument.rgFull),
          CafDocumentDetectorFlow(document: CafDocument.cnhFront),
          CafDocumentDetectorFlow(document: CafDocument.cnhBack),
          CafDocumentDetectorFlow(document: CafDocument.cnhFull),
          CafDocumentDetectorFlow(document: CafDocument.crlv),
          CafDocumentDetectorFlow(document: CafDocument.rneFront),
          CafDocumentDetectorFlow(document: CafDocument.rneBack),
          CafDocumentDetectorFlow(document: CafDocument.ctpsFront),
          CafDocumentDetectorFlow(document: CafDocument.ctpsBack),
          CafDocumentDetectorFlow(document: CafDocument.passport),
          CafDocumentDetectorFlow(document: CafDocument.any),
        ],
        uploadSettings: CafDocumentDetectorUploadSettings(enable: true),
        manualCaptureEnabled: false,
        manualCaptureTime: 45,
        showPopup: true,
        previewShow: false,
        securitySettings: CafDocumentDetectorSecuritySettings(
          useAdb: true,
          useDebug: true,
          useDevelopmentMode: true,
        ),
        instructionScreen:
            CafDocumentDetectorUIInstructionScreenConfiguration(
              enable: true,
              captureTitle: "Título da captura",
              captureSteps: ["Etapa de captura 1", "Etapa de captura 2"],
              uploadTitle: "Título do envio",
              uploadSteps: ["Etapa de envio 1", "Etapa de envio 2"],
              buttonText: "Texto do botão",
            ),
        documentSelectionScreen:
            CafDocumentDetectorUIDocumentSelectionScreenConfiguration(
              title: "Título da seleção de documento",
              description: "Descrição da seleção de documento",
            ),
      );

      await _cafSdk.initializeCafSdk(
        cafSdkConfiguration: config,
        documentDetectorUIConfiguration: documentDetectorUIConfig,
        faceLivenessUIConfiguration: faceLivenessUIConfig,
      );

      if (mounted) {
        ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(
            content: Text('CAF SDK inicializado com sucesso!'),
            backgroundColor: Colors.green,
          ),
        );
      }
    } catch (e) {
      if (mounted) {
        ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(content: Text('Erro: $e'), backgroundColor: Colors.red),
        );
      }
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Exemplo do CAF SDK'),
        backgroundColor: Theme.of(context).colorScheme.inversePrimary,
      ),
      body: SingleChildScrollView(
        padding: const EdgeInsets.all(16.0),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.stretch,
          children: [
            _ConfigurationCard(
              mobileToken: _mobileToken,
              personId: _personId,
              environment: _environment,
            ),
            const SizedBox(height: 16),

            _ActionButtons(onInitialize: _initializeCafSdk),
            const SizedBox(height: 16),
          ],
        ),
      ),
    );
  }
}

class _ConfigurationCard extends StatelessWidget {
  const _ConfigurationCard({
    required this.mobileToken,
    required this.personId,
    required this.environment,
  });

  final String mobileToken;
  final String personId;
  final CafEnvironment environment;

  @override
  Widget build(BuildContext context) {
    return Card(
      child: Padding(
        padding: const EdgeInsets.all(16.0),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            Text(
              'Configuração do CAF SDK',
              style: Theme.of(context).textTheme.titleLarge,
            ),
            const SizedBox(height: 16),
            Text(
              'Token móvel: ${mobileToken.length > 20 ? '${mobileToken.substring(0, 20)}...' : mobileToken}',
              style: Theme.of(context).textTheme.bodyMedium,
            ),
            const SizedBox(height: 8),
            Text(
              'ID da pessoa: $personId',
              style: Theme.of(context).textTheme.bodyMedium,
            ),
            const SizedBox(height: 8),
            Text(
              'Ambiente: $environment',
              style: Theme.of(context).textTheme.bodyMedium,
            ),
          ],
        ),
      ),
    );
  }
}

class _ActionButtons extends StatelessWidget {
  const _ActionButtons({
    required this.onInitialize,
  });

  final VoidCallback onInitialize;

  @override
  Widget build(BuildContext context) {
    return Row(
      children: [
        Expanded(
          child: ElevatedButton(
            onPressed: onInitialize,
            style: ElevatedButton.styleFrom(
              padding: const EdgeInsets.symmetric(vertical: 16),
              shape: RoundedRectangleBorder(
                borderRadius: BorderRadius.circular(8),
              ),
            ),
            child: Text('Inicializar SDK'),
          ),
        ),
        const SizedBox(width: 8),
      ],
    );
  }
}

---

Regras do ProGuard/R8

Adicione estas regras do ProGuard/R8 ao seu proguard-rules.pro arquivo para Android:

# Regras do ProGuard/R8 do Flutter para o Caf SDK
# Estas regras garantem que o plugin do CAF SDK funcione corretamente nas compilações de release

# O pré-handler de exceções do Android é carregado de forma reflexiva (via ServiceLoader).
-keep class kotlinx.coroutines.experimental.android.AndroidExceptionPreHandler { *; }

### GSON ##################################################################
# O Gson usa informações de tipo genérico armazenadas em um arquivo de classe ao trabalhar com campos.
# O ProGuard remove essas informações por padrão, então configure-o para mantê-las todas.
-keepattributes Signature
# Para usar a anotação @Expose do GSON
-keepattributes *Annotation*
### FIM GSON ##################################################################

### Retrofit ##################################################################
# Preservar assinaturas genéricas, classes internas e métodos envolventes para a reflexão do Retrofit.
-keepattributes Signature, InnerClasses, EnclosingMethod
# Reter anotações visíveis em tempo de execução em métodos e parâmetros.
-keepattributes RuntimeVisibleAnnotations, RuntimeVisibleParameterAnnotations
# Manter os valores padrão das anotações.
-keepattributes AnnotationDefault
# Reter os parâmetros dos métodos de serviço para interfaces com anotações do Retrofit.
-keepclassmembers,allowshrinking,allowobfuscation interface * {
    @retrofit2.http.* <methods>;
}
# Suprimir avisos para ferramentas de build e certas anotações JSR 305.
-dontwarn org.codehaus.mojo.animal_sniffer.IgnoreJRERequirement
-dontwarn javax.annotation.**
-dontwarn kotlin.Unit
-dontwarn retrofit2.KotlinExtensions
-dontwarn retrofit2.KotlinExtensions$*
# Manter explicitamente as interfaces do Retrofit para evitar a nulificação pelo R8.
-if interface * { @retrofit2.http.* <methods>; }
-keep,allowobfuscation interface <1>
-if interface * { @retrofit2.http.* <methods>; }
-keep,allowobfuscation interface * extends <1>
# Preservar as continuations usadas pelas funções suspend do Kotlin.
-keep,allowobfuscation,allowshrinking class kotlin.coroutines.Continuation
# Para o modo completo do R8: manter os tipos de retorno genéricos dos métodos do Retrofit.
-if interface * { @retrofit2.http.* public *** *(...); }
-keep,allowoptimization,allowshrinking,allowobfuscation class <3>
# Preservar a classe Response do Retrofit.
-keep,allowobfuscation,allowshrinking class retrofit2.Response
### FIM Retrofit ##############################################################

### OkHttp ####################################################################
# Suprimir avisos para anotações JSR 305.
-dontwarn javax.annotation.**
# Adaptar nomes de arquivos de recursos para o banco de dados interno de sufixos públicos.
-adaptresourcefilenames okhttp3/internal/publicsuffix/PublicSuffixDatabase.gz
# Suprimir avisos para o Animal Sniffer e classes específicas da plataforma.
-dontwarn org.codehaus.mojo.animal_sniffer.*
-dontwarn okhttp3.internal.platform.**
-dontwarn org.conscrypt.**
-dontwarn org.bouncycastle.**
-dontwarn org.openjsse.**
# Manter todas as classes do OkHttp e do Okio.
-keep class okhttp3.** { *; }
-dontwarn okhttp3.**
-keep class okio.** { *; }
-dontwarn okio.**
-dontwarn javax.annotation.Nullable
-dontwarn javax.annotation.ParametersAreNonnullByDefault
### FIM OkHttp ################################################################

### Serialização Kotlin ######################################################
# Manter objetos Companion para classes serializáveis.
-if @kotlinx.serialization.Serializable class **
-keepclassmembers class <1> {
    static <1>$Companion Companion;
}
# Manter funções serializer nos objetos companion.
-if @kotlinx.serialization.Serializable class ** {
    static **$* *;
}
-keepclassmembers class <2>$<3> {
    kotlinx.serialization.KSerializer serializer(...);
}
# Reter INSTANCE e serializer para objetos serializáveis.
-if @kotlinx.serialization.Serializable class ** {
    public static ** INSTANCE;
}
-keepclassmembers class <1> {
    public static <1> INSTANCE;
    kotlinx.serialization.KSerializer serializer(...);
}
# Preservar objetos Companion em kotlinx.serialization.json.
-keepclassmembers class kotlinx.serialization.json.** {
    *** Companion;
}
-keepclasseswithmembers class kotlinx.serialization.json.** {
    kotlinx.serialization.KSerializer serializer(...);
}
# Preservar a busca do serializer para classes serializáveis (ajuste o nome do pacote conforme necessário).
-keepclassmembers @kotlinx.serialization.Serializable class packeage.** {
    *** Companion;
    *** INSTANCE;
    kotlinx.serialization.KSerializer serializer(...);
}
### FIM Serialização Kotlin #################################################

### AutoValue ################################################################
-dontwarn com.google.auto.**
-dontwarn autovalue.shaded.com.**
-dontwarn sun.misc.Unsafe
-dontwarn javax.lang.model.element.Modifier
### FIM AutoValue ############################################################

### Plugin do Flutter ###########################################################
# Manter classes do plugin Flutter
-keep class io.flutter.plugins.** { *; }

# Manter classes do canal de método
-keep class * extends io.flutter.plugin.common.MethodChannel$MethodCallHandler { *; }
-keep class * extends io.flutter.plugin.common.MethodChannel$Result { *; }

# Manter o registrador do plugin
-keep class io.flutter.plugins.GeneratedPluginRegistrant { *; }

# Manter as classes do plugin Flutter do CAF SDK
-keep class io.caf.sdk.flutter.** { *; }
### FIM Plugin do Flutter #######################################################

### CAF - Combate a Fraude ######################################################
# Manter atributos de exceções.
-keepattributes Exceptions
# Preservar todas as classes, interfaces e membros de classe para os módulos CAF.
-keep class com.caf.facelivenessiproov.** { *; }
-keep class com.combateafraude.documentdetector.** { *; }
-keep class com.combateafraude.** { *; }
-keep interface com.combateafraude.** { *; }
-keep class io.caf.** { *; }
-keep interface io.caf.** { *; }
-keepclassmembers class com.combateafraude.** { *; }
# Suprimir avisos para java.nio.file e certas classes internas do OkHttp.
-dontwarn java.nio.file.*
-dontwarn com.squareup.okhttp.internal.Platform
# Manter campos em classes que estendem GeneratedMessageLite (para uso do Tink).
-keepclassmembers class * extends com.google.crypto.tink.shaded.protobuf.GeneratedMessageLite {
  <fields>;
}
# Preservar classes do TensorFlow.
-keep class org.tensorflow.** { *; }
-keep class org.tensorflow.**$* { *; }
-dontwarn org.tensorflow.**
# Preservar classes do IProov e classes Protobuf.
-keep public class com.iproov.sdk.IProov { public *; }
-keep class com.iproov.** { *; }
-keep class com.iproov.**$* { *; }
-keep class com.google.protobuf.** { *; }
-keep class com.google.protobuf.**$* { *; }
-dontwarn com.google.protobuf.**
# Suprimir avisos para classes Flow concorrentes.
-dontwarn java.util.concurrent.Flow*
# Preservar classes Kotlin e kotlinx.
-keep class kotlin.** { *; }
-keep class kotlinx.** { *; }
# Preservar todas as classes do FortFace/PayFace SDK para evitar problemas de ofuscação
-keep class br.com.fortface.** { *; }
-keep interface br.com.fortface.** { *; }
-keepclassmembers class br.com.fortface.** { *; }
# Manter todas as classes internas e enums
-keepclassmembers class br.com.fortface.**$* { *; }
# Preservar completamente as classes JSON (crítico para o PayFace)
-keep class org.json.** { *; }
-keepclassmembers class org.json.** { *; }
# Preservar as classes relacionadas a JSON usadas pelo SDK PayFace
-keepclassmembers class * {
    @org.json.** *;
}
# Suprimir avisos para o SDK PayFace
-dontwarn br.com.fortface.**
-dontwarn com.android.tools.lint.**
-dontwarn io.caf.sdk.common.jvmshared.lint.**
### FIM CAF - Combate a Fraude ##################################################

---

Suporte técnico e dicas de uso

Suporte técnico Se você tiver alguma dúvida ou dificuldade com a integração, entre em contato com o suporte técnico da Caf.

Dicas de uso

• Execute testes: Realize testes em dispositivos reais para validar os requisitos e o desempenho do fluxo
• Explore personalizações: Use opções avançadas de personalização para adaptar o fluxo às necessidades do seu projeto
• Monitore o desempenho: Integre ferramentas de monitoramento para acompanhar os logs e o desempenho do fluxo em produção
• Lide com erros de forma elegante: Implemente o tratamento adequado de erros para todos os possíveis cenários de erro e falha
• Teste com diferentes dispositivos: Garanta compatibilidade entre várias especificações de dispositivos e tamanhos de tela

---

Notas de lançamento

[email protected]

Data de lançamento

• 08-03-2026

Alteração incompatível : O módulo Fingerprint agora é opcional e pode ser configurado em caf-modules-config.json por meio da nova fingerprint propriedade (booleano). Por padrão, a impressão digital está definida como false, o que significa que você não precisa adicionar essa propriedade ao JSON, a menos que queira usá-la. Para ativar o módulo, você deve adicionar explicitamente "fingerprint": true. Importante: a impressão digital também deve ser ativada no Backoffice. Se ela não estiver ativada no Backoffice, o SDK nunca chamará a biblioteca de impressão digital e nenhum dado será enviado, mesmo que a propriedade esteja definida como true localmente.

Destaques

• Módulo Fingerprint opcional: Controle a inclusão do recurso de impressão digital diretamente de caf-modules-config.json. Ele está desativado por padrão, garantindo que você só inclua a dependência quando estritamente necessário.

Atualizações

• Novo fingerprint campo booleano em caf-modules-config.json para Android e iOS.

{
  "documentDetector": true,
  "faceLiveness": true,
  "documentDetectorUI": true,
  "faceLivenessUI": true,
  "livenessProviders": [
    "iproov-lite",
    "payface",
    "facetec"
  ],
  "fingerprint": true
}

[email protected]

Data de lançamento

• 07-06-2026

Alteração incompatível: A eventStream agora emite um tipado Stream<CafResponse> em vez de um Stream<dynamic> com cargas úteis brutas. Map Atualize todos os listeners: substitua event['eventName'] / event['response'] pelos campos tipados — event.success, event.error, event.failure, event.log, event.loading, event.loaded, e event.cancelled. Veja Tratamento de Eventos o exemplo completo de migração.

Destaques

• Relato de erros mais consistente: Erros que ocorrem durante a inicialização do fluxo e estão relacionados à integração interna do SDK agora são emitidos por meio do error evento como BRIDGE_EXCEPTION, para que possam ser tratados da mesma forma que qualquer outro erro do SDK.

Mudanças Incompatíveis

• Stream de eventos tipado: CafSdk.eventStream agora é Stream<CafResponse>. Os consumidores devem acessar os campos tipados de CafResponse (success, error, failure, log, loading, loaded, cancelled) em vez de indexar um Map.
• Classes de configuração de módulo simplificadas: O ...BuilderConfiguration os wrappers foram removidos. Os campos agora são passados diretamente nos objetos de configuração do módulo, e as configurações da UI estendem a configuração base em vez de aninhá-la:

  • CafFaceLivenessBuilderConfiguration removido — passe os campos diretamente em CafFaceLivenessConfiguration.
  • CafDocumentDetectorBuilderConfiguration removido — passe os campos diretamente em CafDocumentDetectorConfiguration.
  • CafFaceLivenessUIBuilderInstructionScreenConfiguration → CafFaceLivenessUIInstructionScreenConfiguration, e o campo instructionScreenConfiguration → instructionScreen.
  • CafDocumentDetectorUIBuilderInstructionScreenConfiguration → CafDocumentDetectorUIInstructionScreenConfiguration, e o campo instructionScreenConfiguration → instructionScreen.
  • CafDocumentDetectorUIBuilderDocumentSelectionScreenConfiguration → CafDocumentDetectorUIDocumentSelectionScreenConfiguration, e o campo documentSelectionScreenConfiguration → documentSelectionScreen.
  • No nível do SDK CafSdkConfiguration permanece inalterado e ainda recebe configuration: CafSdkBuilderConfiguration(...).
• initializeCafSdk tipo de retorno: alterado de Future<bool?> para Future<bool>.

Atualizações

• Constantes de nome dos eventos: Adicionadas as CafSdkEventName constantes (CafUnifiedEvent.*) para identificar os eventos emitidos.
• Novo CafErrorType valores: Adicionados INVALID_RESPONSE_EXCEPTION, CAMERA_EXCEPTION, FACE_AUTHENTICATION, e BRIDGE_EXCEPTION. Observe que BRIDGE_EXCEPTION relata erros que ocorrem ao inicializar ou iniciar o fluxo; ouça-o no error evento e trate-o como parte do seu tratamento normal de erros.
• CafSuccessResponse: signedResponse agora é tipado como String? (anteriormente dynamic), e moduleName a resolução é mais resiliente a variações de identificadores nativos.

Guia de Migração — 1.x → 2.0.0

Três coisas mudaram para os integradores: como você lê eventos, como constrói configurações de módulo e o tipo de retorno de initializeCafSdk. No nível do SDK CafSdkConfiguration (com CafSdkBuilderConfiguration) permanece inalterado.

1. Leia eventos do stream tipado

// Antes (1.x) — Map bruto
_cafSdk.eventStream.listen((event) {
  final name = event['eventName'];
  final response = event['response'];
});

// Depois (2.0.0) — CafResponse tipado
_cafSdk.eventStream.listen((event) {
  if (event.success != null) {
    print('${event.success!.moduleName} -> ${event.success!.signedResponse}');
  } else if (event.error != null) {
    print('${event.error!.type} - ${event.error!.description}');
  }
  // também: event.failure, event.log, event.loading, event.loaded, event.cancelled
});

2. Remova o módulo ...BuilderConfiguration wrapper

Passe os campos diretamente no objeto de configuração do módulo.

// Antes (1.x)
final faceLivenessConfig = CafFaceLivenessConfiguration(
  configuration: CafFaceLivenessBuilderConfiguration(
    loading: true,
    maxRetryAttempts: 2,
  ),
);

// Depois (2.0.0)
final faceLivenessConfig = CafFaceLivenessConfiguration(
  loading: true,
  maxRetryAttempts: 2,
);

// Antes (1.x)
final documentDetectorConfig = CafDocumentDetectorConfiguration(
  configuration: CafDocumentDetectorBuilderConfiguration(
    flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)],
    manualCaptureEnabled: false,
  ),
);

// Depois (2.0.0)
final documentDetectorConfig = CafDocumentDetectorConfiguration(
  flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)],
  manualCaptureEnabled: false,
);

3. Atualize as configurações de UI (wrapper + tipos e campos renomeados)

// Antes (1.x)
final faceLivenessUIConfig = CafFaceLivenessUIConfiguration(
  configuration: CafFaceLivenessBuilderConfiguration(loading: true),
  instructionScreenConfiguration:
      CafFaceLivenessUIBuilderInstructionScreenConfiguration(title: 'Face Liveness'),
);

// Depois (2.0.0)
final faceLivenessUIConfig = CafFaceLivenessUIConfiguration(
  loading: true,
  instructionScreen:
      CafFaceLivenessUIInstructionScreenConfiguration(title: 'Face Liveness'),
);

// Antes (1.x)
final documentDetectorUIConfig = CafDocumentDetectorUIConfiguration(
  configuration: CafDocumentDetectorBuilderConfiguration(
    flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)],
  ),
  instructionScreenConfiguration:
      CafDocumentDetectorUIBuilderInstructionScreenConfiguration(enable: true),
  documentSelectionScreenConfiguration:
      CafDocumentDetectorUIBuilderDocumentSelectionScreenConfiguration(title: 'Choose document'),
);

// Depois (2.0.0)
final documentDetectorUIConfig = CafDocumentDetectorUIConfiguration(
  flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)],
  instructionScreen:
      CafDocumentDetectorUIInstructionScreenConfiguration(enable: true),
  documentSelectionScreen:
      CafDocumentDetectorUIDocumentSelectionScreenConfiguration(title: 'Choose document'),
);

4. Renomeie as importações de tipos (se você importou os tipos removidos)

Removido (1.x)	Use em vez disso (2.0.0)
CafFaceLivenessBuilderConfiguration	CafFaceLivenessConfiguration
CafDocumentDetectorBuilderConfiguration	CafDocumentDetectorConfiguration
CafFaceLivenessUIBuilderInstructionScreenConfiguration	CafFaceLivenessUIInstructionScreenConfiguration
CafDocumentDetectorUIBuilderInstructionScreenConfiguration	CafDocumentDetectorUIInstructionScreenConfiguration
CafDocumentDetectorUIBuilderDocumentSelectionScreenConfiguration	CafDocumentDetectorUIDocumentSelectionScreenConfiguration

5. Atualize o initializeCafSdk tipo de retorno

initializeCafSdk agora retorna Future<bool> em vez de Future<bool?>. Remova qualquer verificação de nulo no resultado aguardado.

// Antes (1.x)
final bool? started = await _cafSdk.initializeCafSdk(
  cafSdkConfiguration: config,
);
if (started == true) {
  // ...
}

// Depois (2.0.0)
final bool started = await _cafSdk.initializeCafSdk(
  cafSdkConfiguration: config,
);
if (started) {
  // ...
}

[email protected]

Data de lançamento

• 05-25-2026

Atualizações

• Provedor de Liveness da Payface (Android): Atualize a versão de 1.18.2 para 1.19.2.
• Provedor de Liveness da Payface (iOS): Atualize a versão de 1.5.2 para 1.8.2.

Correções

FaceLiveness

• O erro de carregamento infinito ocorre quando o SDK retorna um erro.
• A primeira inicialização não funciona ao usar Payface provedor.

[email protected]

Data de lançamento

• 05-08-2026

Correções

• DocumentDetector: Corrigido o comportamento ao lidar com RG (Carteira de Identidade Nacional brasileira) com a opção de documento digital.

[email protected]

Data de lançamento

• 04-13-2026

Alteração incompatível : Os provedores de Face Liveness agora podem ser configurados em caf-modules-config.json via livenessProviders (string ou array). Quando fornecido, ele deve listar o(s) provedor(es) escolhido(s). Não use iproov-lite e iproov-full juntos —iproov-full usa uma versão diferente do Protobuf, e combiná-los causará erros de classe duplicada no momento da compilação. PayFace requer iproov-lite (Protobuf JavaLite); combinar PayFace com iproov-full causa conflitos de Protobuf na compilação. Se omitido, o SDK usa por padrão iproov-lite em ambas as plataformas. Um valor vazio ou inválido causa um erro de compilação no Android; no iOS, um valor vazio também recorre a iproov-lite, mas um valor inválido causa falha na compilação. Veja Passo 2: Configure a seleção de módulos para detalhes.

Destaques

• Provedores de Face Liveness configuráveis: Escolha iproov-lite, iproov-full, payface, e/ou facetec de caf-modules-config.json em vez de depender dos padrões nativos implícitos.

Atualizações

• Configuração do provedor de Liveness:

  • Novo livenessProviders campo em caf-modules-config.json para Android e iOS.
  • Documentado Protobuf JavaLite vs Protobuf Java mapeamento para iproov-lite vs iproov-full.
  • Esclarecido com vários provedores usando um array, e a PayFace + iProov Lite exigência.
• Provedor de Liveness iProov: Documentação e padrões atualizados para refletir o novo modelo de seleção de provedor.
• Android ProGuard / R8: Se o R8 relatar classes ausentes para os stubs de lint fornecidos com o SDK, adicione o seguinte a proguard-rules.pro (também listado em Regras do ProGuard/R8):

-dontwarn com.android.tools.lint.**
-dontwarn io.caf.sdk.common.jvmshared.lint.**

[email protected]

Data de lançamento

• 02-09-2026

Versões anteriores à 1.2.0 farão com que o iProov Liveness se torne inoperante a partir de 12 de março de 2026. Para garantir o funcionamento adequado e a continuidade do serviço, use a versão 1.2.0 ou posterior.

Destaques

• Provedor de Liveness atualizado: Atualização crítica da versão do provedor iProov para melhor estabilidade

Atualizações

• Provedor de Liveness iProov: Atualizada a versão interna do provedor iProov.

[email protected]

Data de lançamento

• 02-09-2026

Destaques

• Novo módulo de segurança: Introdução do CafSecurity módulo para validações de segurança
• Integração com PayFace: Adicionado suporte ao PayFace (Fortface) como provedor opcional de Face Liveness
• Melhorias de estabilidade: Correções importantes de falhas e melhorias de estabilidade para o módulo Document Detector

Recursos

• Módulo CafSecurity:

  • Adicionado um novo módulo especificamente para validações de segurança
  • Configuração: Adicionados enableSecurityModule flag em CafSdkConfiguration (valor padrão: true)
• Integração com PayFace (Fortface):

  • Integração opcional com provedor de Face Liveness
  • Configuração: Nova propriedade payFaceDebugMode em CafFaceLivenessConfiguration para ativar o modo de depuração para o provedor PayFace

Correções

• DocumentDetector:

  • Ciclo de vida da Activity: Resolvidos vários travamentos relacionados ao gerenciamento do ciclo de vida da activity (estados de inicialização, pausa e retomada)
  • Ciclo de vida da câmera: Melhorado o gerenciamento de recursos da câmera e do ciclo de vida das threads para evitar travamentos durante o encerramento do SDK
  • Componentes de UI: Resolvidos problemas de compatibilidade de tema e exceções de transação de fragmentos
  • Requisições de rede: Corrigido o manuseio do corpo da resposta para evitar erros ao ler respostas de rede
  • Acesso a dados: Melhorada a inicialização e validação do cursor antes de acessar dados do banco de dados
  • Prevenção de ANR: Otimizadas as verificações de instância do controlador de documentos para evitar problemas de "Aplicativo não respondendo"
  • Geral: Melhorias internas e correções de estabilidade
• FaceLiveness:

  • Sessões: Corrigidos erros de criação de sessão
  • UI: Corrigida a tonalidade de cor em imagens remotas na tela de Instruções

Atualizações

• Configuração de compilação:

  • Regras do ProGuard: Adicionadas as regras necessárias do ProGuard para a integração com PayFace

[email protected]

Data de lançamento

• 03-09-2026

Atualizações

• Provedor de Liveness iProov atualizado: Atualize a versão do provedor iProov.
• Atualizado o target mínimo de implantação do iOS: Atualizado para 15.0.

Correções

• DocumentDetector

  • Corrigidos travamentos no módulo Document Detector: Resolvidos vários travamentos relacionados ao gerenciamento do ciclo de vida da activity, incluindo estados de inicialização, pausa e retomada.
  • Corrigidos travamentos relacionados ao ciclo de vida da câmera: Melhorado o gerenciamento de recursos da câmera e do ciclo de vida das threads para evitar travamentos durante o encerramento do SDK e transições de estado.
  • Corrigidos travamentos nos componentes de UI: Resolvidos problemas de compatibilidade de tema e exceções de transação de fragmentos para garantir o comportamento adequado da UI.
  • Corrigidos travamentos em requisições de rede: Corrigido o manuseio do corpo da resposta para evitar erros ao ler respostas de rede.
  • Corrigidos travamentos no acesso a dados: Melhorada a inicialização e validação do cursor antes de acessar dados do banco de dados.
  • Corrigido ANR no Document Controller: Otimizadas as verificações de instância do controlador de documentos para evitar problemas de aplicativo não respondendo.
  • Melhorias e correções internas: Melhorias adicionais de estabilidade e correções de bugs.

[email protected]

Data de lançamento

• 10-27-2025

Destaques

• Primeira versão do Flutter SDK: Implementação completa em Flutter do CAF SDK para verificação de identidade
• SDK unificado: Pacote único contendo todos os módulos CAF (Face Liveness e Document Detector) com variantes de core e UI
• Integração Flutter-Nativa: Integração perfeita com o sistema de widgets e o gerenciamento de estado do Flutter
• Suporte multiplataforma: Suporte completo para as plataformas Android e iOS
• Configuração com segurança de tipos: Classes de configuração Dart fortemente tipadas para uma melhor experiência de desenvolvimento

Recursos

• Sistema de configuração de módulos:

  • caf-modules-config.json: Arquivo de configuração na raiz do projeto para especificar quais módulos incluir
  • Módulos disponíveis:

    • documentDetector: Ativar/desativar o módulo Document Detector
    • faceLiveness: Ativar/desativar o módulo Face Liveness
    • documentDetectorUI: Ativar/desativar o módulo de UI do Document Detector
    • faceLivenessUI: Ativar/desativar o módulo de UI do Face Liveness
  • Exemplo de configuração:

    {
      "documentDetector": true,
      "faceLiveness": true,
      "documentDetectorUI": false,
      "faceLivenessUI": false
    }

• Recursos principais do SDK:

  • Classe CafSdk: Classe principal do SDK para inicialização e configuração
  • Stream de eventos: Tratamento de eventos em tempo real por meio de streams Dart
  • Gerenciamento de módulos: Execução sequencial de módulos com ordem de apresentação configurável
  • Tratamento de erros: Tipos de erro abrangentes e tratamento de falhas
  • Builder de configuração: Configuração com segurança de tipos usando o padrão builder
• Módulo Face Liveness:

  • Módulo principal: CafFaceLivenessConfiguration para controle programático
  • Módulo de UI: CafFaceLivenessUIConfiguration com telas de instruções personalizáveis
  • Recursos: URLs de autenticação, pinagem de certificado, modo de depuração, tentativas de repetição
  • Personalização: Telas de instrução com imagens, títulos, descrições e etapas
• Módulo Document Detector:

  • Módulo principal: CafDocumentDetectorConfiguration para controle programático
  • Módulo de UI: CafDocumentDetectorUIConfiguration com personalização completa da UI
  • Tipos de Documento: Suporte para RG, CNH, Passaporte, RNE, CTPS e mais
  • Suporte a upload: Upload de arquivos com compactação, controle de formato e limites de tamanho
  • Configuração de Proxy: Suporte a servidores proxy com autenticação
  • Personalização de Mensagens: Mensagens personalizáveis para o usuário durante todo o fluxo
• Configuração Avançada:

  • Tema de cores: Personalização completa das cores da UI por meio de CafColorConfiguration
  • Configurações de segurança: Flags de desenvolvimento, modo de depuração e controles de segurança
  • Controle de fluxo: Captura manual, timeouts, tentativas de repetição e controles de pop-up
  • Telas de instrução: Telas de instrução personalizáveis para ambos os módulos

Implementação técnica

• Integração com Flutter:

  • Method Channels: Comunicação nativa por meio do sistema de method channels do Flutter
  • Eventos baseados em stream: Tratamento de eventos em tempo real usando streams Dart
  • Gerenciamento de estado: Gerenciamento adequado do ciclo de vida com StatefulWidget suporte
  • Tratamento de erros: Tratamento abrangente de erros com exceções tipadas
• Suporte à plataforma:

  • Android: Suporte completo com regras do ProGuard/R8 e configuração do repositório Maven
  • iOS: Integração completa com CocoaPods e módulos nativos do iOS
  • Permissões: Tratamento adequado de permissões para acesso à câmera e à rede
• Desempenho:

  • Carregamento seletivo de módulos: Carregue apenas os módulos ativados para otimizar o tamanho do pacote
  • Gerenciamento de memória: Limpeza adequada de recursos e gerenciamento de memória
  • Otimização de rede: Comunicação de rede eficiente com mecanismos de repetição

Instalação e configuração

• Instalação do pacote: Instalação simples via flutter pub add caf_sdk
• Configuração de módulos: Seleção fácil de módulos por meio de arquivo de configuração JSON
• Configuração da plataforma: Instruções claras para configuração das plataformas Android e iOS
• Gerenciamento de Permissões: Configuração abrangente de permissões para ambas as plataformas

Documentação

• Exemplos Completos: Exemplos completos de implementação para uso básico e avançado
• Guia de Configuração: Opções de configuração detalhadas para todos os módulos
• Tratamento de Eventos: Exemplos e padrões abrangentes de tratamento de eventos
• Referência de Erros: Documentação completa dos tipos de erro e cenários de falha

Mudanças Incompatíveis

• Primeira Versão: Esta é a primeira versão do SDK Flutter, então não há mudanças que causem quebra de compatibilidade em relação às versões anteriores.

Problemas Conhecidos

• Simulador iOS: Alguns recursos podem não funcionar corretamente no Simulador iOS devido a limitações da câmera
• Emulador Android: Recursos que dependem da câmera exigem dispositivos físicos para testes
• Requisitos de Rede: Todos os módulos exigem conexão com a internet para funcionar corretamente