# Getting started: Android (Validations SDK)
{{<sdk-guides-aside>}}
{{<tags>}}

## **Introduction**

The Truora Validations SDK allows you to integrate identity verification features directly into your native mobile applications. The SDK handles the complexity of capturing the user's identity documents, facial recognition, and liveness detection to verify their identity against backend records.

# **Requirements**

## **Platform Requirements**

* **Android:** 5.1 (API Level 21\) or higher  
* The SDK must be launched from an **AppCompatActivity**

## **Permissions Required**

* Camera access (for document and face capture)  
* Internet access (for API communication)

# **Prerequisites & Authentication**

## **The Key Provider Interface**

To prevent hardcoding sensitive logic, you must implement the `TruoraAPIKeyGetter` interface in your code. This allows you to retrieve the API key from a secure location (like a compiled secret, a secure storage enclave, or an obfuscated string). This interface is how the `sdk` will get access to the `api key` for the validations, the api key must be of type `sdk` (temporary), any other key type will result in an error. Below we show three examples of how to implement the interface, but it can work however you want

### Option 1: Encrypted Storage

{{<code2 "{\"java\": \"sdk_android_encrypted_storage_java.java\", \"kotlin\": \"sdk_android_encrypted_storage_kotlin.kt\"}" "Encrypted Storage" >}}

### Option 2: BuildConfig value

In this option we get  the key from a generated class defined in your module's `build.gradle` file.

{{<code2 "{\"java\": \"sdk_android_buildconfig_java.java\", \"kotlin\": \"sdk_android_buildconfig_kotlin.kt\"}" "BuildConfig Value" >}}

### Option 3: Retrieve from a backend

Recommended for production builds these are examples for backend retrieval: 

{{<code2 "{\"java\": \"sdk_android_backend_service_java.java\", \"kotlin\": \"sdk_android_backend_service_kotlin.kt\"}" "Backend Service" >}}

# **Installation**

The Truora SDK is modular and published on Maven. You don’t need to include every module  in your project, only the validation modules that you need. 

For example, if you are just interested in the face validation module add the following to your app-level `build.gradle.kts` (or `build.gradle`):

{{<code lang="kotlin" lang_title="Kotlin">}}
dependencies {    
    // Face Validation Module
    implementation("com.truora:validations.face:1.0.0")
    // Document Validation Module
    implementation("com.truora:validations.document:1.0.0") 

    // Required AndroidX dependencies
    implementation("androidx.appcompat:appcompat:1.6.1")
    implementation("androidx.constraintlayout:constraintlayout:2.1.4")
}
{{</code>}}

## **Android Permissions**

Add the camera permission to your `AndroidManifest.xml`. The SDK requires camera access to capture the selfie.

{{<code lang="xml" lang_title="XML">}}
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.INTERNET" />
{{</code>}}

# **Configuration Options**

Before implementing validations, let's understand the available configuration options.

Using custom validation config and UI config is optional when building the validation:

- If no `uiConfig` is provided then the validation view will show the standard Truora branding, logo and colors  
- If no `validationConfig` is provided then default values will be applied like:  
  - No waiting for validation results before finishing the validation process for the user  
  - `autocapture` of face/doc when it’s detected will be `on`

More indepth information on the validation configuration options, such as similarity threshold, can be found in the official validations api documentation

