Quick start - view a document

linkPrerequisites

• A valid evaluation or commercial license key. If you do not have a license key, please contact sales for a commercial license key or click here to get an evaluation key.
• The PDFTron Android SDK package.
• The latest version of Android Studio.

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.

1. On the Android welcome screen, click Start a new Android Studio project:

2. Create a new Android Studio project with an Empty Activity and set the minimum SDK to API 16.

3. 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

4. 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:

   Please make sure the above is added to the allprojects block, NOT the buildscript block.

5. Then in your 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.1"
       implementation "com.pdftron:tools:6.9.1"
   
       implementation 'com.android.support:multidex:1.0.3'
   }

   You should also sync your project when you make changes in your Gradle files.

   If you encountered any issue with gradle sync, check out the Troubleshooting guide.

6. The fully-featured document viewer DocumentActivity requires all the android permissions listed in the table below, however if you decide to create your own custom document viewer you should leave out unnecessary permissions.

   Permission	Purpose
   android.permission.WRITE_EXTERNAL_STORAGE	Storage permission for accessing local documents
   android.permission.INTERNET	Internet permission for downloading online documents
   android.permission.RECORD_AUDIO	Audio recording permission for creating sound annotations

   Since we are using the fully-featured reader in our sample app, we add these permissions to the AndroidManifest.xml file of our project. In this file, will also need to add a reference to our PDFTron license key and declare DocumentActivity. The resulting AndroidManifest.xml file should look something like this:

   <?xml version="1.0" encoding="utf-8"?>
   <manifest xmlns:android="http://schemas.android.com/apk/res/android"
       package="com.pdftron.myapplication"
       ...>
   
       <!-- 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>

7. Also, add the following theme (referenced in AndroidManifest.xml) to your res/values/styles.xml file:

   <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>

   If you are using your own theme, please don't forget to add or change the theme tag of your AndroidManifest file's corresponding activity declaration.

8. 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.

9. 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 at our GitHub repository.

linkNext Steps

• Customize your document reader by using ViewerConfig