Gradle Integration

When you sign for a license of the Incode SDKs, you will receive access to our SDKs through a username-password pair to be able to integrate the Incode SDKs into your project.

Quick Start

In your project-level build.gradle, add the Incode maven repository with provided credentials:

allprojects {
    repositories {
        ...
        maven {
            url "https://repo.incode.com/artifactory/libs-incode-welcome"
            credentials {
                username = "organizationUsername"
                password = "xxxxxxxxxxxxxxxxxxxx"
            }
        }
    }
    ...
}

In your module-level app/build.gradle, add the following code to android{} closure:

compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
}

In your module-level app/build.gradle, add Incode library dependencies:

dependencies {
    ...

    // Incode Welcome SDK
    implementation 'com.incode.sdk:welcome:5.15.0' // Incode Welcome SDK
    implementation 'com.incode.sdk:core-light:2.5.0' // Required core dependency

    // The following dependencies are optional and needed only in very specific use cases.
    // Make sure you are using the features they provide before adding the dependencies below.
    implementation 'com.incode.sdk:conference:1.5.2' // Optional dependency
    implementation 'com.incode.sdk:kiosk-login:1.1.0' // Optional dependency
    implementation 'com.incode.sdk:qr-face-login:1.0.0' // Optional dependency
    implementation 'com.incode.sdk:model-liveness-detection:2.0.0' // Optional dependency
    implementation 'com.incode.sdk:model-face-recognition:2.0.0' // Optional dependency
    implementation 'com.incode.sdk:model-id-face-detection:2.0.0' // Optional dependency
    implementation 'com.incode.sdk:model-mask-detection:2.0.0' // Optional dependency
    implementation 'com.incode.sdk:extensions:1.1.0' // Optional dependency
}

Required core-light dependency contains the image processing libraries that are used in the Welcome SDK.
Optional conference dependency is only necessary if you are using Conference module from the SDK.
Optional kiosk-login dependency is only necessary if you are using Kiosk Login feature of the SDK.
Optional qr-face-login dependency is only necessary if you are using QR Face Login feature of the SDK.
Optional model-liveness-detection dependency is only necessary if you are using liveness detection feature that runs locally on device.
Optional model-face-recognition dependency is only necessary if you are using face recognition feature that runs locally on device. This feature is available only for Face Login.
Optional model-id-face-detection dependency is only necessary if you are using checks for detecting front/back side of ID
Optional model-mask-detection dependency is only necessary if you are using the mask check in Selfie scan that runs locally on device.

Done!

Advanced Integration

If you are concerned about keeping your application download size as small as possible, you can utilize Google Play Feature Delivery to download Incode SDK on demand, at runtime, as a Dynamic Feature Module. This then allows you to uninstall the module when/if it is no longer needed.

Note:

You need to be using Android App Bundle format when publishing your app.
Dynamic Feature Modules are supported on devices running Android 5.0 (API Level 21) or higher.
That means that on other devices, dynamic modules will be installed together with the app.

Note:

It is not possible to isolate the whole Incode SDK to a dynamic module. The main (smaller) part needs to be declared as a direct dependency, and the core part (which contains larger files) can be separated into a dynamic module.

Note for Huawei devices without Google Mobile Services:

Google Play Feature Delivery does not work without Google Mobile Services (GMS).
Huawei provides its own library for this purpose - Huawei Dynamic Ability - that works with Huawei Mobile Services (HMS).
Integration is very similar to Google's; Classes and methods are named similarly.

Here is how you can build an example app for both GMS and HMS:

Step 1

In your project-level build.gradle, add the Incode maven repository with provided credentials:

allprojects {
    repositories {
        ...
        maven {
            url "http://repo.incode.com/artifactory/libs-incode-welcome"
            credentials {
                username = "organizationUsername"
                password = "xxxxxxxxxxxxxxxxxxxx"
            }
        }
    }
    ...
}

In your module-level app/build.gradle, add the following code to android{} closure:

compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
}

In your module-level app/build.gradle, add Incode library dependencies:

dependencies {
    ...

    // Google Play Core
    implementation 'com.google.android.play:core:1.9.0' // There might be a newer version available

    // Incode Welcome SDK
    api 'com.incode.sdk:welcome:5.15.0'
}

