> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/caf-sdk/android/installation-guide.md).

# Installation Guide

{% hint style="warning" %}
This guide covers version 7.14.0 and above. For versions below 7.14.0, please see the [legacy documentation](https://docs.caf.io/caf-sdk/android/getting-started-with-the-sdk-1).
{% endhint %}

## Installing the SDK for Android <a href="#requirements-for-adding" id="requirements-for-adding"></a>

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

### Requirements <a href="#requirements-for-adding" id="requirements-for-adding"></a>

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

| Requirement                          | Version |
| ------------------------------------ | ------- |
| Min SDK Version (minSdk)             | 26      |
| Android Compile version (compileSDK) | 36      |
| 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:

{% tabs %}
{% tab title="Liveness" %}
{% code title="AndroidManifest.xml" expandable="true" %}

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

{% endcode %}
{% endtab %}

{% tab title="Document Detector" %}
{% code title="AndroidManifest.xml" expandable="true" %}

```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"/>
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="info" %}
The Document Detector requires `READ_EXTERNAL_STORAGE` permission when document upload is enabled.
{% endhint %}

### 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:

{% hint style="info" %}
For Groovy-based projects, include the following repositories in the `settings.gradle` file.
{% endhint %}

{% tabs %}
{% tab title="Kotlin Script" %}
{% code title="settings.gradle.kts" expandable="true" %}

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

{% endcode %}
{% endtab %}

{% tab title="Groovy" %}
{% code title="settings.gradle" expandable="true" %}

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

{% endcode %}
{% endtab %}
{% endtabs %}

### 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:

{% tabs %}
{% tab title="Kotlin Script" %}
{% code title="build.gradle.kts" expandable="true" %}

```kts
dependencies {
    // Manages versions for all dependencies
    implementation(platform("io.caf.sdk:caf-sdk-bom:7.19.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")
}
```

{% endcode %}
{% endtab %}

{% tab title="Groovy" %}
{% code title="build.gradle" expandable="true" %}

```groovy
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"
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="warning" %}
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.
{% endhint %}

## Configuration and Customizations

#### Obtaining the Mobile Token

To generate your mobile token, follow this guide:

{% content-ref url="/pages/9JinhiBRarpeMNxbUECl" %}
[Authentication](/caf-sdk/authentication.md)
{% endcontent-ref %}

### 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:

{% hint style="info" %}
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.
{% endhint %}

{% tabs %}
{% tab title="Kotlin" %}
{% code title="MyApplication.kt" overflow="wrap" expandable="true" %}

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

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

{% endcode %}
{% endtab %}

{% tab title="Java" %}
{% code title="MyApplication.java" overflow="wrap" expandable="true" %}

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

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

{% endcode %}
{% endtab %}
{% endtabs %}

#### CerttaConfiguration Parameters

<table><thead><tr><th width="214.10546875">Parameter</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>mobileToken</code></td><td><code>String</code></td><td>Your generated JSON Web Token (JWT).</td></tr><tr><td><code>userId</code></td><td><code>String</code></td><td>A unique identifier for the user.</td></tr><tr><td><code>securityEnabled</code></td><td><code>Boolean</code></td><td>Enables or disables security validations.</td></tr><tr><td><code>environment</code></td><td><code>CerttaEnvironment</code></td><td>Defines the execution environment.</td></tr></tbody></table>

#### 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.

{% hint style="success" %}
These methods can be called from any Activity or Fragment after the initial configuration has been established in your `Application` class.
{% endhint %}

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

{% tabs %}
{% tab title="Kotlin" %}
{% code title="MyActivity.kt" %}

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

{% endcode %}
{% endtab %}

{% tab title="Java" %}
{% code title="MyActivity.java" overflow="wrap" expandable="true" %}

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

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="warning" %}
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.
{% endhint %}

## 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()`.

{% tabs %}
{% tab title="Kotlin" %}
{% code expandable="true" %}

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

{% endcode %}
{% endtab %}

{% tab title="Java" %}
{% code expandable="true" %}

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

{% endcode %}
{% endtab %}
{% endtabs %}

#### ColorConfiguration Parameters

{% hint style="info" %}
All parameters in the configuration object are optional. You only need to define the specific colors you wish to override for your custom theme.
{% endhint %}

| 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.

{% code title="proguard\_rules.txt" expandable="true" %}

```
# 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 ##################################################
```

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.caf.io/caf-sdk/android/installation-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.