android

Installation Guide

Install and configure Certta for Android. Learn SDK requirements, permissions, repositories, dependencies, session setup, runtime token updates, and color theming.

This guide covers version 7.14.0 and above. For versions below 7.14.0, please see the legacy documentation.

Installing the SDK for Android

This guide will walk you through the complete setup process required to successfully download, configure, and install the SDK on your machine

Requirements

Before integrating, ensure your environment meets the minimum requirements for the Certta SDK:

Requirement

Version

Min SDK Version (minSdk)

Android Compile version (compileSDK)

Min Kotlin version

1.9.10

Gradle version

8.4

Android Gradle Plugin (AGP)

8.3.2

Permissions

To enable the required network and camera functionality for the Certta SDK, you must declare the appropriate permissions and hardware features in your project's AndroidManifest.xml file.

Add the following lines within your <manifest> tag:

AndroidManifest.xml

<uses-feature android:name="android.hardware.camera" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />

AndroidManifest.xml

<uses-feature android:name="android.hardware.camera" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>

The Document Detector requires READ_EXTERNAL_STORAGE permission when document upload is enabled.

Adding repositories

To download the Certta SDK, you must tell your Android project where to find its dependencies. You do this by configuring the dependencyResolutionManagement block located in your project's root settings.gradle.kts file.

Add the required repository URLs to your configuration:

For Groovy-based projects, include the following repositories in the settings.gradle file.

settings.gradle.kts

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        maven { url = uri("https://repo.combateafraude.com/android/release") }        
    }
}

settings.gradle

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        maven { url "https://repo.combateafraude.com/android/release" }
    }
}

Adding dependencies

To integrate the Certta SDK into your app, add the required dependencies to your module-level (app-level) build.gradle.kts file.

Place the following line within your dependencies block:

build.gradle.kts

dependencies {
    // Manages versions for all dependencies
    implementation(platform("io.caf.sdk:caf-sdk-bom:7.13.0"))
    
    // --- Document Detector (Choose one) ---
    implementation("io.caf.sdk:document-detector-ui") // Adds customizable UI screens
    // implementation("io.caf.sdk:document-detector") // Core only (build your own UI)

    // --- Face Liveness (Choose one) ---
    implementation("io.caf.sdk:caffaceliveness-ui") // Adds customizable UI screens
    // implementation("io.caf.sdk:caffaceliveness") // Core only (build your own UI)

    // --- Liveness Providers ---
    implementation("io.caf.sdk:caffaceliveness-providers-iproov-lite")
    implementation("io.caf.sdk:caffaceliveness-providers-payface")
    implementation("io.caf.sdk:caffaceliveness-providers-facetec")
    
    // --- Fingerprint ---
    implementation("io.caf.sdk:fingerprint")
}

build.gradle

dependencies {
    // Manages versions for all dependencies
    implementation platform("io.caf.sdk:caf-sdk-bom:7.13.0")
    
    // --- Document Detector (Choose one) ---
    implementation "io.caf.sdk:document-detector-ui" // Adds customizable UI screens
    // implementation "io.caf.sdk:document-detector" // Core only (build your own UI)

    // --- Face Liveness (Choose one) ---
    implementation "io.caf.sdk:caffaceliveness-ui" // Adds customizable UI screens
    // implementation "io.caf.sdk:caffaceliveness" // Core only (build your own UI)

    // --- Liveness Providers ---
    implementation "io.caf.sdk:caffaceliveness-providers-iproov-lite"
    implementation "io.caf.sdk:caffaceliveness-providers-payface"
    implementation "io.caf.sdk:caffaceliveness-providers-facetec"
    
     // --- Fingerprint ---
    implementation "io.caf.sdk:fingerprint"
}

When using the caffaceliveness module, you must include at least one liveness provider dependency (such as iproov-lite, payface, or facetec) in your build.gradle file.

Configuration and Customizations

Obtaining the Mobile Token

To generate your mobile token, follow this guide:

Authentication

Configuring the session

Once you have obtained your mobile token, initialize the Certta SDK inside your custom Application class. This should be done within the onCreate() method using the application context and your configuration object.

Here is an example of what your Application class might look like:

Both the userId and mobileToken are optional during the initial configuration. Furthermore, these values are not permanent; you can update or change them at any time during the application lifecycle as your requirements evolve.

MyApplication.kt

val config = CerttaConfiguration(
    userId = "user-id",
    mobileToken = "your-jwt",
    environment = CerttaEnvironment.PROD,
    securityEnabled = true,
)

Certta.instance.configure(
    context = this,
    config = config
)

MyApplication.java

CerttaConfiguration config = new CerttaConfiguration(
   "your-jwt",     // mobileToken
   "user-id",      // userId
   CerttaEnvironment.PROD, //environment
   true,            // securityEnabled
);

Certta.getInstance().configure(this, config);

CerttaConfiguration Parameters

Parameter

Type

Description

mobileToken

String

Your generated JSON Web Token (JWT).

userId

String

A unique identifier for the user.

securityEnabled

Boolean

Enables or disables security validations.

environment

CerttaEnvironment

Defines the execution environment.

Runtime Configuration Updates

The userId and mobileToken are not restricted to the initial setup; they can be updated dynamically at runtime to accommodate changes in user sessions or security requirements.

These methods can be called from any Activity or Fragment after the initial configuration has been established in your Application class.

To update these values, use the specific methods provided by the Certta instance:

MyActivity.kt

Certta.instance.updateUserId("new-user-id")
Certta.instance.updateMobileToken("new-jwt-token")

MyActivity.java

Certta.getInstance().updateUserId("new-user-id");
Certta.getInstance().updateMobileToken("new-jwt-token");

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

Color theming

Both the Liveness and Document Detector modules support custom color theming, allowing you to seamlessly match the SDK's interface to your application's brand guidelines. You can personalize the UI by providing color values in a standard hexadecimal string format (e.g., "#RRGGBB").

After configuring the SDK, create a CerttaColorConfiguration object with the colors you want to change, and pass it to Certta.instance.setColorConfiguration().

val colorConfig = CerttaColorConfiguration(
    primaryColor = "#FF0000",
    secondaryColor = "#00FF00",
    backgroundColor = "#FFFFFF",
    contentColor = "#000000",
    mediumColor = "#D1D1D1",
    dialogBackgroundColor = "#FFFFFF",
    dialogBorderColor = "#0C395E",
)
Certta.instance.setColorConfiguration(colorConfig)

CafColorConfiguration colorConfig = new CafColorConfiguration(
      "#FF0000", //primaryColor
      "#00FF00", //secondaryColor
      "#FFFFFF", //backgroundColor
      "#000000", //contentColor
      "#D1D1D1", //mediumColor,
      "#FFFFFF", //dialogBackgroundColor
      "#0C395E" //dialogBorderColor
);
Certta.getInstance().setColorConfiguration(colorConfig);

ColorConfiguration Parameters

All parameters in the configuration object are optional. You only need to define the specific colors you wish to override for your custom theme.

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.

Code Obsfuscation

Check out the code block with the ProGuard/R8 rules necessary for SDK and its dependencies to function correctly even after code obfuscation and optimization. These rules preserve essential information (such as signatures, annotations, and internal classes) and prevent critical classes from being removed or altered.

proguard_rules.txt

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

### GSON ##################################################################
# Gson uses generic type information stored in a class file when working with fields.
# ProGuard removes such information by default, so configure it to keep all of it.
-keepattributes Signature
# For using GSON @Expose annotation
-keepattributes *Annotation*
### END GSON ##################################################################

