Getting Started on Android

Creating a New Project

  1. Open Android Studio and select New Project… in the File > New > New Project… menu to create a new project for your application:

create-new-project

  1. Choose the correct template for your project. In this example, we’ll use Empty Activity:

app-template

  1. When prompted, choose your app name (PSPDFKit Demo) and set the Save location, Language, and Minimum SDK (19), of your choice:

app-options

  1. Click the Finish button to save the project to your default project location.

Adding PSPDFKit to Your Project

  1. In your top-level build.gradle file, add the PSPDFKit Maven repository:

allprojects {
	repositories {
		maven {
				url 'https://customers.pspdfkit.com/maven/'
		}
	}
}
allprojects {
	repositories {
		maven {
				url = uri("https://customers.pspdfkit.com/maven")
		}
	}
}
  1. In your app/build.gradle file, add the PSPDFKit dependency:

dependencies {
	implementation 'com.pspdfkit:pspdfkit:7.0.0'
}
dependencies {
	implementation("com.pspdfkit:pspdfkit:7.0.0")
}

Configuring Your Build

PSPDFKit is supported on Android devices running API level 19 and newer and targeting the latest stable Android version 10 (API 29). Furthermore, PSPDFKit requires apps to enable Java 8 language features to build.

Inside your app/build.gradle file, make sure to have the following configuration:

