> For the complete documentation index, see [llms.txt](https://docs.apryse.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apryse.com/android/samples/cookbook/try-demo.md).

# Quick start - view a document in Android

Learn how to create a simple Android app that opens a PDF document using DocumentActivity. Follow our step-by-step tutorial and integrate Apryse SDK into your project with Gradle. Get started now! The

## Prerequisites

* Minimum API: 21 (using AndroidX)
* Compile API: 35
* Recommended target API: 35
* The latest version of [Android Studio](https://developer.android.com/studio/).
* If your app is using AndroidX you will also need to add `android.useAndroidX=true` and `android.enableJetifier=true` in your `gradle.properties` file. Learn more about requirements in our [AndroidX FAQ](/android/get-started/faq/androidx.md).

{% hint style="info" %}
**No trial license key required.**

The trial of Apryse Mobile SDK does not require a trial key. A commercial license key is required for use in a production environment. Please [contact sales](https://apryse.com/form/contact-sales) to purchase a commercial key or if you need any other license key assistance.
{% endhint %}

{% hint style="warning" %}
**Keep your license keys confidential.**

License keys are uniquely generated. Please make sure that it is not publicly available (e.g. in your public GitHub).
{% endhint %}

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`](https://sdk.apryse.com/api/android/javadoc/reference/com/pdftron/pdf/controls/DocumentActivity.html). The sample code for this tutorial is available at our [GitHub repository](https://github.com/ApryseSDK/pdftron-android-samples/tree/master/QuickStartPDFViewer/).

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

![](https://226546913-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0QItsdFBmuuL9ezHimHy%2Fuploads%2Fgit-blob-eb2f8c28565141a58a5a50b8560370beea8b0db6%2F3573001963ed971e9702e4eabff2046e43392e6a-767x480.png?alt=media)

1. Create a new Android Studio project with an Empty Activity and set the minimum SDK to **API 16**. Learn more about Apryse's system requirements in [Android supported API FAQ](/android/get-started/faq/supported-api.md).
2. For simplicity, we'll integrate the Apryse SDK into our project using `Gradle`. You can learn more about how Gradle is used in Android Studio at the [Gradle guides](https://guides.gradle.org/building-android-apps/).Find your `gradle.properties` file in the root folder of your project and add your license key to this file:

{% tabs %}
{% tab title="Shell" %}
{% code lineNumbers="true" %}

```sh
PDFTRON_LICENSE_KEY=INSERT_COMMERCIAL_LICENSE_KEY_HERE_AFTER_PURCHASE
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="info" %}
**No trial license key required.**

The trial of Apryse Mobile SDK does not require a trial key. A commercial license key is required for use in a production environment. Please [contact sales](https://apryse.com/form/contact-sales) to purchase a commercial key or if you need any other license key assistance.
{% endhint %}

{% hint style="warning" %}
**Keep your license keys confidential.**

License keys are uniquely generated. Please make sure that it is not publicly available (e.g. in your public GitHub).
{% endhint %}

1. Now open the `settings.gradle` file located **in your project's root directory** and add the Apryse Maven repository:

{% tabs %}
{% tab title="Groovy" %}
{% code lineNumbers="true" %}

```groovy
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            url "https://pdftron-maven.s3.amazonaws.com/release"
        }
        jcenter() // Warning: this repository is going to shut down soon
    }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

1. Then in your app module's `build.gradle` file (usually `app/build.gradle`) add the following:You should also sync your project when you make changes in your Gradle files.

{% tabs %}
{% tab title="Groovy" %}
{% code lineNumbers="true" %}

```groovy
android {
    defaultConfig {
        ...
        multiDexEnabled true
        vectorDrawables.useSupportLibrary = true
        manifestPlaceholders = [pdftronLicenseKey:PDFTRON_LICENSE_KEY]
    }
}

dependencies {
    ...
    implementation "com.pdftron:pdftron:11.0.0"
    implementation "com.pdftron:tools:11.0.0"

    implementation 'androidx.multidex:multidex:2.0.1'
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="info" %}
**If you encountered any issue with gradle sync, check out the Troubleshooting guide.**
{% endhint %}

1. 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 [Android Mobile SDK permissions](/android/learn-more/permissions.md).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 Apryse license key. The resulting `AndroidManifest.xml` file should look something like this:

| Feature                                                                                                  | Relevant permission               |
| -------------------------------------------------------------------------------------------------------- | --------------------------------- |
| <ul><li>Opening a PDF from a URL</li><li>HTML to PDF conversion</li><li>Realtime collaboration</li></ul> | `android.permission.INTERNET`     |
| <ul><li>Creating sound annotations</li></ul>                                                             | `android.permission.RECORD_AUDIO` |

{% hint style="warning" %}
**Storage Permission**

Please follow the latest Android best practices and guidelines outlined [here](https://developer.android.com/training/permissions/usage-notes/)
{% endhint %}

{% tabs %}
{% tab title="XML" %}
{% code lineNumbers="true" %}

```xml
<?xml version="1.0" encoding="utf-8"?>
<!-- Include existing attributes in manifest -->
<manifest>

    <!-- Required permissions are added here -->
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.RECORD_AUDIO" />

    <!-- Add multidex support and enable largeHeap. Also enable usesCleartextTraffic in application attributes if you are working with HTTP files. If you are only working with HTTPS files, this is not required.-->
    <!-- Include existing attributes in application -->
    <application android:name="androidx.multidex.MultiDexApplication" android:largeHeap="true" android:usesCleartextTraffic="false">    
        
        <!-- Add license key in meta-data tag here. This should be inside the application tag. -->
        <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/PDFTronAppTheme"/>
    </application>
</manifest>
```

{% endcode %}
{% endtab %}
{% endtabs %}

1. If you would like to customize the appearance of the viewer activity, define `PDFTronAppTheme` (referenced by `DocumentActivity` in `AndroidManifest.xml`) in `res/values/styles.xml`:You can learn more about this in the [customize the viewer's theme guide](/android/ui-customization/custom-theme-a.md).

{% tabs %}
{% tab title="XML" %}
{% code lineNumbers="true" %}

```xml
<!-- Include existing attributes in resources -->
<resources>
    <!-- Custom theme that will be used by the document reader -->
    <style name="PDFTronAppTheme" parent="PDFTronAppThemeBase"> <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>
```

{% endcode %}
{% endtab %}
{% endtabs %}

1. Now add a PDF file to the `res/raw` folder of your project (you can use our [sample file](https://github.com/ApryseSDK/pdftron-android-samples/blob/master/QuickStartPDFViewer/app/src/main/res/raw/sample.pdf)) and call it **sample.pdf**, we are going to reference this file in the next step.

![](https://226546913-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0QItsdFBmuuL9ezHimHy%2Fuploads%2Fgit-blob-726278599b598bb82c008148cac56d9e3f01c3a0%2Fc924c319bd5c1f91a53ee0e90ece3f423842bb1a-230x263.png?alt=media)

1. In `onCreate` of your launcher activity, call \[`DocumentActivity.openDocument(Context, int)`]\(<https://sdk.apryse.com/api/android/javadoc/reference/com/pdftron/pdf/controls/DocumentActivity.html#openDocument(android.content.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](https://github.com/ApryseSDK/pdftron-android-blogs/tree/master/AndroidPDFViewer/).

{% tabs %}
{% tab title="Java" %}
{% code lineNumbers="true" %}

```java
// ...
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // Open our sample document in the 'res/raw' resource folder
    DocumentActivity.openDocument(this, R.raw.sample);
}
```

{% endcode %}
{% endtab %}

{% tab title="Kotlin" %}
{% code lineNumbers="true" %}

```kotlin
// ...
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    // Open our sample document in the 'res/raw' resource folder
    DocumentActivity.openDocument(this, R.raw.sample);
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

![](https://226546913-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0QItsdFBmuuL9ezHimHy%2Fuploads%2Fgit-blob-bb206ec1d18fef0a46a819fd87a140a1ed6371a5%2F199cca72d0118cdfa361d3debf9f21777836b2f3-1080x2160.png?alt=media)

{% tabs %}
{% tab title="Java" %}
{% code lineNumbers="true" %}

```java
// Open a local document given a path
private void openLocalDocument(Context context, String localFilePath) {
    final Uri localFile = Uri.fromFile(new File(localFilePath));
    DocumentActivity.openDocument(context, localFile);
}

// Open a document given a Content Uri
private void openContentUriDocument(Context context, Uri contentUri) {
    DocumentActivity.openDocument(context, contentUri);
}

// Open a document from HTTP/HTTPs
private void openHttpDocument(Context context, String url) {
    final Uri fileLink = Uri.parse(url);
    DocumentActivity.openDocument(context, fileLink);
}

// Open a document stored in the 'src/main/res/raw' folder
private void openRawResourceDocument(Context context, @IdRes int fileResId) {
    DocumentActivity.openDocument(context, fileResId);
}
```

{% endcode %}
{% endtab %}

{% tab title="Kotlin" %}
{% code lineNumbers="true" %}

```kotlin
// Open a local document given a path
private fun openLocalDocument(context: Context, localFilePath: String) {
    val localFile = Uri.fromFile(File(localFilePath))
    DocumentActivity.openDocument(context, localFile)
}

// Open a document given a Content Uri
private fun openContentUriDocument(context: Context, contentUri: Uri) {
    DocumentActivity.openDocument(context, contentUri)
}

// Open a document from HTTP/HTTPs
private fun openHttpDocument(context: Context, url: String) {
    val fileLink = Uri.parse(url)
    DocumentActivity.openDocument(context, fileLink)
}

// Open a document stored in the 'src/main/res/raw' folder
private fun openRawResourceDocument(context: Context, @IdRes fileResId: Int) {
    DocumentActivity.openDocument(context, fileResId)
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Next steps

* Customize your document reader by using [ViewerConfig](/android/viewer/fragment-config.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.apryse.com/android/samples/cookbook/try-demo.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.