Step 2

If you have an Application class, make it extend from SplitCompatApplication

import com.google.android.play.core.splitcompat.SplitCompatApplication;

public class BaseApplication extends SplitCompatApplication {
    ...
}

If you do not have an Application class, add the following attribute to <application> element in your AndroidManifest.xml:

<application
    android:name="com.google.android.play.core.splitcompat.SplitCompatApplication"
    ...
    >

Step 3

Enable MultiDex

If your minSdkVersion is set to 21 or higher, MultiDex is enabled by default and you can skip this step.

If your minSdkVersion is lower than 21, follow this guide from Google to enable MultiDex: https://developer.android.com/studio/build/multidex#mdex-gradle

Step 4

Create new Dynamic Module in Android Studio:

• File --> New --> New Module

• Select Dynamic Feature Module Click Next

• Enter Module name, for example: incode_core Click Next

• Set your desired Module Title, for example: Incode Core Set Install-time inclusion to Do not include module at install-time (on-demand only) Enable Fusing

• Click Finish to create the Dynamic Module.

Step 5

Wait for Android Studio to finish syncing.

After the process is complete, take some time to review the changes that have been made to the project by Android Studio:

• You have a new module named incode_core

• In your module-level app/build.gradle, the following line has been added to android{} closure:

  dynamicFeatures = [':incode_core']

• In your app/res/values/strings.xml file, a string has been added:

  <string name="title_incode_core">Incode Core</string>

  • This is the user-friendly module name that could potentially be shown to the user.

Step 6

Open your app/res/values/strings.xml file

Add the following string resource:

<string name="module_name_incode_core" translatable="false">incode_core</string>

• You will use this string resource when referencing your Dynamic Module.
• Its value needs to match the Module name value from Step 4.

Step 7

Open incode_core/build.gradle

Add the following code to android{} closure:

compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
}

Add the following dependencies:

implementation 'com.incode.sdk:core-light:2.5.0' // Required core dependency
implementation 'com.incode.sdk:conference:1.5.2' // Optional dependency
implementation 'com.incode.sdk:kiosk-login:1.1.0' // Optional dependency
implementation 'com.incode.sdk:qr-face-login:1.0.0' // Optional dependency
implementation 'com.incode.sdk:model-liveness-detection:2.0.0' // Optional dependency
implementation 'com.incode.sdk:model-face-recognition:2.0.0' // Optional dependency
implementation 'com.incode.sdk:model-id-face-detection:2.0.0' // Optional dependency
implementation 'com.incode.sdk:model-mask-detection:2.0.0' // Optional dependency
implementation 'com.incode.sdk:extensions:1.0.0' // Optional dependency

The incode_core module does not need to contain any other code.

Required core-light dependency contains the image processing libraries that are used in the Welcome SDK.
Optional conference dependency is only necessary if you are using Conference module from the SDK.
Optional model-liveness-detection dependency is only necessary if you are using liveness detection feature that runs locally on device.
Optional model-face-recognition dependency is only necessary if you are using face recognition feature that runs locally on device. This feature is available only for Face Login.
Optional model-id-face-detection dependency is only necessary if you are using checks for detecting front/back side of ID
Optional model-mask-detection dependency is only necessary if you are using mask check in Selfie scan that runs locally on device.

Step 8

Add the following ndk abi filters to your module-level app/build.gradle inside defaultConfig{} closure:

ndk {
    abiFilters "arm64-v8a", "armeabi-v7a", "x86", "x86_64"
}

The Gradle configuration is now complete!

Step 9

Before using the Incode SDK, we need to make sure that Incode Core Dynamic Module is installed first.
If not, we can make a request to the Google Play Core library to download and install the Dynamic Module.

