Migrando do CafSdk

Migre um app Flutter da API sequencial CafSdk para o Certta DevX no caf_sdk 2.4.0. Compare configuração, inicialização do módulo e tratamento de eventos.

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.

A partir de caf_sdk 2.4.0, Certta DevX (CerttaSdk) é a API recomendada para novas integrações. A API sequencial CafSdk API continua disponível no mesmo pacote. Os initializeCafSdk fluxos existentes continuam funcionando.

Esta página mapeia a API sequencial legada para módulos independentes open() chamadas.

Comparação de APIs

Área	CafSdk (legado)	Certta DevX (2.4.0+)
Importação	package:caf_sdk/caf_sdk.dart	package:caf_sdk/certta_sdk.dart
Ponto de entrada	CafSdk()	CerttaSdk()
Sessão	CafSdkConfiguration + initializeCafSdk(...)	configureSdk(CerttaConfiguration)
Ordem dos módulos	presentationOrder executa Face Liveness e Document Detector em uma única sequência	Cada módulo é aberto independentemente
Inicialização	Uma initializeCafSdk inicia todo o pipeline	liveness.open, documentDetector.open, documentDetectorUi.open
Eventos	Único eventStream de CafResponse	Streams por módulo + logStream
Identificador da pessoa	personId	userId
Flag de segurança	CafSdkBuilderConfiguration.enableSecurityModule	CerttaConfiguration.securityEnabled
Cores	CafSdkBuilderConfiguration.colorConfiguration	CerttaConfiguration.colorConfiguration

Seleção de módulos (caf-modules-config.json), repositórios Maven, CocoaPods, permissões e ProGuard não mudam. Siga o Guia de Instalação.

1. Configure a sessão uma vez

// Antes (CafSdk)
final cafSdk = CafSdk();
await cafSdk.initializeCafSdk(
  cafSdkConfiguration: CafSdkConfiguration(
    mobileToken: 'token',
    personId: 'personId',
    environment: CafEnvironment.prod,
    configuration: CafSdkBuilderConfiguration(
      presentationOrder: [
        CafModuleType.faceLiveness,
        CafModuleType.documentDetector,
      ],
      enableSecurityModule: true,
    ),
  ),
  faceLivenessConfiguration: faceLivenessConfig,
  documentDetectorConfiguration: documentDetectorConfig,
);

// Depois (Certta)
import 'package:flutter/services.dart';

final certta = CerttaSdk();
try {
  await certta.configureSdk(
    const CerttaConfiguration(
      mobileToken: 'token',
      userId: 'personId',
      environment: CafEnvironment.prod,
      securityEnabled: true,
    ),
  );
} on PlatformException catch (e) {
  // Trate BRIDGE_EXCEPTION
}

Depois configureSdk, atualize as credenciais sem reconstruir a configuração completa:

try {
  await certta.updateUserId('novo-id-do-usuario');
  await certta.updateMobileToken('novo-jwt-token');
} on PlatformException catch (e) {
  // Trate BRIDGE_EXCEPTION
}

2. Abra um módulo por vez

Não há presentationOrder na Certta. Inicie Face Liveness ou Document Detector quando o fluxo do seu produto precisar.

import 'package:flutter/services.dart';

// Vivacidade facial
try {
  await certta.liveness.open(
    const CerttaLivenessConfiguration(
      maxRetryAttempts: 3,
      faceAuthEnabled: false,
      showLoading: true,
      useFaceLivenessUi: true,
    ),
  );
} on PlatformException catch (e) {
  // Trate BRIDGE_EXCEPTION
}

// Detector de documentos (sem interface)
try {
  await certta.documentDetector.open(
    CerttaDocumentDetectorConfiguration(
      flow: [
        CafDocumentDetectorFlow(document: CafDocument.rgFront),
        CafDocumentDetectorFlow(document: CafDocument.rgBack),
      ],
    ),
  );
} on PlatformException catch (e) {
  // Trate BRIDGE_EXCEPTION
}

// Detector de documentos (interface)
try {
  await certta.documentDetectorUi.open(
    CerttaDocumentDetectorUiConfiguration(
      flow: [CafDocumentDetectorFlow(document: CafDocument.rgFront)],
    ),
  );
} on PlatformException catch (e) {
  // Trate BRIDGE_EXCEPTION
}

Configuração legada do módulo	Inicialização da Certta
CafFaceLivenessConfiguration	CerttaLivenessConfiguration (useFaceLivenessUi: false)
CafFaceLivenessUIConfiguration	CerttaLivenessConfiguration (useFaceLivenessUi: true)
CafDocumentDetectorConfiguration	CerttaDocumentDetectorConfiguration
CafDocumentDetectorUIConfiguration	CerttaDocumentDetectorUiConfiguration

A configuração de vivacidade da Certta é um conjunto menor: maxRetryAttempts, faceAuthEnabled, showLoading, useFaceLivenessUi, e payFaceDebugMode (iOS). URLs de proxy, certificados e campos da tela de instruções do Face Liveness de CafFaceLivenessConfiguration não fazem parte do objeto de configuração da Certta.

3. Ouça eventos tipados do módulo

// Antes — um stream, CafResponse
cafSdk.eventStream.listen((event) {
  if (event.success != null) { /* moduleName + signedResponse */ }
  if (event.failure != null) { /* CafFailureType */ }
  if (event.error != null) { /* CafErrorType */ }
  if (event.cancelled) { /* usuário cancelou */ }
});

// Depois — assine por módulo (antes de abrir)
certta.liveness.eventStream.listen((event) {
  if (event.success != null) { /* JWT in event.success!.response */ }
  if (event.failed != null) { /* CerttaLivenessFailure */ }
  if (event.error != null) { /* CerttaError */ }
});

certta.documentDetector.eventStream.listen((event) {
  if (event.success != null) { /* JWT */ }
  if (event.error != null) { /* CerttaError */ }
});

certta.logStream.listen((log) {
  print('${log.level}: ${log.message}');
});

CafSdk CafResponse	Equivalente na Certta
success.signedResponse	event.success.response
success.moduleName	Implícito pelo stream que recebeu o evento
failure	CerttaLivenessEvent.failed (CerttaLivenessFailure)
error	event.error (CerttaError)
cancelled	Exposto como CerttaError (cancelled / tipo semelhante)
log	CerttaSdk.logStream
loading / loaded	Não encaminhado nos streams do módulo Certta

As rejeições do mapeador de bridge lançam PlatformException com CerttaErrorCode.bridgeException (BRIDGE_EXCEPTION) em vez de aparecer apenas em eventStream.

4. Pipelines sequenciais

Se você usou presentationOrder, telas de transição (enableTransitionScreens), ou waitForAllServices Com o CafSdk, o mesmo fluxo de produto pode ser construído com o Certta DevX: configure a sessão uma vez e, em seguida, encadeie chamadas de módulo open() chamadas a partir da lógica do seu app (por exemplo, iniciar Face Liveness quando o Document Detector emitir success em eventStream).

A versão sequencial CafSdk API continua disponível em package:caf_sdk/caf_sdk.dart e está documentada em Guia de início rápido legado. Ambas as APIs são compatíveis e cobrem necessidades de integração equivalentes — prefira a Certta DevX para novos desenvolvimentos e ao migrar apps existentes.

Próximos passos

Guia de InstalaçãoFace LivenessDocument Detector