AndroidX Migration

Starting with PSPDFKit 5.1 for Android, 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 (AppCompat, fragments, leanback APIs, etc.). Although the Android Support Library is still available for download from Google’s Maven repository, all development to it has been stopped.

Compatibility Notes

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

  • PSPDFKit 5.0.2 and earlier — These versions of PSPDFKit use the older Android Support Library. When using these versions of PSPDFKit inside your app, you either need to build your app with the Support Library, or you need to enable Jetifier in your build setup.
  • PSPDFKit 5.1 and later — These versions of PSPDFKit 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 PSPDFKit 5.1+, you need to migrate your app to AndroidX too. Using PSPDFKit 5.1+ inside an app that uses the Android Support Library is not possible.

Migrating Your App

When updating to PSPDFKit 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:

    build.gradle
    1
    2
    3
    4
    5
    
    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.

  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, please check out the official AndroidX migration guide for help.

Common Migration Problems

When updating to PSPDFKit 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:

Copy
1
2
3
4
5
6
7
8
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:

Copy
1
2
3
4
5
6
7
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

In order to use PSPDFKit 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:

Copy
build.gradle
1
2
3
4
5
6
7
8
9
10
11
12
// Outdated dependencies that need to be updated.
dependencies {
    implementation 'com.pspdfkit:pspdfkit:5.4.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:

Copy
build.gradle
1
2
3
4
5
6
7
8
9
10
11
12
// Updated dependencies using AndroidX.
dependencies {
    implementation 'com.pspdfkit:pspdfkit:5.4.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:

1
2
# 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 which 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

As of now (May 2019), the Xamarin framework does not support AndroidX bindings. There’s an open issue for supporting AndroidX on the official Xamarin Android GitHub repository, and the Xamarin team at Microsoft is actively working on resolving the issue.

Since AndroidX support is required for PSPDFKit 5.1 and newer, the latest available version of our Xamarin wrapper for PSPDFKit is 5.0.2. As soon as there is official support for AndroidX, we will be able to continuously publish newer Xamarin wrapper updates whenever we ship a new version of PSPDFKit for Android.

Cordova/Ionic

Our Cordova wrapper for PSPDFKit, which can be used for Apache Cordova and the Ionic framework, is regularly updated to use the latest version of PSPDFKit for Android, 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 also 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 our Common Migration Problems section 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 wrapper 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 PSPDFKit and for which migration issues have been reported:

React Native

React Native was migrated to AndroidX for the upcoming 0.60 release. The last stable release of our React Native wrapper for PSPDFKit is using PSPDFKit 5.0.1 until AndroidX is available for React Native as a stable release. We also provide an experimental version that is using PSPDFKit 5.3.0 (see below). As soon as there is official support for AndroidX, we will be able to continue publishing newer stable React Native wrapper updates whenever we ship a new version of PSPDFKit for Android. In the meantime, all updates will take place on our experimental branch.

Experimental AndroidX Support

While our last stable release of the React Native wrapper for PSPDFKit is still using PSPDFKit 5.0.1, we do provide an experimental branch that has been updated to PSPDFKit 5.2.0 and is using AndroidX. It comes with a Gradle build script that automatically replaces the old support library imports with their AndroidX counterparts in all Gradle modules. This should not cause issues for 90 percent of the use cases. However, keep in mind that there is no way for us to test that it works for every application, so we can’t guarantee it will work for you.

Flutter

Our PSPDFKit Flutter wrapper for the Flutter framework is regularly updated to use the latest version of PSPDFKit for Android, 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 wrapper. If you encounter conflicts in your Flutter app, please let us know by contacting our technical support team.