This is the example code that you can use somewhere in your app module (in an Activity):

    ...
    private static final int REQUEST_CODE_CONFIRM_MODULE_DOWNLOAD = 0x8A7; // Use your own value
    private SplitInstallManager splitInstallManager;
    private SplitInstallStateUpdatedListener splitInstallListener;
    ...

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        ...
        splitInstallManager = SplitInstallManagerFactory.create(this);
        checkIfIncodeSdkInstalled();
        ...
    }

    private void onIncodeSdkInstalled() {
        // Everything is ready; You can start the Incode SDK now
    }

    @Override
    protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
        super.onActivityResult(requestCode, resultCode, data);
        ...
        if (requestCode == REQUEST_CODE_CONFIRM_MODULE_DOWNLOAD) {
            if (resultCode == RESULT_OK) {
                // User accepted; Dynamic Module will soon start installing
            } else {
                // User denied the installation prompt; Dynamic Module will not be installed
            }
        }
        ...
    }

    private void checkIfIncodeSdkInstalled() {
        final String moduleName = getString(R.string.module_name_incode_core);
        if (splitInstallManager.getInstalledModules().contains(moduleName)) {
            // Dynamic feature module is already installed; Done!
            onIncodeSdkInstalled();
        } else {
            // Starting download of dynamic feature module
            SplitInstallRequest request = SplitInstallRequest.newBuilder()
                    .addModule(moduleName)
                    .build();

            if (splitInstallListener != null) {
                splitInstallManager.unregisterListener(splitInstallListener);
            }
            splitInstallListener = new SplitInstallStateUpdatedListener() {
                @Override
                public void onStateUpdate(@NonNull SplitInstallSessionState state) {
                    switch (state.status()) {
                        case SplitInstallSessionStatus.PENDING:
                            break;
                        case SplitInstallSessionStatus.REQUIRES_USER_CONFIRMATION:
                            /*
                              This may occur when attempting to download a sufficiently large module.
                              In order to see this, the application has to be uploaded to the Play Store.
                              Then features can be requested until the confirmation path is triggered.
                             */
                            try {
                                splitInstallManager.startConfirmationDialogForResult(state, MyActivity.this, REQUEST_CODE_CONFIRM_MODULE_DOWNLOAD);
                            } catch (IntentSender.SendIntentException e) {
                                finish();
                            }
                            break;
                        case SplitInstallSessionStatus.DOWNLOADING:
                            // You can use this method to update a progress indicator, for example:
                            //progressBar.setMax((int) state.totalBytesToDownload());
                            //progressBar.setProgress((int) state.bytesDownloaded());
                            break;
                        case SplitInstallSessionStatus.INSTALLING:
                            // Download complete; Installing...
                            //progressBar.setProgress((int) state.bytesDownloaded());
                            break;
                        case SplitInstallSessionStatus.INSTALLED:
                            if (splitInstallListener != null) {
                                splitInstallManager.unregisterListener(splitInstallListener);
                            }
                            // Done!
                            onIncodeSdkInstalled();
                            break;
                        case SplitInstallSessionStatus.FAILED:
                            if (splitInstallListener != null) {
                                splitInstallManager.unregisterListener(splitInstallListener);
                            }
                            // Install failed
                            break;
                        default:
                            Log.w(TAG, "Unhandled state:%s", state.status());
                            break;
                    }
                }
            };
            splitInstallManager.registerListener(splitInstallListener);
            splitInstallManager.startInstall(request);
        }
    }

Step 10 - Testing your implementation

If you now try to run your application from Android Studio, the Dynamic Module will be installed together with the app,
and the code for downloading and installing the module will never execute.

To actually test your implementation (downloading and installing the Dynamic Module),
you need to upload your App Bundle to Google Play.

To support on-demand modules, Google Play requires that you upload your application using the Android App Bundle format so that it can handle the on-demand requests from the server side.

Publishing the project on the Play Console requires some graphic assets,
so for testing purposes you can use these sample assets from the Google codelab:
https://github.com/googlecodelabs/android-dynamic-features/tree/master/graphic_assets

To be able to quickly test your application, without waiting for any approval, you can publish your application in the Internal Testing track.

For a step-by-step guide on how to publish a new application on the Google Play Store, you can follow the Play Console Guide on how to upload an app

Helpful links:

Google

https://developer.android.com/codelabs/on-demand-dynamic-delivery

Huawei

https://developer.huawei.com/consumer/en/codelab/DynamicAbility/index.html

Supporting both Google Mobile Services and Huawei Mobile Services

Supporting both Google Mobile Services and Huawei Mobile Services can be achieved by using build flavors and separate classes for downloading Dynamic Modules for GMS and HMS, which use the corresponding libraries.