### Retrofit ##################################################################
# Preserve generic signatures, inner classes, and enclosing methods for Retrofit reflection.
-keepattributes Signature, InnerClasses, EnclosingMethod
# Retain runtime-visible annotations on methods and parameters.
-keepattributes RuntimeVisibleAnnotations, RuntimeVisibleParameterAnnotations
# Keep annotation default values.
-keepattributes AnnotationDefault
# Retain service method parameters for interfaces with Retrofit annotations.
-keepclassmembers,allowshrinking,allowobfuscation interface * {
    @retrofit2.http.* <methods>;
}
# Suppress warnings for build tooling and certain JSR 305 annotations.
-dontwarn org.codehaus.mojo.animal_sniffer.IgnoreJRERequirement
-dontwarn javax.annotation.**
-dontwarn kotlin.Unit
-dontwarn retrofit2.KotlinExtensions
-dontwarn retrofit2.KotlinExtensions$*
# Explicitly keep Retrofit interfaces to prevent nullification by R8.
-if interface * { @retrofit2.http.* <methods>; }
-keep,allowobfuscation interface <1>
-if interface * { @retrofit2.http.* <methods>; }
-keep,allowobfuscation interface * extends <1>
# Preserve continuations used by Kotlin suspend functions.
-keep,allowobfuscation,allowshrinking class kotlin.coroutines.Continuation
# For R8 full mode: keep generic return types for Retrofit methods.
-if interface * { @retrofit2.http.* public *** *(...); }
-keep,allowoptimization,allowshrinking,allowobfuscation class <3>
# Preserve Retrofit Response class.
-keep,allowobfuscation,allowshrinking class retrofit2.Response
### END Retrofit ##############################################################

### OkHttp ####################################################################
# Suppress warnings for JSR 305 annotations.
-dontwarn javax.annotation.**
# Adapt resource filenames for internal public suffix database.
-adaptresourcefilenames okhttp3/internal/publicsuffix/PublicSuffixDatabase.gz
# Suppress warnings for Animal Sniffer and platform-specific classes.
-dontwarn org.codehaus.mojo.animal_sniffer.*
-dontwarn okhttp3.internal.platform.**
-dontwarn org.conscrypt.**
-dontwarn org.bouncycastle.**
-dontwarn org.openjsse.**
# Keep all OkHttp and Okio classes.
-keep class okhttp3.** { *; }
-dontwarn okhttp3.**
-keep class okio.** { *; }
-dontwarn okio.**
-dontwarn javax.annotation.Nullable
-dontwarn javax.annotation.ParametersAreNonnullByDefault
### END OkHttp ################################################################

### Kotlin Serialization ######################################################
# Keep Companion objects for serializable classes.
-if @kotlinx.serialization.Serializable class **
-keepclassmembers class <1> {
    static <1>$Companion Companion;
}
# Keep serializer functions on companion objects.
-if @kotlinx.serialization.Serializable class ** {
    static **$* *;
}
-keepclassmembers class <2>$<3> {
    kotlinx.serialization.KSerializer serializer(...);
}
# Retain INSTANCE and serializer for serializable objects.
-if @kotlinx.serialization.Serializable class ** {
    public static ** INSTANCE;
}
-keepclassmembers class <1> {
    public static <1> INSTANCE;
    kotlinx.serialization.KSerializer serializer(...);
}
# Preserve Companion objects in kotlinx.serialization.json.
-keepclassmembers class kotlinx.serialization.json.** {
    *** Companion;
}
-keepclasseswithmembers class kotlinx.serialization.json.** {
    kotlinx.serialization.KSerializer serializer(...);
}
# Preserve serializer lookup for serializable classes (adjust package name as needed).
-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 ############################################################

### CAF - Combate a Fraude ######################################################
# Keep exceptions attributes.
-keepattributes Exceptions
# Preserve all classes, interfaces, and class members for CAF modules.
-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.** { *; }
# Suppress warnings for java.nio.file and certain OkHttp internal classes.
-dontwarn java.nio.file.*
-dontwarn com.squareup.okhttp.internal.Platform
# Keep fields in classes extending GeneratedMessageLite (for Tink usage).
-keepclassmembers class * extends com.google.crypto.tink.shaded.protobuf.GeneratedMessageLite {
  <fields>;
}
# Preserve TensorFlow classes.
-keep class org.tensorflow.** { *; }
-keep class org.tensorflow.**$* { *; }
-dontwarn org.tensorflow.**
# Preserve IProov classes and Protobuf classes.
-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.**
# Suppress warnings for concurrent Flow classes.
-dontwarn java.util.concurrent.Flow*
# Preserve Kotlin and kotlinx classes.
-keep class kotlin.** { *; }
-keep class kotlinx.** { *; }
-dontwarn com.android.tools.lint.**
-dontwarn io.caf.sdk.common.jvmshared.lint.**
### END CAF - Combate a Fraude ##################################################

Last updated 1 month ago