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
- Create a folder named
libsinside your app module directory. - Copy
IntellicheckSDK.aarinto thelibsfolder.
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:
- Click Sync Now in Android Studio.
- 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.
| Parameter | Type | Default | Description |
|---|---|---|---|
serverCustomerId | Int? | Required | Your customer ID for backend authentication |
| Theme Customization | |||
primaryColor | Int | SDK default | ARGB color for primary UI elements |
backgroundColor | Int | SDK default | ARGB color for screen backgrounds |
mainFontColor | Int | SDK default | ARGB color for main text |
buttonFontColor | Int | SDK default | ARGB color for button text |
buttonOutline | Int | SDK default | ARGB color for button borders |
dialogColor | Int | SDK default | ARGB color for dialog backgrounds |
buttonCornerRadius | Int | 20 | Corner radius for buttons (0–100) |
| Font Customization | |||
descriptionFont | FontType | SansRegular | Font for description text |
buttonFont | FontType | SansRegular | Font for button text |
descriptionBoldFont | FontType | InterBold | Font for bold description text |
| Branding | |||
organizationLogo | Int | SDK default | Drawable resource ID for custom logo on start screen |
| Flow Customization | |||
showEverythingIsDoneScreen | Boolean | true | Display final completion screen after all scans |
showScanningIsDoneScreen | Boolean | true | Display intermediate scan completion screens |
faceCheckState | Boolean | false | Enable facial verification (if supported) |
darkModeState | Boolean | false | Enable dark mode theme |
scanOnlyBarcode | Boolean | false | Skip front/back image capture for driver licenses (barcode only) |
openOnStart | DocumentType? | null | Pre-select document type on launch to skip selection screen. Values: DrivingLicence, PassportCard, IdentityCard |
| Advanced Options | |||
sendDataToServer | Boolean | true | Set 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
| Constant | Type | Description |
|---|---|---|
RESULT_TRANSACTION_ID | String | Transaction identifier for backend verification |
RESULT_BARCODE | String | Base64-encoded barcode data |
RESULT_FRONT_IMAGE | String | URI string for document front image |
RESULT_BACK_IMAGE | String | URI string for document back image |
RESULT_RFID | String | Base64-encoded RFID data (passport booklets) |
RESULT_PASSPORT_CARD_FRONT_URI | String | URI for passport card front image |
RESULT_PASSPORT_CARD_BACK_URI | String | URI 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
IntellicheckActivityis registered in yourAndroidManifest.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.xmlincludes<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
flatDirconfiguration inbuild.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.
Updated about 13 hours ago