android {
    compileSdkVersion 29
    buildToolsVersion '29.0.1'

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

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}
android {
    compileSdkVersion(29)
    buildToolsVersion = "29.0.1"

    defaultConfig {
        applicationId = "com.example.app"
        minSdkVersion(19)
        targetSdkVersion(29)
    }

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

With minSdkVersion set to 21, your app is available on more than 94.1 percent of devices on the Google Play Store (last update: March 2021).

Displaying a PDF

To verify that PSPDFKit was successfully integrated into your app, try opening a PDF file with the ready-to-use PdfActivity:

  1. Copy a PDF document into the assets directory of your Android project — for example, to src/main/assets/my-document.pdf.

  2. Add PdfActivity to your app’s AndroidManifest.xml:

<application>
		<activity
			android:name="com.pspdfkit.ui.PdfActivity"
			android:windowSoftInputMode="adjustNothing" />
</application>
  1. You can now start PdfActivity with the document from your assets directory:

val uri = Uri.parse("file:///android_asset/my-document.pdf")
val config = PdfActivityConfiguration.Builder(context).build()
PdfActivity.showDocument(this, uri, config)
final Uri uri = Uri.parse("file:///android_asset/my-document.pdf");
final PdfActivityConfiguration config = new PdfActivityConfiguration.Builder(context).build();
PdfActivity.showDocument(this, uri, config);
  1. PdfActivity will now present the document from your assets directory.

Next Steps

Adding PSPDFKit to Your Project

  1. In your top-level build.gradle file, add the PSPDFKit Maven repository:

allprojects {
	repositories {
		maven {
				url 'https://customers.pspdfkit.com/maven/'
		}
	}
}
allprojects {
	repositories {
		maven {
				url = uri("https://customers.pspdfkit.com/maven")
		}
	}
}
  1. In your app/build.gradle file, add the PSPDFKit dependency:

dependencies {
	implementation 'com.pspdfkit:pspdfkit:7.0.0'
}
dependencies {
	implementation("com.pspdfkit:pspdfkit:7.0.0")
}

Configuring Your Build

PSPDFKit is supported on Android devices running API level 19 and newer and targeting the latest stable Android version 10 (API 29). Furthermore, PSPDFKit requires apps to enable Java 8 language features to build.

Inside your app/build.gradle file, make sure to have the following configuration:

android {
    compileSdkVersion 29
    buildToolsVersion '29.0.1'

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

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}
android {
    compileSdkVersion(29)
    buildToolsVersion = "29.0.1"

    defaultConfig {
        applicationId = "com.example.app"
        minSdkVersion(19)
        targetSdkVersion(29)
    }

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

With minSdkVersion set to 21, your app is available on more than 94.1 percent of devices on the Google Play Store (last update: March 2021).

Displaying a PDF

To verify that PSPDFKit was successfully integrated into your app, try opening a PDF file with the ready-to-use PdfActivity:

  1. Copy a PDF document into the assets directory of your Android project — for example, to src/main/assets/my-document.pdf.

  2. Add PdfActivity to your app’s AndroidManifest.xml:

<application>
		<activity
			android:name="com.pspdfkit.ui.PdfActivity"
			android:windowSoftInputMode="adjustNothing" />
</application>
  1. You can now start PdfActivity with the document from your assets directory:

val uri = Uri.parse("file:///android_asset/my-document.pdf")
val config = PdfActivityConfiguration.Builder(context).build()
PdfActivity.showDocument(this, uri, config)
final Uri uri = Uri.parse("file:///android_asset/my-document.pdf");
final PdfActivityConfiguration config = new PdfActivityConfiguration.Builder(context).build();
PdfActivity.showDocument(this, uri, config);
  1. PdfActivity will now present the document from your assets directory.

Next Steps

Adding PSPDFKit to Your Project

PSPDFKit for Android can be imported manually. Below are the steps to follow if you wish to do so.

  1. Download the PSPDFKit for Android library AAR bundle from our Maven repository.

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

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

dependencies {
	implementation files('libs/pspdfkit-7.0.0.aar')

	// You must include all transitive dependencies of PSPDFKit.
	implementation 'androidx.legacy:legacy-support-v4:1.0.0'
	implementation 'androidx.appcompat:appcompat:1.1.0'
	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.2.0-alpha01'
	implementation 'io.reactivex.rxjava2:rxjava:2.2.7'
	implementation 'io.reactivex.rxjava2:rxandroid:2.1.1'
	implementation 'com.getkeepsafe.relinker:relinker:1.4.1'
	implementation 'org.jetbrains.kotlin:kotlin-stdlib:1.3.71'
}

ℹ️ 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’ve been using this technique, you need to migrate to file-based dependencies when updating the Android Gradle plugin to 3.5.0.

The following library is included in the list of transitive dependencies:

  • ReLinker — to work around some versions of Android that have unreliable PackageManager implementations

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

ProGuard

There’s 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 at proguard.txt, which is located inside the PSPDFKit .aar:

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

Displaying a PDF

To verify that PSPDFKit was successfully integrated into your app, try opening a PDF file with the ready-to-use PdfActivity:

  1. Copy a PDF document into the assets directory of your Android project — for example, to src/main/assets/my-document.pdf.

  2. Add PdfActivity to your app’s AndroidManifest.xml:

<application>
		<activity
			android:name="com.pspdfkit.ui.PdfActivity"
			android:windowSoftInputMode="adjustNothing" />
</application>
  1. You can now start PdfActivity with the document from your assets directory:

val uri = Uri.parse("file:///android_asset/my-document.pdf")
val config = PdfActivityConfiguration.Builder(context).build()
PdfActivity.showDocument(this, uri, config)
final Uri uri = Uri.parse("file:///android_asset/my-document.pdf");
final PdfActivityConfiguration config = new PdfActivityConfiguration.Builder(context).build();
PdfActivity.showDocument(this, uri, config);
  1. PdfActivity will now present the document from your assets directory.

Next Steps

Cloning PSPDFKit Catalog

  1. Open the terminal app and change the current working directory. In this case, we’ll use the ~/Downloads directory:

cd ~/Downloads
  1. Clone the PSPDFKit for Android Catalog repository:

git clone https://github.com/PSPDFKit/pspdfkit-android-catalog.git
  1. Start Android Studio and open the cloned project folder from the File > Open… menu.

  2. Wait a few moments for Gradle to sync the project.

  3. Make sure you either set up an emulator with the AVD or connect an Android device.

  4. Build and run the app configuration using the Run ‘app’ button in Android Studio.

build-run-catalog-app

  1. You should see the PSPDFKit Catalog app on your device:

catalog-view

Next Steps