Open a PDF file from Document Engine on Android

Document Engine is an optional backend for Nutrient Android SDK. Its Instant synchronization component synchronizes annotations across users and devices.

Use the Instant API to display server-hosted documents and manage their lifecycle.

API overview

InstantClient represents a connection to Document Engine. An app typically creates one client, but it can create several to connect to multiple Document Engine instances.

Instant downloads and stores PDFs at your app’s request. A documentId identifies each PDF. Each PDF can have multiple named layers, each containing a separate set of annotations over the base document. For details, refer to the Instant layers guide.

An InstantDocumentDescriptor represents a layer in your app. To create a descriptor, follow these steps:

1. Obtain a JSON Web Token (JWT) for the layer from your server.
2. Call getInstantDocumentDescriptorForJwt() on your InstantClient.

Use the descriptor to download the PDF and the layer’s annotations. After downloading, create an InstantPdfDocument, set the document on an InstantPdfFragment, and display the fragment in your app.

Alternatively, provide the Document Engine URL and JWT to InstantPdfActivity. The activity downloads and opens the document. Instant synchronizes annotation changes across users viewing the same document.

The Instant UI classes extend the standard viewer classes:

• InstantPdfFragment extends PdfFragment.
• InstantPdfActivity extends PdfActivity.

Both Instant UI classes display only InstantPdfDocument instances. Passing a standard PdfDocument throws an exception. Likewise, display Instant documents only in activities or fragments that extend the corresponding Instant UI class.

Document lifecycle

An Instant document’s lifecycle can include these stages:

• Obtaining a document identifier from your server
• Obtaining a document descriptor
• Downloading the document
• Showing the document and synchronizing annotations
• Updating the authentication token to keep synchronizing annotations
• Losing access to the document
• Clearing local storage

Usage in detail

To download and open a document, follow these steps:

1. Sign in to your server.
2. Obtain the document identifier.
3. Request a JSON Web Token (JWT) for the document from your server.
4. Use the JWT to download and open the document.

The following example starts the download:

val serverUrl = "location of your Document Engine here"
val jwt = "some JWT from your server identifying document layer"

// Downloads and opens the document layer encoded by the JWT.
InstantClient.create(context, serverUrl).openDocumentAsync(jwt).subscribe(...)

String serverUrl = "location of your Document Engine here";
String jwt = "some JWT from your server identifying document layer";

// Downloads and opens the document layer encoded by the JWT.
InstantClient.create(context, serverUrl).openDocumentAsync(jwt).subscribe(...);

Choose one of these options to display the document and synchronize annotations:

• Start an InstantPdfActivity with showInstantDocument().
• Create an InstantPdfFragment with newInstance().

The following example demonstrates both options. Display the fragment in your layout if you choose that option:

// Starts the activity. `activityConfiguration` is a `PdfActivityConfiguration`.
InstantPdfActivity.showInstantDocument(context, serverUrl, jwt, activityConfiguration)

val fragment = InstantPdfFragment.newInstance(serverUrl, jwt, activityConfiguration.configuration)
// Display a fragment inside your layout.

// Starts the activity. `activityConfiguration` is a `PdfActivityConfiguration`.
InstantPdfActivity.showInstantDocument(context, serverUrl, jwt, activityConfiguration);

InstantPdfFragment fragment = InstantPdfFragment.Companion.newInstance(serverUrl, jwt, activityConfiguration.getConfiguration());
// Display a fragment inside your layout.

Instant doesn’t persist JWTs. When a JWT expires, Instant reports InstantErrorCode.AUTHENTICATION_FAILED. Update the open document’s JWT with InstantPdfDocument#reauthenticateWithJwt(token).

Your app might learn from your server or Document Engine that a user no longer has access to a document. Stop displaying the document when access ends. Clear local storage with pdfDocument.getInstantClient().removeLocalStorageForDocument(pdfDocument.getInstantDocumentDescriptor().getDocumentId()). Here, pdfDocument is the InstantPdfDocument.