Installation Guide

Install and configure Certta for Flutter. Learn SDK requirements, module selection, permissions, session setup, runtime token updates, and color theming.

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

Installing the SDK for Flutter

This guide walks you through the setup required to download, configure, and initialize Certta (caf_sdk 2.4.0+) in a Flutter app.

Check out the example app for a complete implementation example.

Requirements

Requirement	Version
Flutter	3.3.0+
Dart	3.9.0+
Android minSdk	26
Android compileSdk	36+
Kotlin	1.8+
Gradle	8.0+
Android Gradle Plugin (AGP)	8.0+
iOS deployment target	15.0+
Xcode	14.0+
Swift	5.0+

Step 1: Install the SDK

flutter pub add caf_sdk

The published package version is 2.4.0. Import the Certta DevX API with:

import 'package:caf_sdk/certta_sdk.dart';

The sequential CafSdk / initializeCafSdk API remains available via package:caf_sdk/caf_sdk.dart. Prefer Certta for new integrations. See Migrating from CafSdk.

Step 2: Configure module selection

Create a caf-modules-config.json file in your project root (next to pubspec.yaml) to choose which native modules to bundle:

If you omit this file, all modules are enabled by default and iproov-lite is used as the Face Liveness provider.

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

Set to true the modules you want to use.

For a single provider, livenessProviders can be a string. Allowed values are iproov-lite, iproov-full, payface, and facetec. To use several providers, use an array:

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

iProov and Protobuf

• iproov-lite: use when your app targets Protobuf JavaLite — the usual choice for a smaller Android binary.
• iproov-full: use when you need Protobuf Java (full) together with iProov.

If you include the PayFace provider, you must also use iProov Lite (iproov-lite). PayFace is built against Protobuf JavaLite; mixing it with iproov-full causes Protobuf dependency conflicts at build time.

Fingerprint

The Fingerprint module is optional (fingerprint, boolean). It defaults to false. To enable it, set "fingerprint": true.

Fingerprint is collected as part of the liveness flow, so it is only bundled when faceLiveness or faceLivenessUI is also enabled. Setting "fingerprint": true without a liveness module has no effect.

Contact CAF Support to request activation on the backend. If it is not enabled on our side, the SDK will not trigger the fingerprint library even if the property is true locally.

Step 3: Android configuration

Configure the repositories block in your project's android/build.gradle.kts (usually at the root level):

Kotlin Script

repositories {
    maven { url = uri("https://repo.combateafraude.com/android/release") }
}

Groovy

repositories {
    maven { url "https://repo.combateafraude.com/android/release" }
}

Step 4: iOS configuration

Navigate to the ios/ directory of your Flutter project and run:

pod install

• This step is mandatory so iOS can link the native modules.
• Re-run pod install whenever native dependencies are added or updated.

---

Permissions

Android

Declare the following in AndroidManifest.xml:

Face Liveness

Permission	Description	Necessity
android.permission.CAMERA	Camera access for face verification (liveness).	Mandatory
android.permission.INTERNET	Communication with authentication and verification services (HTTPS/WSS).	Mandatory

Document Detector

Permission	Description	Necessity
android.permission.CAMERA	Camera access to capture document images.	Only for capture
android.permission.INTERNET	Upload captured images for processing and validation.	Mandatory
android.permission.READ_EXTERNAL_STORAGE	Access stored files when document upload is enabled.	Only for upload

Document Detector requires READ_EXTERNAL_STORAGE when document upload is enabled.

iOS

Declare the following in Info.plist:

Face Liveness

Permission	Description	Necessity
NSCameraUsageDescription	Camera access for face verification (liveness).	Mandatory
Network access	Communication with authentication and verification services (HTTPS/WSS).	Mandatory

Document Detector

Permission	Description	Necessity
NSCameraUsageDescription	Camera access to capture document images.	Only for capture
Network access	Upload captured images for processing and validation.	Mandatory
NSPhotoLibraryUsageDescription	Access stored files when document upload is enabled.	Only for upload

---

