Android

Guide for integrating Kvalifika SDK into a native Android project

Use Kvalifika SDK to easily integrate into a native Android project. Before integrating Kvalifika, it is recommended to follow the steps described in Integration Guide and Initial Setup.

Naming of the properties and functions might be slightly modified depending on the version.

Installation

Add the following to the project's main build.gradle file:

Kotlin
Java
Kotlin
allprojects {
repositories {
// Existing repositories, like google() and jcenter()
maven { url 'https://s3.eu-central-1.amazonaws.com/com.kvalifika.sdk' }
}
}
Java
allprojects {
repositories {
// Existing repositories, like google() and jcenter()
maven { url 'https://s3.eu-central-1.amazonaws.com/com.kvalifika.sdk' }
}
}

Please use minSdkVersion 21 in your build.gradle (Module) file

To install Kvalifika Android SDK, add the following to build.gradle (Module) file:

Kotlin
Java
Kotlin
dependencies {
// Insert line below to include our client library as a dependency.
implementation 'com.kvalifika:sdk:0.5.0'
}
Java
dependencies {
// Insert line below to include our client library as a dependency.
implementation 'com.kvalifika:sdk:0.5.0'
}

Initialize the SDK

import Kvalifika:

import com.kvalifika.sdk.KvalifikaSDK
import com.kvalifika.sdk.KvalifikaSDKLocale
import com.kvalifika.sdk.KvalifikaSDKCallback
import com.kvalifika.sdk.KvalifikaSDKError

After that, you need to initialize SDK with your appId and secretKey

appId is Application ID and secretKey is Application Secret Key, generated from Admin Panel. See Initial Setup for details.

Kotlin
Java
Kotlin
class MainActivity : AppCompatActivity() {
private lateinit var sdk: KvalifikaSDK
private val appId: String = "YOUR APP ID"
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
sdk = KvalifikaSDK.Builder(this, appId)
.locale(KvalifikaSDKLocale.EN)
.build()
}
}
Java
public class MainActivity extends AppCompatActivity {
private KvalifikaSDK sdk;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
String appId = "YOU APP ID";
setContentView(R.layout.activity_main);
sdk = new KvalifikaSDK.Builder(this, appId)
.locale(KvalifikaSDKLocale.EN)
.build();
}
}

Start Verification

Call sdk.startSession() on button click event:

Kotlin
Java
Kotlin
class MainActivity : AppCompatActivity() {
private lateinit var sdk: KvalifikaSDK
private val appId: String = "YOUR APP ID"
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
sdk = KvalifikaSDK.Builder(this, appId)
.locale(KvalifikaSDKLocale.GE)
.build()
}
// Start verification on button click
fun onVerificationPress(view: View?) {
sdk.startSession()
}
}
Java
public class MainActivity extends AppCompatActivity {
private KvalifikaSDK sdk;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
String appId = "YOU APP ID";
setContentView(R.layout.activity_main);
sdk = new KvalifikaSDK.Builder(this, appId)
.locale(KvalifikaSDKLocale.EN)
.build();
}
public void onVerificationPress(View view) {
sdk.startSession();
}
}

Handling Verifications

It's useful to know that whether a user has completed the verification flow or canceled it. For this, you can implement the callback methods.

Callback Methods

Method

Description

onInitialize

This callback method is triggered when SDK is initialized.

onStart

This callback method is triggered when the user starts verification.

onFinish

This callback method is triggered when the user completes verification. Get session data here.

onError

This callback method is triggered on error (see Error Codes for more information)

