Troubleshooting issues with the Android SDK

This page covers Android-specific integration issues. For a symptom-based overview, start with Common Issues.

License errors

In case of an expired or invalid license, SDK methods raise a LicenseException with an error code explaining the reason. Catch license errors separately so your app can prompt users to update or fall back to another capture method:

try {
    // SDK method call
} catch (e: LicenseException) {
    // Handle expired or invalid license
    // e.errorCode provides details such as expired, invalid, or demo ended
}

If the license key is rejected at startup, verify that it matches the app package name and that it is set before calling SDK APIs. See Configure the License Key.

SDK dependency not resolved

Symptoms

Gradle cannot resolve com.geniusscansdk:gssdk, or the app fails at runtime with missing SDK classes.

Fix

Make sure the Genius Scan SDK Maven repository and dependency are present in the app Gradle configuration:

repositories {
    maven { url 'https://s3.amazonaws.com/tgl.maven' }
}

dependencies {
    implementation 'com.geniusscansdk:gssdk:6.0.0-beta11'
}

If the dependency is present but classes are missing at runtime, clean and rebuild the app, then verify that the dependency is declared in the app module that launches the scan flow.

Minimum SDK below 23

Symptoms

Gradle fails during dependency resolution, manifest merging, or AAR metadata checks.

Fix

Set the app minSdkVersion to 23 or later:

android {
    defaultConfig {
        minSdkVersion 23
    }
}

Native library or ABI issues

Symptoms

The app fails with native library errors, or Gradle reports architecture-related packaging issues.

Fix

If your app uses abiFilters, make sure they only include architectures supported by the SDK and by the rest of your app. If you do not need to restrict architectures, remove the filters and let Gradle package all supported native libraries.

The Android install guide lists the supported architectures and SDK size estimates: Size of the SDK.

APK size is too big

Symptoms

The Android build is significantly larger than the estimates in the install guide.

Fix

Native debug symbols are included as part of the SDK to help with troubleshooting. These symbols increase the size of builds significantly, so they should be removed when compiling release builds.

Gradle can and should do that automatically by running the stripReleaseDebugSymbols task.

If the impact of the SDK on your APK size exceeds our estimates, this task may have failed. Look for one of the following warnings in the build logs:

• Execution failed for task ':app:stripReleaseDebugSymbols'.
• Unable to strip the following libraries: libgssdk-core.so, libgssdk-ocr.so

You may fix such an issue by verifying that:

1. The Android NDK is installed on the machine: Android Studio > Settings > Android SDK > SDK Tools
2. Its version matches the ndkVersion from the android/build.gradle file.

Camera permission is missing in a custom integration

The simple scan flow handles the standard capture flow. If you build a custom camera integration with native UI components, request camera permission before initializing the camera screen or fragment.

Getting further help

If the issue persists, contact support with:

• The SDK version
• The app package name
• The Android Gradle Plugin version and minSdkVersion
• Complete Gradle logs or runtime error messages
• Steps to reproduce the issue