- [Face validation API](https://dev.truora.com/validators/face_validation_api/)  
- [Document validation API](https://dev.truora.com/validators/document_validation_api/)

## **User ID**

The `userId` parameter is crucial for initializing the Truora SDK. It provides a unique identifier for the user undergoing the validation process.

* Purpose: The `userId` allows Truora to associate validation attempts and reference data (like previously captured reference faces) with a specific user in your system. It is mandatory for linking the validation results to your user base.

* Best Practice: This ID should be an immutable, non-sensitive identifier from your database (e.g., a UUID or internal user ID) that uniquely identifies the person. Do not use sensitive PII like an email address or national ID number as the `userId`.

## **Language**

The `language` parameter allows you to define the localization of the text and instructions displayed within the validation view.

* Customization: By setting the language, you ensure a user-friendly experience by presenting instructions and feedback in the user's preferred language.

* Available Options: The SDK supports several languages. You should provide the language code as a two-letter string (e.g., "es" for Spanish, "en" for English, "pt" for Portuguese). If no language is provided, the SDK will typically default to English or attempt to use the device's system language, though providing an explicit language is recommended.

{{<code2 "{\"java\": \"sdk_android_init_java.java\", \"kotlin\": \"sdk_android_init_kotlin.kt\"}" "Initialization" >}}

## **Face configuration**

To create a face validation you just need to add it when building the validation object `withValidation`, you can just return the validation config inside the lambda function if you do not want to use any custom configuration

To specify that the validation type you want to use is `Face`, then explicitly type the lambda function as accepting a `Face` config validation type

{{<code2 "{\"java\": \"sdk_android_face_config_java.java\", \"kotlin\": \"sdk_android_face_config_kotlin.kt\"}" "Face Configuration" >}}

### Configuration Parameters:

{{<table "table w-auto small m-auto text-center table-striped table-bordered">}}
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| **useAutocapture** | bool | true | Automatically capture when face is properly detected |
| **similarityThreshold** | double | 0.8 | Minimum similarity score required (0.0 - 1.0) |
| **timeout** | int | 60 | Maximum time in seconds for the validation |
| **waitForResults** | bool | false | Wait for API response before closing the view |
| **referenceFace** | ReferenceFace | null | Optional reference image for comparison |
{{</table>}}

## 

## **Document configuration**

To create a face validation you just need to added it when building the validation object `withValidation`, you can just return the validation config inside the lambda function if you do not want to use any custom configuration

To specify that the validation type you want to use is `Document`, then explicitly type the lambda function as accepting a `Document` config validation type

{{<code2 "{\"java\": \"sdk_android_doc_config_java.java\", \"kotlin\": \"sdk_android_doc_config_kotlin.kt\"}" "Document Configuration" >}}

### Configuration Parameters:

{{<table "table w-auto small m-auto text-center table-striped table-bordered">}}
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| **country** | Country | null | Country code for document validation (if not set, user selects) |
| **documentType** | DocumentType | null | Type of document (if not set, user selects) |
| **useAutocapture** | bool | true | Automatically capture when document is detected. **Not supported for passport** — the SDK will throw a `TruoraException` if autocapture is enabled with `DocumentType.PASSPORT` |
| **timeout** | int | 90 | Maximum time in seconds for the validation |
| **waitForResults** | bool | false | Wait for API response before closing the view |
{{</table>}}

### Available Countries and Document Types:

{{<table "table w-auto small m-auto text-center table-striped table-bordered">}}
| Country | Code | Supported Document Types |
| --- | --- | --- |
| Argentina | Country.ar | nationalId |
| Brazil | Country.br | cnh, generalRegistration |
| Chile | Country.cl | nationalId, foreignId, driverLicense, passport |
| Colombia | Country.co | nationalId, foreignId, rut, ppt, passport, identityCard, temporaryNationalId |
| Costa Rica | Country.cr | nationalId, foreignId |
| El Salvador | Country.sv | nationalId, foreignId, passport |
| Mexico | Country.mx | nationalId, foreignId, passport |
| Peru | Country.pe | nationalId, foreignId |
| Venezuela | Country.ve | nationalId |
| All | Country.all | passport |
{{</table>}}

# **Understanding SDK Results**

Before implementing validations, it's important to understand what results you'll receive and how to handle them.

The SDK returns a TruoraValidationResult which can be:

* **completed**: Validation process finished (contains ValidationResult)  
* **canceled:** Validation process canceled by the user (could contain ValidationResult)  
* **error**: SDK error occurred (contains TruoraError)

## **Validation Result Object**

The plugin returns ValidationResult objects with the following structure:

{{<code lang="kotlin" lang_title="Kotlin">}}
data class ValidationResult(
  val id: String?, // Unique ID for this validation
  val status: String?, // Status of the validation
  val type: String?, // Type of the validation
  val detail: ValidationDetailResponse?
)
{{</code>}}

## **Validation Statuses**

{{<table "table w-auto small m-auto text-center table-striped table-bordered">}}
| Status | Description | When it occurs |
| --- | --- | --- |
| **ValidationStatus.success** | Validation passed | User successfully passed the validation |
| **ValidationStatus.failure** | Validation failed | User did not pass the validation criteria |
| **ValidationStatus.pending** | Awaiting processing | Validation is being process |
{{</table>}}

## **TruoraValidationError Types**

When the SDK returns **failed**, the error can be one of three types:

{{<table "table w-auto small m-auto text-center table-striped table-bordered">}}
| Exception Type | Description |
| --- | --- |
| **TruoraValidationError.SDK** | Internal SDK error (configuration, permissions, user actions) |
| **TruoraValidationError.ValidationApi** | Error from the Truora Validation API |
| **TruoraValidationError.Network** | Network connectivity error |
{{</table>}}

Common SDK Error Types (SDKErrorType):

{{<table "table w-auto small m-auto text-center table-striped table-bordered">}}
| Error Type | Code | Description |
| --- | --- | --- |
| **cameraPermissionError** | 20011 | Camera permission was denied |
| **invalidApiKey** | 20017 | API key is invalid or expired |
| **invalidConfiguration** | 20024 | SDK configuration is invalid |
| **networkError** | 20025 | Network connection failed |
| **uploadFailed** | 20026 | Failed to upload captured media |
{{</table>}}

{{<code2 "{\"java\": \"sdk_android_result_handling_java.java\", \"kotlin\": \"sdk_android_result_handling_kotlin.kt\"}" "Result Handling" >}}

# **Implementation**

## **Face Validation**

Here's a complete example of implementing face validation:

{{<code2 "{\"java\": \"sdk_android_face_validation_java.java\", \"kotlin\": \"sdk_android_face_validation_kotlin.kt\"}" "Face Validation" >}}

## **Document Validation**

For document validation, use the DocumentValidationConfig:

{{<code2 "{\"java\": \"sdk_android_doc_validation_java.java\", \"kotlin\": \"sdk_android_doc_validation_kotlin.kt\"}" "Document Validation" >}}


# **Troubleshooting**

Common Issues

1. **Camera not working on Android**  
   Solution: Verify that camera permissions are added to AndroidManifest.xml and that the user has granted permission at runtime.

2. **"API Key Invalid" error**  
   Solution: Verify your API key is correct and has the proper grants (generator or sdk type). Check that it hasn't expired.

3. **Validation timeout**  
   Solution: Increase the timeout value in the config, or ensure the device has a stable internet connection.