--- title: "External Document" canonical_url: "https://www.nutrient.io/guides/android/samples/external-document-kotlin/" md_url: "https://www.nutrient.io/guides/android/samples/external-document-kotlin.md" last_updated: "2026-05-15T19:10:04.916Z" description: "Pick and open a document from the device file system." --- # External Document Pick and open a document from the device file system. [Get Started](https://www.nutrient.io/sdk/android/getting-started.md) [All Samples](https://www.nutrient.io/guides/android/samples.md) [Download](https://www.nutrient.io/guides/android/downloads.md) [Launch Demo](https://www.nutrient.io/demo/) --- ```kotlin /* * Copyright © 2020-2026 PSPDFKit GmbH. All rights reserved. * * The PSPDFKit Sample applications are licensed with a modified BSD license. * Please see License for details. This notice may not be removed from this file. */ package com.pspdfkit.catalog.examples.kotlin import android.app.Activity import android.app.AlertDialog import android.content.Context import android.content.Intent import android.net.Uri import android.os.Build import android.os.Build.VERSION.SDK_INT import android.os.Bundle import android.os.Environment import android.widget.Toast import androidx.fragment.app.FragmentActivity import com.pspdfkit.Nutrient import com.pspdfkit.catalog.R import com.pspdfkit.catalog.SdkExample import com.pspdfkit.catalog.utils.Utils import com.pspdfkit.configuration.activity.PdfActivityConfiguration import com.pspdfkit.document.ImageDocumentLoader import com.pspdfkit.document.ImageDocumentUtils import com.pspdfkit.document.download.DownloadJob import com.pspdfkit.document.download.DownloadProgressFragment import com.pspdfkit.document.download.DownloadRequest import com.pspdfkit.ui.PdfActivityIntentBuilder import com.pspdfkit.utils.getSupportParcelableExtra import java.io.File /** * This example shows how to build a custom activity that allows the user to pick a document. */ class ExternalDocumentExample(context: Context) : SdkExample(context, R.string.externalDocumentExampleTitle, R.string.externalDocumentExampleDescription) { override fun launchExample(context: Context, configuration: PdfActivityConfiguration.Builder) { // Let's not save any changes to the opened file system documents in this example. configuration.autosaveEnabled(false) val intent = Intent(context, ExternalExampleActivity::class.java) intent.putExtra(ExternalExampleActivity.EXTRA_CONFIGURATION, configuration.build()) context.startActivity(intent) } } class ExternalExampleActivity : FragmentActivity() { private lateinit var configuration: PdfActivityConfiguration private var waitingForResult = false override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) // Extract the configuration for displaying the viewer activity. configuration = intent.getSupportParcelableExtra(EXTRA_CONFIGURATION, PdfActivityConfiguration::class.java)?: throw ExceptionInInitializerError( ExternalExampleActivity::class.java.simpleName + " was started without a PdfActivityConfiguration.", ) // Check if the activity was recreated, and see if the user already started document picking. waitingForResult = savedInstanceState?.getBoolean(IS_WAITING_FOR_RESULT, false)?: false // Prevent the example from requesting multiple documents at the same time. if (!waitingForResult) { waitingForResult = true if (Utils.hasExternalStorageRwPermission(this)) { showOpenFileDialog() } else { showPermissionExplanationDialog() } } } @Deprecated("Deprecated in Java") override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) { super.onActivityResult(requestCode, resultCode, data) if (requestCode == REQUEST_OPEN_DOCUMENT) { waitingForResult = false if (resultCode == Activity.RESULT_OK && data!= null) { val uri = data.data?: return val isImageFile = ImageDocumentUtils.isImageUri(this, uri) // Some URIs can be opened directly, including local filesystem, app assets, and content provider URIs. if (Nutrient.isOpenableUri(this, uri)) { startActivity(createActivityIntent(uri, configuration, isImageFile)) finish() } else { // Find the DownloadProgressFragment for showing download progress, or create a new one. val downloadFragment = supportFragmentManager.findFragmentByTag( DOWNLOAD_PROGRESS_FRAGMENT, ) as DownloadProgressFragment??: run { DownloadProgressFragment().apply { val request = DownloadRequest.Builder(this@ExternalExampleActivity).uri(uri).build() this.job = DownloadJob.startDownload(request) show(supportFragmentManager, DOWNLOAD_PROGRESS_FRAGMENT) } } // Once the download is complete we launch the PdfActivity from the downloaded file. downloadFragment.job.setProgressListener( object : DownloadJob.ProgressListenerAdapter() { override fun onComplete(output: File) { startActivity(createActivityIntent(Uri.fromFile(output), configuration, isImageFile)) finish() } }, ) } } else if (resultCode == Activity.RESULT_CANCELED) { // If the user cancelled document selection, we just close the activity. finish() } } else if (requestCode == REQUEST_ASK_FOR_PERMISSION) { if (SDK_INT >= Build.VERSION_CODES.R) { if (Environment.isExternalStorageManager()) { showOpenFileDialog() } else { Toast.makeText(this, "Allow permission for storage access!", Toast.LENGTH_SHORT).show() } } } } private fun createActivityIntent(uri: Uri, baseConfiguration: PdfActivityConfiguration, isImageFile: Boolean): Intent { val pdfActivityIntentBuilder: PdfActivityIntentBuilder var configuration = baseConfiguration if (isImageFile) { pdfActivityIntentBuilder = PdfActivityIntentBuilder.fromImageUri(this, uri) // Get the default image document configuration. // Default options in this configuration are specifically thought to enhance the user // experience for image documents (e.g. thumbnail bar and page number overlay are hidden). configuration = ImageDocumentLoader.getDefaultImageDocumentActivityConfiguration(configuration) } else { pdfActivityIntentBuilder = PdfActivityIntentBuilder.fromUri(this, uri) } return pdfActivityIntentBuilder.configuration(configuration).build() } override fun onSaveInstanceState(outState: Bundle) { super.onSaveInstanceState(outState) // Retain if we are currently waiting for an intent to return, so we don't set it off twice by accident. outState.putBoolean(IS_WAITING_FOR_RESULT, waitingForResult) } override fun onRequestPermissionsResult(requestCode: Int, permissions: Array, grantResults: IntArray) { super.onRequestPermissionsResult(requestCode, permissions, grantResults) if (requestCode == REQUEST_ASK_FOR_PERMISSION) { // We attempt to open document after permissions have been requested. // Nutrient can open documents without the permissions when SAF is used, however the access // without permissions will be significantly slower. showOpenFileDialog() } } private fun showPermissionExplanationDialog() { AlertDialog.Builder(this).setMessage(R.string.externalDocumentExamplePermissionExplanation).setCancelable(false).setPositiveButton(R.string.grantAccess) { _, _ -> Utils.requestExternalStorageRwPermission(this, REQUEST_ASK_FOR_PERMISSION) }.setNegativeButton(R.string.continueWithout) { dialog, _ -> dialog.cancel() Toast.makeText(this, "Allow permission for storage access!", Toast.LENGTH_SHORT).show() }.show() } // We're temporarily suppressing the warning for startActivityForResult being deprecated. // Issue: https://github.com/PSPDFKit/PSPDFKit/issues/31881 @Suppress("DEPRECATION") private fun showOpenFileDialog() { // Prepare an implicit intent which allows the user to select any document. val intent = Intent(Intent.ACTION_OPEN_DOCUMENT) intent.addCategory(Intent.CATEGORY_OPENABLE) intent.type = "*/*" // We accept PDF files and images (for image documents). intent.putExtra(Intent.EXTRA_MIME_TYPES, arrayOf("application/pdf", "image/*")) // Set of the intent for result, so we can retrieve the Uri of the selected document. startActivityForResult(intent, REQUEST_OPEN_DOCUMENT) } companion object { internal const val EXTRA_CONFIGURATION = "Nutrient.ExternalExampleActivity.configuration" private const val REQUEST_OPEN_DOCUMENT = 1 private const val REQUEST_ASK_FOR_PERMISSION = 2 private const val IS_WAITING_FOR_RESULT = "Nutrient.ExternalExampleActivity.waitingForResult" private const val DOWNLOAD_PROGRESS_FRAGMENT = "DownloadProgressFragment" } } ``` This code sample is an example that illustrates how to use our SDK. Please adapt it to your specific use case. --- ## Related pages - [Application Policy](/guides/android/samples/application-policy-kotlin.md) - [Custom Form Highlight Color](/guides/android/samples/custom-form-highlight-color-java.md) - [Custom Page Templates](/guides/android/samples/custom-page-templates-java.md) - [Digital Signature (Basic)](/guides/android/samples/digital-signature-basic-kotlin.md) - [Disabled Annotation Property](/guides/android/samples/disabled-annotation-property-java.md) - [Image Document](/guides/android/samples/image-document-kotlin.md) - [Compose Image Document](/guides/android/samples/compose-image-document-kotlin.md) - [Inline Multimedia](/guides/android/samples/inline-multimedia-kotlin.md) - [JavaScript Form Filling](/guides/android/samples/javascript-form-filling-kotlin.md) - [Overlay Visibility](/guides/android/samples/overlay-visibility-kotlin.md) - [PdfFragment](/guides/android/samples/pdffragment-kotlin.md) - [Reader View](/guides/android/samples/reader-view-kotlin.md) - [Playground](/guides/android/samples/playground-kotlin.md) - [JavaScript Calculator](/guides/android/samples/javascript-calculator-kotlin.md) - [Text Field Suggestions](/guides/android/samples/text-field-suggestions-kotlin.md) - [Thumbnail Bar Modes](/guides/android/samples/thumbnail-bar-modes-kotlin.md) - [Signature Storage Database](/guides/android/samples/signature-storage-database-kotlin.md) - [Selection Customization](/guides/android/samples/selection-customization-java.md) - [Password Protected PDF](/guides/android/samples/password-protected-pdf-kotlin.md) - [Scientific Paper](/guides/android/samples/scientific-paper-kotlin.md) - [Try Instant](/guides/android/samples/try-instant-kotlin.md) - [Merge Documents](/guides/android/samples/merge-documents-kotlin.md) - [Annotation Rendering](/guides/android/samples/annotation-rendering-kotlin.md) - [Custom Data Provider](/guides/android/samples/custom-data-provider-kotlin.md) - [Annotations with Transparency](/guides/android/samples/annotations-with-transparency-kotlin.md) - [Annotation Flags](/guides/android/samples/annotation-flags-kotlin.md) - [AI Assistant (Multiple Documents, ViewPager)](/guides/android/samples/ai-assistant-multiple-documents-viewpager-kotlin.md) - [Custom Sharing Menu](/guides/android/samples/custom-sharing-menu-java.md) - [Add LTV to Existing Signature](/guides/android/samples/add-ltv-to-existing-signature-kotlin.md) - [Custom Toolbar Grouping](/guides/android/samples/custom-toolbar-grouping-java.md) - [Custom Layout](/guides/android/samples/custom-layout-kotlin.md) - [Custom ActionBar Actions](/guides/android/samples/custom-actionbar-actions-kotlin.md) - [Custom Activity Toolbars](/guides/android/samples/custom-activity-toolbars-java.md) - [Custom Note Hinter](/guides/android/samples/custom-note-hinter-kotlin.md) - [Custom Main Toolbar](/guides/android/samples/custom-main-toolbar-kotlin.md) - [Annotation Configuration](/guides/android/samples/annotation-configuration-kotlin.md) - [Annotation Selection Styling](/guides/android/samples/annotation-selection-styling-kotlin.md) - [Custom Search UI (Compose)](/guides/android/samples/custom-search-ui-compose-kotlin.md) - [Document Switcher](/guides/android/samples/document-switcher-java.md) - [File Annotation Creation](/guides/android/samples/file-annotation-creation-kotlin.md) - [Dynamic Pages on Scroll](/guides/android/samples/dynamic-pages-on-scroll-kotlin.md) - [Custom Activity Form Editing](/guides/android/samples/custom-activity-form-editing-java.md) - [Custom Stamp Annotations](/guides/android/samples/custom-stamp-annotations-java.md) - [Custom Outline Provider](/guides/android/samples/custom-outline-provider-kotlin.md) - [Compose Navigation](/guides/android/samples/compose-navigation-kotlin.md) - [Fragment Runtime Configuration](/guides/android/samples/fragment-runtime-configuration-kotlin.md) - [Annotation Overlay](/guides/android/samples/annotation-overlay-java.md) - [Instant Document JSON](/guides/android/samples/instant-document-json-kotlin.md) - [DocumentView Composable](/guides/android/samples/documentview-composable-kotlin.md) - [Form Creation](/guides/android/samples/form-creation-kotlin.md) - [Document Download](/guides/android/samples/document-download-kotlin.md) - [JavaScript Actions](/guides/android/samples/javascript-actions-kotlin.md) - [Instant JSON Attachment](/guides/android/samples/instant-json-attachment-kotlin.md) - [Digital Signature (Manual)](/guides/android/samples/digital-signature-manual-kotlin.md) - [Digital Signature (Third-Party)](/guides/android/samples/digital-signature-third-party-kotlin.md) - [Inline Search](/guides/android/samples/inline-search-java.md) - [Form Filling](/guides/android/samples/form-filling-kotlin.md) - [Form Click Intercept (Compose)](/guides/android/samples/form-click-intercept-compose-kotlin.md) - [Document Sharing](/guides/android/samples/document-sharing-java.md) - [Custom Download Dialog](/guides/android/samples/custom-download-dialog-java.md) - [Download Progress](/guides/android/samples/download-progress-kotlin.md) - [Popup Toolbar Customization](/guides/android/samples/popup-toolbar-customization-kotlin.md) - [Custom Sharing Dialog](/guides/android/samples/custom-sharing-dialog-java.md) - [PDF from Image](/guides/android/samples/pdf-from-image-kotlin.md) - [Digital Signature (Two-Step)](/guides/android/samples/digital-signature-two-step-kotlin.md) - [Remote URL](/guides/android/samples/remote-url-kotlin.md) - [PdfUiFragment](/guides/android/samples/pdfuifragment-kotlin.md) - [Runtime Configuration](/guides/android/samples/runtime-configuration-kotlin.md) - [Sound Extraction](/guides/android/samples/sound-extraction-kotlin.md) - [Document from Canvas](/guides/android/samples/document-from-canvas-kotlin.md) - [Tabbed Documents](/guides/android/samples/tabbed-documents-kotlin.md) - [Watermarks](/guides/android/samples/watermarks-kotlin.md) - [Programmatic Zoom](/guides/android/samples/programmatic-zoom-kotlin.md) - [Signature Parcelize](/guides/android/samples/signature-parcelize-kotlin.md) - [OCR](/guides/android/samples/ocr-kotlin.md) - [Vertical Scrollbar](/guides/android/samples/vertical-scrollbar-java.md) - [Split View](/guides/android/samples/split-view-java.md) - [XFDF Import/Export](/guides/android/samples/xfdf-import-export-kotlin.md) - [UI View Modes](/guides/android/samples/ui-view-modes-kotlin.md) - [LTV Signature](/guides/android/samples/ltv-signature-kotlin.md) - [Bookmark Highlighting](/guides/android/samples/bookmark-highlighting-kotlin.md) - [Custom Annotation Inspector](/guides/android/samples/custom-annotation-inspector-java.md) - [Annotation Sidebar](/guides/android/samples/annotation-sidebar-kotlin.md) - [AI Assistant (Single Document)](/guides/android/samples/ai-assistant-single-document-kotlin.md) - [AI Assistant (Multiple Documents, Compose)](/guides/android/samples/ai-assistant-multiple-documents-compose-kotlin.md) - [Document Comparison](/guides/android/samples/document-comparison-kotlin.md) - [Document Processing](/guides/android/samples/document-processing-kotlin.md) - [Custom Annotation Creation Toolbar](/guides/android/samples/custom-annotation-creation-toolbar-java.md) - [Custom Electronic Signature](/guides/android/samples/custom-electronic-signature-java.md) - [E-Learning](/guides/android/samples/e-learning-kotlin.md) - [Electronic + Digital Signing](/guides/android/samples/electronic-digital-signing-kotlin.md) - [Generate PDF Report](/guides/android/samples/generate-pdf-report-kotlin.md) - [Multimedia Annotations](/guides/android/samples/multimedia-annotations-kotlin.md) - [Forms with JavaScript](/guides/android/samples/forms-with-javascript-kotlin.md) - [Overlay Views](/guides/android/samples/overlay-views-kotlin.md) - [Kiosk Grid](/guides/android/samples/kiosk-grid-kotlin.md) - [Search Indexing](/guides/android/samples/search-indexing-kotlin.md) - [Annotation Creation](/guides/android/samples/annotation-creation-kotlin.md) - [Filterable Thumbnail Grid](/guides/android/samples/filterable-thumbnail-grid-kotlin.md) - [Tabbed Documents (Persistent)](/guides/android/samples/tabbed-documents-persistent-kotlin.md) - [Measurement Tools](/guides/android/samples/measurement-tools-kotlin.md) - [HTML-to-PDF Conversion](/guides/android/samples/html-to-pdf-conversion-kotlin.md) - [AES Encrypted File](/guides/android/samples/aes-encrypted-file-java.md) - [Construction Floor Plan](/guides/android/samples/construction-floor-plan-kotlin.md) - [Hide and Reveal Areas](/guides/android/samples/hide-and-reveal-areas-kotlin.md) - [Multiple Documents (Compose Pager)](/guides/android/samples/multiple-documents-compose-pager-kotlin.md) - [Screen Reader](/guides/android/samples/screen-reader-java.md) - [Custom Search UI (Views)](/guides/android/samples/custom-search-ui-views-java.md)