Configuring the session

To generate your mobile token, follow this guide:

Authentication

Initialize Certta once you have a valid mobile token (JWT) and user ID — typically after login:

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

final certta = CerttaSdk();

try {
  await certta.configureSdk(
    const CerttaConfiguration(
      mobileToken: 'your-jwt',
      userId: 'user-id',
      environment: CafEnvironment.prod,
      securityEnabled: true,
    ),
  );
} on PlatformException catch (e) {
  // Handle BRIDGE_EXCEPTION
}

You can confirm the session with await certta.isInitialized().

CerttaConfiguration parameters

Parameter	Type	Description
mobileToken	String	CAF mobile JWT from your backend.
userId	String	End-user identifier.
environment	CafEnvironment	Backend environment: prod, beta, or dev.
securityEnabled	bool	Enables security checks. Default true.
colorConfiguration	CafColorConfiguration?	Optional color theme. See Color theming.

configureSdk throws a PlatformException with code BRIDGE_EXCEPTION when the native mapper rejects the configuration.

Runtime configuration updates

userId and mobileToken can be updated after the initial configureSdk without repeating the full configuration. Call these after login, logout, or token refresh:

await certta.updateUserId('new-user-id');
await certta.updateMobileToken('new-jwt-token');

Use these methods whenever your app performs logout/login or when your backend issues a refreshed JWT so Certta stays synchronized with the active session.

Logs

SDK pipeline logs are emitted on CerttaSdk.logStream:

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

---

Color theming

Face Liveness and Document Detector support custom colors so the SDK UI can match your brand. Pass hexadecimal strings (for example "#RRGGBB") on CafColorConfiguration when you call configureSdk.

await certta.configureSdk(
  CerttaConfiguration(
    mobileToken: 'your-jwt',
    userId: 'user-id',
    environment: CafEnvironment.prod,
    colorConfiguration: const CafColorConfiguration(
      primaryColor: '#FF0000',
      secondaryColor: '#00FF00',
      backgroundColor: '#FFFFFF',
      contentColor: '#000000',
      mediumColor: '#D1D1D1',
      dialogBackgroundColor: '#FFFFFF',
      dialogBorderColor: '#0C395E',
    ),
  ),
);

All color fields are optional. Override only the colors you need.

Color property	Description
primaryColor	Main color for buttons and highlights.
secondaryColor	Secondary color for complementary elements.
backgroundColor	Screen background color.
contentColor	Color used for texts and icons.
mediumColor	Neutral color for elements like progress bars.
dialogBackgroundColor	Dialog and popup background color.
dialogBorderColor	Dialog and popup border color.

---

Language

Android

The language follows the device locale with no extra configuration.

iOS

Configure Localizations and CFBundleLocalizations in Xcode:

• Adding support for languages and regions
• CFBundleLocalizations

After these settings, the SDK uses the device language.

---

Code obfuscation

Add the following ProGuard/R8 rules to android/app/proguard-rules.pro so the SDK and its dependencies keep working after obfuscation.

proguard-rules.pro

# Flutter ProGuard/R8 rules for Caf SDK
# These rules ensure the CAF SDK plugin works correctly in release builds

# The Android pre-handler for exceptions is loaded reflectively (via ServiceLoader).
-keep class kotlinx.coroutines.experimental.android.AndroidExceptionPreHandler { *; }

### GSON ##################################################################
-keepattributes Signature
-keepattributes *Annotation*
### END GSON ##################################################################

