Integrating Mobile SDK for Android

📘 Overview

  • Library Name: IntellicheckSDK
  • Latest Version: 1.0.0
  • Distribution Format: AAR (Android Archive)
  • Purpose: Enables scanning and verification of identity documents including driver's licenses, passport cards, and passport booklets with barcode and RFID reading capabilities

📋 Requirements

  • Minimum Android SDK: 31 (Android 12)
  • Target SDK Version: 35
  • Camera: A device with a high-quality camera capable of scanning PDF417 barcodes.
  • NFC reader: A device with NFC reader capability for passport booklet RFID scanning (not required for driver licenses, passport cards, or other document types).

🚀 Integration Steps

1. Obtain the SDK

To receive the SDK archive, contact our support team and request the file named:

  • IntellicheckSDK.aar

2. Add the SDK to Your Project

2.1 Copy AAR File

  1. Create a folder named libs inside your app module directory.
  2. Copy IntellicheckSDK.aar into the libs folder.
your-app-project/
├── app/
│   ├── libs/
│   │   └── IntellicheckSDK.aar
│   ├── src/
│   └── build.gradle
├── gradle/
└── build.gradle

2.2 Configure Gradle

📘

Language Note: Code examples use Kotlin. While the SDK works with Java projects, we recommend Kotlin for the best integration experience due to named parameters and default values.

In your app-level build.gradle (or build.gradle.kts):

repositories {
    flatDir {
        dirs("libs")
    }
}

dependencies {
    implementation(name = "IntellicheckSDK", ext = "aar")
}

After making changes:

  1. Click Sync Now in Android Studio.
  2. Rebuild your project to verify integration.
👍

Sync your Gradle files to complete the integration.

2.3 Configure Android Manifest

Add the required permissions to your AndroidManifest.xml.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.yourcompany.yourapp">

    <!-- Required SDK Permissions -->
    <uses-permission android:name="android.permission.CAMERA"/>
    <uses-permission android:name="android.permission.NFC"/>
    <uses-permission android:name="android.permission.INTERNET"/>

    <!-- Optional: Declare NFC feature as required or not -->
    <uses-feature
        android:name="android.hardware.nfc"
        android:required="false"/>
    
    <application>
        <!-- Your application content -->
        
        <!-- SDK Activity (register if not auto-merged) -->
        <activity
            android:name="intellicheck.sdk.presentation.IntellicheckActivity"
            android:exported="false"
            android:screenOrientation="portrait"/>
    </application>
</manifest>

Request Runtime Permissions

For Android 6.0 (API 23) and higher, request camera and NFC permissions at runtime.

// Check and request camera permission
if (ContextCompat.checkSelfPermission(this, Manifest.permission.CAMERA)
    != PackageManager.PERMISSION_GRANTED) {
    ActivityCompat.requestPermissions(
        this,
        arrayOf(Manifest.permission.CAMERA),
        CAMERA_PERMISSION_REQUEST_CODE
    )
}

// Handle permission result
override fun onRequestPermissionsResult(
    requestCode: Int,
    permissions: Array,
    grantResults: IntArray
) {
    when (requestCode) {
        CAMERA_PERMISSION_REQUEST_CODE -> {
            if (grantResults.isNotEmpty() && 
                grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                // Permission granted, launch SDK
            } else {
                // Permission denied, show explanation
            }
        }
    }
}

🧪 Usage Examples

Basic Usage

Use the default configuration for quick SDK initialization.

import intellicheck.sdk.presentation.IntellicheckActivity
import intellicheck.sdk.data.ConfigurationSettings
import android.content.Intent
import androidx.activity.result.contract.ActivityResultContracts

class MainActivity : AppCompatActivity() {
    
    // Register Activity Result Launcher
    private val sdkLauncher = registerForActivityResult(
        ActivityResultContracts.StartActivityForResult()
    ) { result ->
        if (result.resultCode == Activity.RESULT_OK) {
            val data = result.data
            val transactionId = data?.getStringExtra(
                IntellicheckActivity.RESULT_TRANSACTION_ID
            )
            
            // Process transaction ID
            transactionId?.let {
                processTransaction(it)
            }
        } else {
            // Handle cancellation or error
            handleScanCancelled()
        }
    }
    
