Migrating from CafSdk

Migrate a Flutter app from the sequential CafSdk API to Certta DevX in caf_sdk 2.4.0. Compare configuration, module launch, and event handling.

This guide covers caf_sdk 2.4.0 and above (Certta DevX). For the previous CafSdk sequential flow, see the legacy documentation.

Starting with caf_sdk 2.4.0, Certta DevX (CerttaSdk) is the recommended API for new integrations. The sequential CafSdk API remains available in the same package. Existing initializeCafSdk flows keep working.

This page maps the legacy sequential API to independent module open() calls.

API comparison

Area	CafSdk (legacy)	Certta DevX (2.4.0+)
Import	package:caf_sdk/caf_sdk.dart	package:caf_sdk/certta_sdk.dart
Entry point	CafSdk()	CerttaSdk()
Session	CafSdkConfiguration + initializeCafSdk(...)	configureSdk(CerttaConfiguration)
Module order	presentationOrder runs Face Liveness and Document Detector in one sequence	Each module is opened independently
Launch	One initializeCafSdk starts the whole pipeline	liveness.open, documentDetector.open, documentDetectorUi.open
Events	Single eventStream of CafResponse	Per-module streams + logStream
Person identifier	personId	userId
Security flag	CafSdkBuilderConfiguration.enableSecurityModule	CerttaConfiguration.securityEnabled
Colors	CafSdkBuilderConfiguration.colorConfiguration	CerttaConfiguration.colorConfiguration

Module selection (caf-modules-config.json), Maven repositories, CocoaPods, permissions, and ProGuard do not change. Follow the Installation Guide.

1. Configure the session once

// Before (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,
);

// After (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) {
  // Handle BRIDGE_EXCEPTION
}

After configureSdk, update credentials without rebuilding the full configuration:

try {
  await certta.updateUserId('new-user-id');
  await certta.updateMobileToken('new-jwt-token');
} on PlatformException catch (e) {
  // Handle BRIDGE_EXCEPTION
}

2. Open one module at a time

There is no presentationOrder on Certta. Start Face Liveness or Document Detector when your product flow needs it.

import 'package:flutter/services.dart';

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

// Document Detector (headless)
try {
  await certta.documentDetector.open(
    CerttaDocumentDetectorConfiguration(
      flow: [
        CafDocumentDetectorFlow(document: CafDocument.rgFront),
        CafDocumentDetectorFlow(document: CafDocument.rgBack),
      ],
    ),
  );
} on PlatformException catch (e) {
  // Handle BRIDGE_EXCEPTION
}

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

Legacy module config	Certta launch
CafFaceLivenessConfiguration	CerttaLivenessConfiguration (useFaceLivenessUi: false)
CafFaceLivenessUIConfiguration	CerttaLivenessConfiguration (useFaceLivenessUi: true)
CafDocumentDetectorConfiguration	CerttaDocumentDetectorConfiguration
CafDocumentDetectorUIConfiguration	CerttaDocumentDetectorUiConfiguration

Certta liveness configuration is a smaller set: maxRetryAttempts, faceAuthEnabled, showLoading, useFaceLivenessUi, and payFaceDebugMode (iOS). Proxy URLs, certificates, and Face Liveness instruction-screen fields from CafFaceLivenessConfiguration are not part of the Certta configuration object.

3. Listen to typed module events

// Before — one 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) { /* user cancelled */ }
});

// After — subscribe per module (before open)
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	Certta equivalent
success.signedResponse	event.success.response
success.moduleName	Implied by which stream received the event
failure	CerttaLivenessEvent.failed (CerttaLivenessFailure)
error	event.error (CerttaError)
cancelled	Surfaced as CerttaError (cancelled / similar type)
log	CerttaSdk.logStream
loading / loaded	Not forwarded on Certta module streams

Bridge mapper rejections throw PlatformException with CerttaErrorCode.bridgeException (BRIDGE_EXCEPTION) instead of only appearing on eventStream.

4. Sequential pipelines

If you used presentationOrder, transition screens (enableTransitionScreens), or waitForAllServices with CafSdk, the same product flow can be built with Certta DevX: configure the session once, then chain module open() calls from your app logic (for example, start Face Liveness when Document Detector emits success on eventStream).

The sequential CafSdk API remains available in package:caf_sdk/caf_sdk.dart and is documented in Legacy Getting Started. Both APIs are supported and cover equivalent integration needs — prefer Certta DevX for new work and when migrating existing apps.

Next steps

Installation GuideFace LivenessDocument Detector