### Retrofit ##################################################################
-keepattributes Signature, InnerClasses, EnclosingMethod
-keepattributes RuntimeVisibleAnnotations, RuntimeVisibleParameterAnnotations
-keepattributes AnnotationDefault
-keepclassmembers,allowshrinking,allowobfuscation interface * {
    @retrofit2.http.* <methods>;
}
-dontwarn org.codehaus.mojo.animal_sniffer.IgnoreJRERequirement
-dontwarn javax.annotation.**
-dontwarn kotlin.Unit
-dontwarn retrofit2.KotlinExtensions
-dontwarn retrofit2.KotlinExtensions$*
-if interface * { @retrofit2.http.* <methods>; }
-keep,allowobfuscation interface <1>
-if interface * { @retrofit2.http.* <methods>; }
-keep,allowobfuscation interface * extends <1>
-keep,allowobfuscation,allowshrinking class kotlin.coroutines.Continuation
-if interface * { @retrofit2.http.* public *** *(...); }
-keep,allowoptimization,allowshrinking,allowobfuscation class <3>
-keep,allowobfuscation,allowshrinking class retrofit2.Response
### END Retrofit ##############################################################

### OkHttp ####################################################################
-dontwarn javax.annotation.**
-adaptresourcefilenames okhttp3/internal/publicsuffix/PublicSuffixDatabase.gz
-dontwarn org.codehaus.mojo.animal_sniffer.*
-dontwarn okhttp3.internal.platform.**
-dontwarn org.conscrypt.**
-dontwarn org.bouncycastle.**
-dontwarn org.openjsse.**
-keep class okhttp3.** { *; }
-dontwarn okhttp3.**
-keep class okio.** { *; }
-dontwarn okio.**
-dontwarn javax.annotation.Nullable
-dontwarn javax.annotation.ParametersAreNonnullByDefault
### END OkHttp ################################################################

### Kotlin Serialization ######################################################
-if @kotlinx.serialization.Serializable class **
-keepclassmembers class <1> {
    static <1>$Companion Companion;
}
-if @kotlinx.serialization.Serializable class ** {
    static **$* *;
}
-keepclassmembers class <2>$<3> {
    kotlinx.serialization.KSerializer serializer(...);
}
-if @kotlinx.serialization.Serializable class ** {
    public static ** INSTANCE;
}
-keepclassmembers class <1> {
    public static <1> INSTANCE;
    kotlinx.serialization.KSerializer serializer(...);
}
-keepclassmembers class kotlinx.serialization.json.** {
    *** Companion;
}
-keepclasseswithmembers class kotlinx.serialization.json.** {
    kotlinx.serialization.KSerializer serializer(...);
}
-keepclassmembers @kotlinx.serialization.Serializable class packeage.** {
    *** Companion;
    *** INSTANCE;
    kotlinx.serialization.KSerializer serializer(...);
}
### END Kotlin Serialization #################################################

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

### Flutter Plugin ###########################################################
-keep class io.flutter.plugins.** { *; }
-keep class * extends io.flutter.plugin.common.MethodChannel$MethodCallHandler { *; }
-keep class * extends io.flutter.plugin.common.MethodChannel$Result { *; }
-keep class io.flutter.plugins.GeneratedPluginRegistrant { *; }
-keep class io.caf.sdk.flutter.** { *; }
### END Flutter Plugin #######################################################

### CAF - Combate a Fraude ######################################################
-keepattributes Exceptions
-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.** { *; }
-dontwarn java.nio.file.*
-dontwarn com.squareup.okhttp.internal.Platform
-keepclassmembers class * extends com.google.crypto.tink.shaded.protobuf.GeneratedMessageLite {
  <fields>;
}
-keep class org.tensorflow.** { *; }
-keep class org.tensorflow.**$* { *; }
-dontwarn org.tensorflow.**
-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.**
-dontwarn java.util.concurrent.Flow*
-keep class kotlin.** { *; }
-keep class kotlinx.** { *; }
-keep class br.com.fortface.** { *; }
-keep interface br.com.fortface.** { *; }
-keepclassmembers class br.com.fortface.** { *; }
-keepclassmembers class br.com.fortface.**$* { *; }
-keep class org.json.** { *; }
-keepclassmembers class org.json.** { *; }
-keepclassmembers class * {
    @org.json.** *;
}
-dontwarn br.com.fortface.**
-dontwarn com.android.tools.lint.**
-dontwarn io.caf.sdk.common.jvmshared.lint.**
### END CAF - Combate a Fraude ##################################################

---

Next steps

Face LivenessDocument Detector