    private fun launchSDK() {
        // Create configuration with your customer ID
        val config = ConfigurationSettings(
            serverCustomerId = YOUR_CUSTOMER_ID
        )
        
        // Create intent and add configuration
        val intent = Intent(this, IntellicheckActivity::class.java).apply {
            putExtras(
                ConfigurationSettings.createConfigurationSettingsBundle(config)
            )
        }
        
        // Launch SDK
        sdkLauncher.launch(intent)
    }
    
    private fun processTransaction(transactionId: String) {
        // TODO: Send transaction ID to your backend for verification
    }
    
    private fun handleScanCancelled() {
        // TODO: Handle user cancellation
    }
}

Advanced Usage with Configuration

Customize the SDK appearance and behavior.

val config = ConfigurationSettings(
    // Required
    serverCustomerId = 12345,
    
    // Theme Customization
    primaryColor = Color.Blue.toArgb(),
    backgroundColor = Color.White.toArgb(),
    mainFontColor = Color.Black.toArgb(),
    buttonFontColor = Color.White.toArgb(),
    buttonOutline = Color.Gray.toArgb(),
    buttonCornerRadius = 12,
    
    // Flow Customization
    showEverythingIsDoneScreen = true,
    showScanningIsDoneScreen = true
)

val intent = Intent(this, IntellicheckActivity::class.java).apply {
    putExtras(ConfigurationSettings.createConfigurationSettingsBundle(config))
}

sdkLauncher.launch(intent)

⚙️ Configuration Options

The ConfigurationSettings class accepts these parameters.

ParameterTypeDefaultDescription
serverCustomerIdInt?RequiredYour customer ID for backend authentication
Theme Customization
primaryColorIntSDK defaultARGB color for primary UI elements
backgroundColorIntSDK defaultARGB color for screen backgrounds
mainFontColorIntSDK defaultARGB color for main text
buttonFontColorIntSDK defaultARGB color for button text
buttonOutlineIntSDK defaultARGB color for button borders
dialogColorIntSDK defaultARGB color for dialog backgrounds
buttonCornerRadiusInt20Corner radius for buttons (0–100)
Font Customization
descriptionFontFontTypeSansRegularFont for description text
buttonFontFontTypeSansRegularFont for button text
descriptionBoldFontFontTypeInterBoldFont for bold description text
Branding
organizationLogoIntSDK defaultDrawable resource ID for custom logo on start screen
Flow Customization
showEverythingIsDoneScreenBooleantrueDisplay final completion screen after all scans
showScanningIsDoneScreenBooleantrueDisplay intermediate scan completion screens
faceCheckStateBooleanfalseEnable facial verification (if supported)
darkModeStateBooleanfalseEnable dark mode theme
scanOnlyBarcodeBooleanfalseSkip front/back image capture for driver licenses (barcode only)
openOnStartDocumentType?nullPre-select document type on launch to skip selection screen. Values: DrivingLicence, PassportCard, IdentityCard
Advanced Options
sendDataToServerBooleantrueSet to false for production apps (SDK returns scanned data to your app for backend processing). Set to true only for internal SDK testing (SDK sends data directly to Intellicheck).

Color Value Examples

// Using predefined colors
primaryColor = Color.Blue.toArgb()

// Using hex colors
primaryColor = Color.parseColor("#1976D2").toArgb()

// Using ARGB
primaryColor = Color.argb(255, 25, 118, 210)

Handling Results

The SDK returns results via Intent extras in the activity result callback.

Available Result Keys

ConstantTypeDescription
RESULT_TRANSACTION_IDStringTransaction identifier for backend verification
RESULT_BARCODEStringBase64-encoded barcode data
RESULT_FRONT_IMAGEStringURI string for document front image
RESULT_BACK_IMAGEStringURI string for document back image
RESULT_RFIDStringBase64-encoded RFID data (passport booklets)
RESULT_PASSPORT_CARD_FRONT_URIStringURI for passport card front image
RESULT_PASSPORT_CARD_BACK_URIStringURI for passport card back image