A basic implementation is demonstrated in this example app:

Troubleshooting

Issue:

Attribute application@allowBackup value=(true) from AndroidManifest.xml is also present at [com.incode.sdk:welcome:x.x.x] AndroidManifest.xml value=(false).
Suggestion: add 'tools:replace="android:allowBackup"' to `<application>` element at AndroidManifest.xml to override.

Solution:

This means that you have set allowBackup in your AndroidManifest.xml to true, but the Welcome SDK has this value set to false.
Having allowBackup set to true is a potential security issue, so we suggest setting it to false.
If you are sure that you wish to allow backups, then add tools:replace="android:allowBackup" to <application> element in your Manifest.
If you already have some attributes in tools:replace, separate them with commas (for example: "android:label,android:allowBackup").

Issue:

Static interface methods are only supported starting with Android N (--min-api 24): Lbutterknife/Unbinder;lambda$static$0()V
Error while dexing. The dependency contains Java 8 bytecode. Please enable desugaring by adding the following to build.gradle
android {
    compileOptions {
        sourceCompatibility 1.8
        targetCompatibility 1.8
}}

Solution:

In your module-level [module]/build.gradle, add the following code to android{} closure:

compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
}

Issue:

Caused by: com.android.tools.r8.utils.b: Cannot fit requested classes in a single dex file (# methods: 88987 > 65536)
Execution failed for task ':app:mergeDexDebug'.
> A failure occurred while executing com.android.build.gradle.internal.tasks.Workers$ActionFacade
   > com.android.builder.dexing.DexArchiveMergerException: Error while merging dex archives:
     The number of method references in a .dex file cannot exceed 64K.
     Learn how to resolve this issue at https://developer.android.com/tools/building/multidex.html

Solution:

Make sure MultiDex is enabled
https://developer.android.com/studio/build/multidex#mdex-gradle

Issue:

Execution failed for task ':app:packageDebugBundle'.
> A failure occurred while executing com.android.build.gradle.internal.tasks.Workers$ActionFacade
   > All modules with native libraries must support the same set of ABIs, but module 'base' supports '[X86, ARMEABI_V7A, ARM64_V8A, X86_64, MIPS, ARMEABI]' and module 'incode_core' supports '[ARMEABI_V7A, X86, X86_64, ARM64_V8A]'.
- problem when generating bundles.

Solution:

Add the following ndk abi filters to your module-level app/build.gradle inside defaultConfig{} closure:

ndk {
    abiFilters "arm64-v8a", "armeabi-v7a", "x86", "x86_64"
}

Issue:

E/AndroidRuntime: FATAL EXCEPTION: RxCachedThreadScheduler-2
    Process: com.incode.welcome.example, PID: 6842
    io.reactivex.exceptions.UndeliverableException: The exception could not be delivered to the consumer because it has already canceled/disposed the flow or the exception has nowhere to go to begin with. Further reading: https://github.com/ReactiveX/RxJava/wiki/What's-different-in-2.0#error-handling | java.lang.NoSuchMethodError: No virtual method log(ILjava/lang/String;Ljava/lang/Throwable;)V in class Lokhttp3/internal/platform/Platform; or its super classes (declaration of 'okhttp3.internal.platform.Platform' appears in /data/app/com.incode.welcome.example-HnCVs4pdPTZBq3BhFsJmdQ==/base.apk!classes3.dex)
        at io.reactivex.plugins.RxJavaPlugins.onError(RxJavaPlugins.java:367)
        at io.reactivex.internal.schedulers.ScheduledRunnable.run(ScheduledRunnable.java:69)
        at io.reactivex.internal.schedulers.ScheduledRunnable.call(ScheduledRunnable.java:57)
        at java.util.concurrent.FutureTask.run(FutureTask.java:266)
        at java.util.concurrent.ScheduledThreadPoolExecutor$ScheduledFutureTask.run(ScheduledThreadPoolExecutor.java:301)
        at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1167)
        at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:641)
        at java.lang.Thread.run(Thread.java:919)
     Caused by: java.lang.NoSuchMethodError: No virtual method log(ILjava/lang/String;Ljava/lang/Throwable;)V in class Lokhttp3/internal/platform/Platform; or its super classes (declaration of 'okhttp3.internal.platform.Platform' appears in /data/app/com.incode.welcome.example-HnCVs4pdPTZBq3BhFsJmdQ==/base.apk!classes3.dex)
        at okhttp3.logging.HttpLoggingInterceptor$Logger$1.log(HttpLoggingInterceptor.java:114)
        at okhttp3.logging.HttpLoggingInterceptor.intercept(HttpLoggingInterceptor.java:173)
        at okhttp3.internal.http.RealInterceptorChain.proceed(RealInterceptorChain.kt:100)
        at okhttp3.internal.connection.RealCall.getResponseWithInterceptorChain$okhttp(RealCall.kt:197)
        at okhttp3.internal.connection.RealCall.execute(RealCall.kt:148)
        at retrofit2.OkHttpCall.execute(OkHttpCall.java:186)
        at retrofit2.adapter.rxjava2.CallExecuteObservable.subscribeActual(CallExecuteObservable.java:45)
        at io.reactivex.Observable.subscribe(Observable.java:12267)
        at retrofit2.adapter.rxjava2.BodyObservable.subscribeActual(BodyObservable.java:34)
        at io.reactivex.Observable.subscribe(Observable.java:12267)
        at io.reactivex.internal.operators.observable.ObservableMap.subscribeActual(ObservableMap.java:32)
        at io.reactivex.Observable.subscribe(Observable.java:12267)
        at io.reactivex.internal.operators.observable.ObservableSubscribeOn$SubscribeTask.run(ObservableSubscribeOn.java:96)
        at io.reactivex.Scheduler$DisposeTask.run(Scheduler.java:578)
        at io.reactivex.internal.schedulers.ScheduledRunnable.run(ScheduledRunnable.java:66)
        at io.reactivex.internal.schedulers.ScheduledRunnable.call(ScheduledRunnable.java:57) 
        at java.util.concurrent.FutureTask.run(FutureTask.java:266) 
        at java.util.concurrent.ScheduledThreadPoolExecutor$ScheduledFutureTask.run(ScheduledThreadPoolExecutor.java:301) 
        at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1167) 
        at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:641) 
        at java.lang.Thread.run(Thread.java:919) 