Kotlin
Java
Kotlin
sdk.callback(object : KvalifikaSDKCallback {
override fun onInitialize() {
Log.d("MainActivity", "initialized")
}
override fun onStart(sessionId: String) {
Log.d("MainActivity", "started")
}
override fun onFinish(sessionId: String) {
// Fetch session data here from your server
}
override fun onError(error: KvalifikaSDKError, message: String?) {
if(error == KvalifikaSDKError.INVALID_APP_ID) {
Log.d("MainActivity", "Invalid App ID")
}
if (error == KvalifikaSDKError.USER_CANCELLED) {
Toast.makeText(applicationContext, "User cancelled", Toast.LENGTH_LONG).show()
}
if (error == KvalifikaSDKError.TIMEOUT) {
Toast.makeText(applicationContext, "Timeout", Toast.LENGTH_LONG).show()
}
if (error == KvalifikaSDKError.SESSION_UNSUCCESSFUL) {
Toast.makeText(applicationContext, "Session failed", Toast.LENGTH_LONG).show()
}
if (error == KvalifikaSDKError.ID_UNSUCCESSFUL) {
Toast.makeText(applicationContext, "ID scan failed", Toast.LENGTH_LONG).show()
}
if (error == KvalifikaSDKError.CAMERA_PERMISSION_DENIED) {
Toast.makeText(applicationContext, "Camera permission denied", Toast.LENGTH_LONG).show()
}
if (error == KvalifikaSDKError.LANDSCAPE_MODE_NOT_ALLOWED) {
Toast.makeText(applicationContext, "Landscape mode is not allowed", Toast.LENGTH_LONG).show()
}
if (error == KvalifikaSDKError.REVERSE_PORTRAIT_NOT_ALLOWED) {
Toast.makeText(applicationContext, "Reverse portrait is not allowed", Toast.LENGTH_LONG).show()
}
if (error == KvalifikaSDKError.FACE_IMAGES_UPLOAD_FAILED) {
Toast.makeText(applicationContext, "Could not upload face images", Toast.LENGTH_LONG).show()
}
if (error == KvalifikaSDKError.DOCUMENT_IMAGES_UPLOAD_FAILED) {
Toast.makeText(applicationContext, "Could not upload Id card or passport images", Toast.LENGTH_LONG).show()
}
if (error == KvalifikaSDKError.COMPARE_IMAGES_FAILED) {
Toast.makeText(applicationContext, "Could not compare images", Toast.LENGTH_LONG).show()
}
if (error == KvalifikaSDKError.UNKNOWN_INTERNAL_ERROR) {
Toast.makeText(applicationContext, "Unknown error happened", Toast.LENGTH_LONG).show()
}
}
})
Java
sdk.callback(new KvalifikaSDKCallback() {
@Override
public void onInitialize() {
Log.d("MainActivity", "initialized");
}
@Override
public void onStart(@NotNull String sessionId) {
Log.d("MainActivity", "started");
}
@Override
public void onFinish(@NotNull String sessionId) {
Log.d("MainActivity", "finished");
}
@Override
public void onError(@NotNull KvalifikaSDKError error, String message) {
if (error == KvalifikaSDKError.INVALID_APP_ID) {
Log.d("MainActivity", "Invalid App ID");
}
if (error == KvalifikaSDKError.USER_CANCELLED) {
Toast.makeText(getApplicationContext(), "User cancelled", Toast.LENGTH_LONG).show();
}
if (error == KvalifikaSDKError.TIMEOUT) {
Toast.makeText(getApplicationContext(), "Timeout", Toast.LENGTH_LONG).show();
}
if (error == KvalifikaSDKError.SESSION_UNSUCCESSFUL) {
Toast.makeText(getApplicationContext(), "Session failed", Toast.LENGTH_LONG).show();
}
if (error == KvalifikaSDKError.ID_UNSUCCESSFUL) {
Toast.makeText(getApplicationContext(), "ID scan failed", Toast.LENGTH_LONG).show();
}
if (error == KvalifikaSDKError.CAMERA_PERMISSION_DENIED) {
Toast.makeText(getApplicationContext(), "Camera permission denied", Toast.LENGTH_LONG).show();
}
if (error == KvalifikaSDKError.LANDSCAPE_MODE_NOT_ALLOWED) {
Toast.makeText(getApplicationContext(), "Landscape mode is not allowed", Toast.LENGTH_LONG).show();
}
if (error == KvalifikaSDKError.REVERSE_PORTRAIT_NOT_ALLOWED) {
Toast.makeText(getApplicationContext(), "Reverse portrait is not allowed", Toast.LENGTH_LONG).show();
}
if (error == KvalifikaSDKError.FACE_IMAGES_UPLOAD_FAILED) {
Toast.makeText(getApplicationContext(), "Could not upload face images", Toast.LENGTH_LONG).show();
}
if (error == KvalifikaSDKError.DOCUMENT_IMAGES_UPLOAD_FAILED) {
Toast.makeText(getApplicationContext(), "Could not upload Id card or passport images", Toast.LENGTH_LONG).show();
}
if (error == KvalifikaSDKError.COMPARE_IMAGES_FAILED) {
Toast.makeText(getApplicationContext(), "Could not compare images", Toast.LENGTH_LONG).show();
}
if (error == KvalifikaSDKError.UNKNOWN_INTERNAL_ERROR) {
Toast.makeText(getApplicationContext(), "Unknown error happened", Toast.LENGTH_LONG).show();
}
}
});

Error Codes

Error Code

Description

INVALID_APP_ID

Kvalifika App Id is incorrect

USER_CANCELLED

User canceled before completing verification.

TIMEOUT

Canceled due to inactivity.

SESSION_UNSUCCESSFUL

The Session was not performed successfully

ID_UNSUCCESSFUL

The ID Scan was not performed successfully and identity document data was not generated.

CAMERA_PERMISSION_DENIED

Camera is required but access is prevented by user settings.

LANDSCAPE_MODE_NOT_ALLOWED

Verification was canceled because the device is in landscape mode.

REVERSE_PORTRAIT_NOT_ALLOWED

Verification was canceled because the device is in reverse portrait mode.

FACE_IMAGES_UPLOAD_FAILED

Could not upload face images. Internal request failed.

DOCUMENT_IMAGES_UPLOAD_FAILED

Could not upload ID card or passport images. Internal request failed.

COMPARE_IMAGES_FAILED

Could not compare images. Internal request failed.

UNKNOWN_INTERNAL_ERROR

Session failed because of an unhandled internal error.

UI Customizations

Appearance

It is possible to customize the logo and icons and provide drawable resources.

Kotlin
Java
Kotlin
sdk = KvalifikaSDK.Builder(this, appId, secretKey)
.locale(KvalifikaSDKLocale.EN)
.logo(R.drawable.logo)
.documentIcon(R.drawable.document_icon)
.activeFlashIcon(R.drawable.flash_on)
.inactiveFlashIcon(R.drawable_flash_off)
.cancelIcon(R.drawable.cancel_icon)
.build()
Java
sdk = KvalifikaSDK.Builder(this, appId, secretKey)
.locale(KvalifikaSDKLocale.EN)
.logo(R.drawable.logo)
.documentIcon(R.drawable.document_icon)
.activeFlashIcon(R.drawable.flash_on)
.inactiveFlashIcon(R.drawable_flash_off)
.cancelIcon(R.drawable.cancel_icon)
.build()

Language

It is possible to set locale when initializing SDK. Supported locales are:

Code

Language

EN

English

GE

Georgian

Kotlin
Java
Kotlin
sdk = KvalifikaSDK.Builder(this, appId, secretKey)
.locale(KvalifikaSDKLocale.EN)
.build()
Java
KvalifikaSDK sdk = new KvalifikaSDK.Builder(this, appId, secretKey)
.locale(KvalifikaSDKLocale.EN)
.build();

ProGuard

If you are using ProGuard in the release build, add the following options:

-keep class com.facetec.sdk.** { *; }