Complete Result Handling Example

private val sdkLauncher = registerForActivityResult(
    ActivityResultContracts.StartActivityForResult()
) { result ->
    when (result.resultCode) {
        Activity.RESULT_OK -> {
            val data = result.data
            
            // Transaction ID (always present on success)
            val transactionId = data?.getStringExtra(
                IntellicheckActivity.RESULT_TRANSACTION_ID
            )
            
            // Barcode data (driver licenses)
            val barcode = data?.getStringExtra(
                IntellicheckActivity.RESULT_BARCODE
            )
            
            // Document images
            val frontImageUri = data?.getStringExtra(
                IntellicheckActivity.RESULT_FRONT_IMAGE
            )?.let { Uri.parse(it) }
            
            val backImageUri = data?.getStringExtra(
                IntellicheckActivity.RESULT_BACK_IMAGE
            )?.let { Uri.parse(it) }
            
            // RFID data (passport booklets)
            val rfidData = data?.getStringExtra(
                IntellicheckActivity.RESULT_RFID
            )
            
            // Process results
            handleSuccessfulScan(
                transactionId = transactionId,
                barcode = barcode,
                frontImage = frontImageUri,
                backImage = backImageUri,
                rfidData = rfidData
            )
        }
        
        Activity.RESULT_CANCELED -> {
            // User cancelled the scan
            handleUserCancellation()
        }
        
        else -> {
            // Error occurred
            handleScanError(result.resultCode)
        }
    }
}

private fun handleSuccessfulScan(
    transactionId: String?,
    barcode: String?,
    frontImage: Uri?,
    backImage: Uri?,
    rfidData: String?
) {
    transactionId?.let { txId ->
        // Send to your backend for verification
        verifyTransaction(txId)
    }
    
    // Store images if needed
    frontImage?.let { saveOrDisplayImage(it) }
    
    // Process RFID data if present
    rfidData?.let { processPassportRFID(it) }
}

Important Notes

UI and Permissions

  • Self-Contained UI: The SDK provides a complete scanning interface; no custom UI implementation needed.
  • Runtime Permissions: Host app is responsible for requesting camera and NFC permissions before launching the SDK.
  • Portrait Mode: SDK always runs in portrait orientation.
  • NFC Requirement: NFC hardware is required only for passport booklet scanning with RFID reading.

Troubleshooting

SDK Activity Not Found

Error: ActivityNotFoundException: Unable to find explicit activity class.

Solution:

  • Verify IntellicheckActivity is registered in your AndroidManifest.xml.
  • Check that the SDK AAR is properly included in your build.
  • Perform a clean rebuild: Build > Clean Project then Build > Rebuild Project.

Camera Permission Denied

Error: SDK fails to launch or shows permission error.

Solution:

  • Request camera permission before launching SDK.
  • Check AndroidManifest.xml includes <uses-permission android:name="android.permission.CAMERA"/>.
  • For Android 13+, ensure you're requesting the correct runtime permission

NFC Not Available

Error: Passport scanning fails on devices without NFC.

Solution:

Check NFC availability before allowing passport scanning.

  val nfcAdapter = NfcAdapter.getDefaultAdapter(context)
  if (nfcAdapter == null) {
      // Device doesn't support NFC - disable passport booklet scanning
  }

Gradle Sync Failed

Error: Could not find IntellicheckSDK.aar.

Solution:

  • Verify AAR file is in app/libs/ directory.
  • Check flatDir configuration in build.gradle.
  • Try File > Invalidate Caches / Restart.

Minimum SDK Version Error

Error: Manifest merger failed: uses-sdk:minSdkVersion 26 cannot be smaller than version 31.

Solution:

The SDK requires minimum SDK 31. Update your build.gradle.

defaultConfig {
    minSdk = 31
    targetSdk = 35
}

❓ Need Help?

If you encounter issues or have questions, open a support request and ask for help from our solutions engineering team.