Solution:

This crash occurs when the okhttp3:okhttp dependency version is different from okhttp3:logging-interceptor or okhttp3:okhttp-urlconnection dependencies and trying to init Incode SDKs.

For example, in case you have in the Project's External Libraries the following dependencies, you will face the crash because of the version inconsistency:

• okhttp3:logging-interceptor:3.4.1
• okhttp3:okhttp-urlconnection:3.4.1
• okhttp3:okhttp:4.5.0

To fix the crash, for the example above, you need to bump the version of okhttp3:logging-interceptor & okhttp3:okhttp-urlconnection to 4.5.0.

Add the following implementations inside build.gradle to override existing lower versions:

dependencies {
    ...
    
    implementation 'com.squareup.okhttp3:logging-interceptor:4.5.0'
    implementation 'com.squareup.okhttp3:okhttp-urlconnection:4.5.0'
}

It is important to note that the crash will still occur in the case you only have the logging-interceptor or okhttp-urlconnection dependency.

Crashes if you have in External Libraries these dependencies:

• okhttp3:logging-interceptor:3.4.1
• okhttp3:okhttp:4.5.0

Crashes as well if you have in External Libraries these dependencies:

• okhttp3:okhttp-urlconnection:3.4.1
• okhttp3:okhttp:4.5.0

Issue:

org.gradle.api.InvalidUserCodeException: Build was configured to prefer settings repositories over project repositories but repository 'maven' was added by build file 'build.gradle'

Solution:

For projects using Gradle 6.8 or higher, a new way of defining dependencies in settings.gradle with the dependencyResolutionManagement block was introduced. Moving the maven repo declaration from the project build.gradle to here should resolve it. See also StackOverflow.

dependencyResolutionManagement {
    ...
    repositories {
        ...
        maven {
            url "https://repo.incode.com/artifactory/libs-incode-welcome"
            credentials {
                username = "organizationUsername"
                password = "xxxxxxxxxxxxxxxxxxxx"
            }
        }
    }
}