AndroidX migration

Starting with Nutrient Android SDK 5.1, we moved away from the older Android Support Library and are now using the new AndroidX library, which is part of Android Jetpack.

AndroidX is the next iteration of the Support Library, and it contains all the existing support library packages (such as AppCompat, fragments, and leanback APIs). Although the Android Support Library is still available for download from Google’s Maven repository, all development to it has been stopped.

Compatibility notes

To stay compatible with the Android library ecosystem, we opted to migrate Nutrient Android SDK with the 5.1 update in December 2018. This marked a breaking change for many of the classes used by Nutrient Android SDK, which results in the important version compatibility changes listed below:

  • Nutrient 5.0.2 and earlier — These versions of Nutrient use the older Android Support Library. When using these versions of Nutrient inside your app, you either need to build your app with the Support Library, or you need to enable Jetifier in your build setup.

  • Nutrient 5.1 and later — These versions of Nutrient use the new AndroidX library. When using these versions, your app needs to use AndroidX itself. Due to namespace clashes between AndroidX and the Support Library, it is not possible to bundle both libraries inside the same app.

ℹ️ Note: When upgrading your app to use Nutrient 5.1+, you need to migrate your app to AndroidX too. Using Nutrient 5.1+ inside an app that uses the Android Support Library is not possible.

Migrating your app

When updating to Nutrient 5.1 or newer, you will need to make sure your app uses the AndroidX library. This consists of several steps:

  • Changing your app’s dependencies, removing the old Support Library dependencies, and adding the new AndroidX library dependencies.

  • Changing the source code of your app, i.e. replacing any use of Support Library APIs with AndroidX APIs.

  • Enabling Jetifier, which allows use of third-party libraries that still use the Android Support Library.

Auto-migration inside Android Studio

To make migration easier, Android Studio integrates an automated migration wizard. If your app is still using the Support Library, the steps to migrate to AndroidX with Android Studio are outlined below.

  1. Inside Android Studio, open your Android project that still uses the old Android Support Library.

  2. Make sure the compileSdkVersion of your app is set to at least 28, which is required for the AndroidX migration:

    android {
    // This needs to be 28 or higher.
    compileSdkVersion 28
    ...
}

  3. In the menu, navigate to Refactor > Migrate to AndroidX….

  4. You should see a confirmation dialog that allows you to create a backup of your current project. Do this in case you don’t have a safe copy of your source code. You shouldn’t require this if your code is tracked using a version control system like Git.

    Back up your project before AndroidX migration

  5. Hit Migrate to start the migration process.

  6. After a brief period of searching, Android Studio will present you with a window with all sources that need to be migrated for AndroidX.

  7. Review the changes and press Do Refactor to finish the AndroidX migration.

  8. Your app is now using AndroidX.

⚠️ Important: Although the auto-migration to AndroidX works in most cases, it could be that the migration breaks parts of your app’s code or build setup. Make sure to verify that everything is working as expected (e.g. building, running, automated tests). In case something is not working, check out the official AndroidX migration guide for help.

Common migration problems

When updating to Nutrient 5.1 or later, or when migrating to AndroidX, there are a few problems that can prevent a successful migration. This section tries to describe the most common errors and how to fix them.

Including both AndroidX and the support library

Including AndroidX and the old Android Support Library at the same time does not work. If you try to build your app this way, you will most likely run into a build-time issue like the following:

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':app:transformClassesWithMultidexlistForDebug'.
> com.android.build.api.transform.TransformException: Error while generating the main dex list.
...
> Caused by: com.android.tools.r8.errors.CompilationError: Program type already present:
    android.support.v4.media.MediaBrowserCompat$ConnectionCallback$ConnectionCallbackInternal

Or, you might encounter an error like this:

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':app:transformDexArchiveWithExternalLibsDexMergerForDebug'.
> com.android.builder.dexing.DexArchiveMergerException: Error while merging dex archives:
  ...
  Program type already present: android.support.v4.media.MediaBrowserCompat$ConnectionCallback$ConnectionCallbackInternal

To use Nutrient 5.1 and newer, you need to migrate your app and all third-party source dependencies (for example, Git submodules or Cordova plugins) of your app to AndroidX.

I don’t know if my App uses the old Android support library

Inside your project’s build.gradle file, you will need to make sure that the newer AndroidX libraries are used. Here’s an example of an app’s dependencies that still use the older support libraries:

// Outdated dependencies that need to be updated.
dependencies {
    implementation 'com.pspdfkit:pspdfkit:2024.8.1'

    // These dependencies need to be replaced with AndroidX.
    implementation 'com.android.support:support-v4:26.0.2'
    implementation 'com.android.support:appcompat-v7:26.0.2'
    implementation 'com.android.support:recyclerview-v7:26.0.2'
    implementation 'com.android.support:cardview-v7:26.0.2'
    implementation 'com.android.support:design:26.0.2'
    ...
}

If your app also uses dependencies from the com.android.support group, you have to replace these dependencies using their respective AndroidX artifacts:

// Updated dependencies using AndroidX.
dependencies {
    implementation 'com.pspdfkit:pspdfkit:2024.8.1'

    implementation 'androidx.legacy:legacy-support-v4:1.0.0'
    implementation 'androidx.appcompat:appcompat:1.0.2'
    implementation 'androidx.recyclerview:recyclerview:1.0.0'
    implementation 'androidx.cardview:cardview:1.0.0'
    implementation 'androidx.gridlayout:gridlayout:1.0.0'
    implementation 'com.google.android.material:material:1.0.0'
    ...
}

It still doesn’t work after updating the dependencies

If the build still fails with error messages that point to the presence of the old Android Support Library, it’s very likely that the dependency is pulled in transitively by another third-party library. You can find out which library depends on the Android Support Library by running the dependency insight task of Gradle:

# Make sure to replace :app with the name of your Android app or library module.
$ ./gradlew -q :app:dependencies

The output will be a tree of dependencies that you can search within to find com.android.support. The dependency that is the hierarchical parent of any of the com.android.support dependencies will require an update. In case you don’t know how to update these dependencies, feel free to contact our technical support team for help.

Cross-platform support

The introduction of AndroidX marked a breaking change for the Android ecosystem. Due to the structure of AndroidX, it is not possible to integrate both the Android Support Library and AndroidX into a single app. While tools like the Android Studio auto-migration wizard and Jetifier allow for a hassle-free migration of Android apps, several third-party frameworks will require additional effort for migrating to AndroidX. Here, we want to provide an overview of cross-platform frameworks and their support for AndroidX.

Xamarin Android

In September 2019, AndroidX support was added to our Xamarin Android library with version 5.5.1.

Cordova/Ionic

Our Cordova library for Nutrient, which can be used for Apache Cordova and the Ionic framework, is regularly updated to use the latest version of Nutrient Android SDK, and it has already been migrated to 5.1+ and AndroidX.

However, there are a couple of problems when using AndroidX with other existing third-party Cordova and Ionic plugins:

  • AndroidX can’t be used in apps that use the older Android Support Library. Since several Cordova plugins add Maven dependencies to the Android Support Library, you might see a build error when trying run your app. If this is the case for you, have a look at the Common Migration Problems section of this guide for help.

  • Auto-migration of Cordova plugins using Jetifier does not work for Cordova plugins. Cordova plugins are integrated from source code (i.e. Java source code), and Jetifier was designed to operate on .aar library files that contain precompiled Java classes. This means that existing Cordova plugins must be migrated to AndroidX manually before they can be used in an AndroidX-enabled app.

In order to provide full future compatibility of our Cordova-Android library with other Cordova plugins, we’ve reported these issues on the official Apache Cordova issue tracker and are actively contributing in hopes of a quick resolution.

Known incompatible plugins

Here’s a list of Cordova and Ionic plugins that are knowingly incompatible with Cordova-Android for Nutrient and for which migration issues have been reported:

React Native

Our React Native library for Nutrient is regularly updated to use the latest version of Nutrient Android SDK, and it has already been migrated to 5.1+ and AndroidX.

However, there are two problems when using AndroidX:

  • AndroidX can’t be used in apps that use the older Android Support Library. Since several React Native plugins haven’t yet been migrated, you should also set up the React Native jetifier module to automatically migrate those modules to AndroidX.

  • AndroidX requires React Native 0.60. This is an issue because the Windows version of our React Native library is not updated to 0.60 due to compatibility issues. This means that if you want to support Android and Windows in one React Native project, you need to use the legacy version of our library. This legacy version is not using AndroidX since it is still on React Native 0.59 and using Nutrient Android SDK 5.0.1.

Flutter

Our Nutrient Flutter library for the Flutter framework is regularly updated to use the latest version of Nutrient Android SDK, and it has already been migrated to 5.1+ and AndroidX. While we don’t have reports of compatibility issues with other Flutter plugins, general conflicts with older plugins that use the Android Support Library might be possible for the same reasons described above in regards to our Cordova library. If you encounter conflicts in your Flutter app, let us know by contacting our technical support team.