Documentation
Some test text!
In this quick start tutorial you will create a simple Android app that will open a PDF document stored in your Android project by using DocumentActivity
. The sample code for this tutorial is available at our GitHub repository.
Create a new Android Studio project with an Empty Activity and set the minimum SDK to API 16. You can learn more about the system requirements here.
For simplicity, we'll integrate the PDFTron SDK into our project using Gradle
. You can learn more about how Gradle is used in Android Studio at the Gradle guides.
Find your gradle.properties
file in the root folder of your project and add your credentials to this file:
AWS_ACCESS_KEY=YOUR_ACCESS_KEY_GOES_HERE
AWS_SECRET_KEY=YOUR_SECRET_KEY_GOES_HERE
PDFTRON_LICENSE_KEY=YOUR_PDFTRON_LICENSE_KEY_GOES_HERE
Now find your project's root-level build.gradle
file:
and add the PDFTron Maven repository to the repositories
tag:
allprojects {
//...
repositories {
//...
maven {
url "s3://pdftron-maven/release"
credentials(AwsCredentials) {
accessKey AWS_ACCESS_KEY
secretKey AWS_SECRET_KEY
}
}
}
}
Copy the following as is, do not import org.gradle.api.credentials.Credentials
:
repositories
block in the allprojects
, not in buildscript
.Then in your app module's build.gradle
file (usually app/build.gradle
) add the following:
android {
defaultConfig {
...
multiDexEnabled true
vectorDrawables.useSupportLibrary = true
manifestPlaceholders = [pdftronLicenseKey:PDFTRON_LICENSE_KEY]
}
configurations.all {
resolutionStrategy.force "com.android.support:appcompat-v7:28.0.0"
resolutionStrategy.force "com.android.support:support-v4:28.0.0"
resolutionStrategy.force "android.arch.lifecycle:runtime:1.0.3"
}
}
dependencies {
...
implementation "com.pdftron:pdftron:6.9.5"
implementation "com.pdftron:tools:6.9.5"
implementation 'com.android.support:multidex:1.0.3'
}
You should also sync your project when you make changes in your Gradle files.
In order to support all the features in DocumentActivity
, we need to include the Android permissions listed in the table below. However if you would like to disable certain features and customize your document viewer, you should leave out unnecessary permissions. You can learn more about permissions here.
Feature | Relevant permission |
---|---|
Accessing documents in local storage, including:
| android.permission.WRITE_EXTERNAL_STORAGE |
| android.permission.INTERNET |
| android.permission.RECORD_AUDIO |
In this sample we'll add all the permissions to AndroidManifest.xml
so we can support all the features in the viewer. In this file, we'll also need to add a reference to our PDFTron license key. The resulting AndroidManifest.xml
file should look something like this:
<?xml version="1.0" encoding="utf-8"?>
<manifest ...>
<!-- Required permissions are added here -->
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<!-- Add multidex support and enable largeHeap -->
<application
android:name="android.support.multidex.MultiDexApplication"
android:largeHeap="true"
android:usesCleartextTraffic="true"
...>
<!-- Reference to our PDFTron license key -->
<meta-data
android:name="pdftron_license_key"
android:value="${pdftronLicenseKey}"/>
<!-- Document viewer activity declaration-->
<activity android:name="com.pdftron.pdf.controls.DocumentActivity"
android:configChanges="keyboardHidden|orientation|screenSize|screenLayout|smallestScreenSize"
android:windowSoftInputMode="adjustPan"
android:theme="@style/CustomAppTheme"/>
...
</application>
</manifest>
If you would like to customize the appearance of the viewer activity, define CustomAppTheme
(referenced by DocumentActivity
in AndroidManifest.xml
) in res/values/styles.xml
:
<resources>
...
<!-- Custom theme that will be used by the document reader -->
<style name="CustomAppTheme" parent="Theme.AppCompat.DayNight.NoActionBar">
<item name="colorPrimary">@color/app_color_primary_day</item>
<item name="colorPrimaryDark">@color/app_color_primary_dark_day</item>
<item name="colorAccent">@color/app_color_accent</item>
<!-- Action bar -->
<item name="actionModeBackground">?attr/colorPrimary</item>
<item name="windowActionModeOverlay">true</item>
</style>
</resources>
DocumentActivity
extends AppCompatActivity
and uses AppCompat Toolbar
. It's important that you define a Theme.AppCompat
theme for CustomAppTheme
. The recommended theme is Theme.AppCompat.*.NoActionBar
. Other custom themes can also be used, however be sure to disable the action bar manually:
<style name="CustomAppTheme" parent="Theme.AppCompat.*">
...
<!-- Action bar -->
<item name="windowActionModeOverlay">true</item>
<item name="windowActionBar">false</item>
<item name="windowNoTitle">true</item>
</style>
Now add a PDF file to the res/raw
folder of your project (you can use our sample here) and call it sample.pdf, we are going to reference this file in the next step.
In onCreate
of your launcher activity, call DocumentActivity.openDocument(Context, int)
to open this PDF file with the document reader:
This launches DocumentActivity
with our sample PDF document with default viewer configurations, and you should see the following:
You can also view your document in DocumentActivity
by specifiying a local file path, an HTTP/HTTPS url, or a Content Uri:
Please note that any changes made to files opened from res/raw
will not be saved on the disk.
The source code for this tutorial can be found on our GitHub repository.
ViewerConfig