Integrating PSPDFKit

To include PSPDFKit in your app, you’ll have to use a build system supporting the Android AAR library format — Gradle, Maven, or similar. The Eclipse IDE with the Ant build system is not supported.

Requirements

PSPDFKit is supported on Android devices with API 19 and newer, targeting the latest stable Android version P (API 28). PSPDFKit uses the Android Jetpack libraries to make many of the latest Android features available on older devices. You can target devices with API 19 and newer by setting the minSdkVersion inside your app’s build.gradle. Since PSPDFKit is developed and tested on the latest Android versions, set your compileSdkVersion and targetSdkVersion to those versions as well. Finally, you also need to enable Java 8 support for your project:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

android {
    compileSdkVersion 29
    buildToolsVersion '29.0.1'

    defaultConfig {
        applicationId 'com.example.app'
        minSdkVersion 19
        targetSdkVersion 28
    }

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

ℹ️ Note: By targeting a minimum API of 19, your app is available on 96.4 percent of devices on the Google Play Store.

We recommend Android Studio 3.5 as the IDE and Android Gradle plugin 3.5.1 or higher for development.

Automated Integration Using Gradle

The easiest way to integrate PSPDFKit into your app is by specifying it as a dependency inside your app’s build.gradle file.

1. In your web browser, log in to https://customers.pspdfkit.com and navigate to the Your Licenses & Keys page. If you don’t yet have a customer account, you can also get an evaluation license.
2. Locate your Android license and click Download PSPDFKit for Android, and then open the Use Gradle tab.
3. Follow the instructions on the screen to integrate PSPDFKit into your app:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

repositories {
    google()
    jcenter()
    ...

    maven {
        url 'https://customers.pspdfkit.com/maven/'

        credentials {
            username 'pspdfkit'
            password 'YOUR_MAVEN_KEY_GOES_HERE'
        }
    }
}

...

dependencies {
    ...
    implementation 'com.pspdfkit:pspdfkit:6.0.3'
}

If you encounter any problems during the integration, please let us know.

Example Catalog App

The example Catalog app contains a lot of useful examples for exploring the different features of PSPDFKit and getting started quickly. You can find the example Catalog sources inside the customer portal at https://customers.pspdfkit.com or by requesting an evaluation license of PSPDFKit.

Manual Library File Integration

1. In your web browser, log in to https://customers.pspdfkit.com and navigate to the Your Licenses & Keys page. If you don’t yet have a customer account, you can also get an evaluation license.

2. Locate your Android license and click Download PSPDFKit for Android.

3. Download the PSPDFKit library ZIP bundle and extract it.

4. Copy the PSPDFKit AAR file into your project’s libs directory.

5. Include PSPDFKit as a file-based dependency in your project, and provide all the transitive dependencies required by PSPDFKit (as shown below):

   Groovy

   Copy

   build.gradle
   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18	dependencies { implementation files('libs/pspdfkit-6.0.3.aar') // You must include all transitive dependencies of PSPDFKit. 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.palette:palette:1.0.0' implementation 'androidx.exifinterface:exifinterface:1.0.0' implementation 'androidx.gridlayout:gridlayout:1.0.0' implementation 'com.google.android.material:material:1.1.0-alpha02' implementation 'io.reactivex.rxjava2:rxjava:2.2.4' implementation 'io.reactivex.rxjava2:rxandroid:2.1.0' implementation 'com.getkeepsafe.relinker:relinker:1.3.1' implementation 'com.facebook.device.yearclass:yearclass:2.0.0' implementation 'org.jetbrains.kotlin:kotlin-stdlib:1.3.50' }

ℹ️ Note: Starting with the Android Gradle plugin 3.5.0, the use of flatDir repositories to include local AAR files is no longer supported. If you have been using this technique, you need to migrate to file-based dependencies when updating the Android Gradle plugin to 3.5.0.

The following optional libraries are included in the list of transitive dependencies:

• ReLinker — to work around some versions of Android that have unreliable PackageManager implementations.
• Device Year Class — to optimize the low-resolution render strategy based on device specs and performance.

These optional libraries can be omitted from the list of transitive dependencies if you don’t want to bundle them with your app. In such a case, PSPDFKit will detect the absence of these dependencies and will fall back to different implementations.

Nightly Builds

Nightly builds represent our current development snapshot and contain unreleased features and bug fixes. Our support team can grant access to nightly builds for special situations, such as if you need to verify if a feature or bug fix is working as intended.

ℹ️ Note: Although nightly builds should be stable, they haven’t undergone the same quality control process as stable releases, and as such, they are not meant to be used for apps in production.

Nightly Maven Downloads

If nightly builds are enabled for your customer account, you can download them by setting the version of your PSPDFKit Gradle dependency to SNAPSHOT:

1
2
3

dependencies {
    implementation 'com.pspdfkit:pspdfkit:SNAPSHOT'
}

Forcing Redownloading of Nightly Builds

To speed up your builds, Gradle will cache nightly binaries for a certain period before it redownloads a newer version from our servers. You can force Gradle to update the binaries to the latest available nightly binary inside Android Studio:

1. Open the Gradle tools window, usually located on the right side of Android Studio.
2. Right-click your Gradle root project (the first entry) and select Refresh dependencies.
3. Gradle will now redownload all dependencies and update the PSPDFKit nightly builds to the latest available version.

Download Nightly Builds Manually

Nightly builds are also available as ZIP files containing the PSPDFKit AAR file, the Catalog app, and other examples. The manually downloaded AAR file can be integrated using the Manual Library File Integration steps above. You can download the nightly ZIP file using the download link you received from the PSPDFKit customer support team.

ProGuard

There is no need to specify additional ProGuard rules since PSPDFKit uses consumersProguardFiles to keep ProGuard from obfuscating the required symbols. If you want to check out the rules, you should take a look into proguard.txt, which is located inside the PSPDFKit .aar:

1
2
3

    cd [YOUR_AAR_LOCATION]
    unzip [YOUR_AAR_NAME].aar -d aar-contents
    cat aar-contents/proguard.txt

Troubleshooting

If you’re getting java.lang.NoClassDefFoundError inside com.android.internal.os.ZygoteInit.main, this usually means the native library couldn’t be loaded. A common reason for this is either an invalid or too aggressive ProGuard configuration, or stale caches. Clean all intermediate build files (in Android Studio: Build > Clean Project) and rebuild your app to determine whether or not this is the case.