Document Sharing

PSPDFKit allows you to securely share PDF documents with other apps via the DocumentSharingManager which provides several static methods for that purpose. Shared documents are served by the DocumentSharingProvider which is automatically registered at build time using the authority ${applicationId}.pdf.share (where applicationId is defined by your app's build.gradle).

Document Sharing

You can use #shareDocument(Context, PdfDocument, ShareAction) to share a loaded document with any other app supporting the PDF document format. If you want to share with an app supporting PDF sending (usually messengers, cloud providers, file managers, ...) call the method providing the ShareAction.SEND. If you want to launch an app for viewing instead, you can use the ShareAction.VIEW.

Copy
1
2
// Show the activity picker listing apps that can "send PDF files".
DocumentSharingManager.shareDocument(context, document, ShareAction.SEND)
Copy
1
2
// Show the activity picker listing apps that can "send PDF files".
DocumentSharingManager.shareDocument(context, document, ShareAction.SEND);

Sharing Options

The DocumentSharingManager has overloaded sharing methods that accept SharingOptions which let you specify the title of the shared document and document processing options for flattening or removing annotations on the shared document or extracting a range of pages.

Copy
1
2
3
// The title of the document has to be specified without the file extension.
val options = SharingOptions("Custom Document Title")
DocumentSharingManager.shareDocument(context, document, ShareAction.SEND, options)
Copy
1
2
3
// The title of the document has to be specified without the file extension.
final SharingOptions options = new SharingOptions("Custom Document Title");
DocumentSharingManager.shareDocument(context, document, ShareAction.SEND, options);

You can decide to flatten or remove all annotations on the shared document by defining a AnnotationProcessingMode within the sharing options.

Copy
1
2
3
// Flatten all existing annotations on the shared document.
val options = SharingOptions(AnnotationProcessingMode.FLATTEN)
DocumentSharingManager.shareDocument(context, document, ShareAction.VIEW, options)
Copy
1
2
3
// Flatten all existing annotations on the shared document.
final SharingOptions options = new SharingOptions(AnnotationProcessingMode.FLATTEN);
DocumentSharingManager.shareDocument(context, document, ShareAction.VIEW, options);

If you like to share only a portion of a document, the SharingOptions let you specify one or multiple page ranges that should be extracted before sharing.

Copy
1
2
3
4
5
// Share pages 0, 4, 5.
val pages = listOf(Range(0,1), Range(4,2))
// Delete all existing annotations from the shared document.
val options = SharingOptions(AnnotationProcessingMode.DELETE, pages)
DocumentSharingManager.shareDocument(context, document, ShareAction.VIEW, options)
Copy
1
2
3
4
5
// Share pages 0, 4, 5.
final List<Range> pages = Arrays.asList(new Range(0,1), new Range(4,2));
// Delete all existing annotations from the shared document.
final SharingOptions options = new SharingOptions(AnnotationProcessingMode.DELETE, pages);
DocumentSharingManager.shareDocument(context, document, ShareAction.VIEW, options);

Sharing Dialog

The DocumentSharingDialog is a ready-to-use dialog for letting users define the desired SharingOptions prior to sharing.

Following is a small sample showing how to use the dialog. You can find a full example inside the DocumentSharingExample of our catalog app.

Copy
Activity.kt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
val listener : (SharingOptions) -> Unit = {
    DocumentSharingManager.shareDocument(
        this,
        document,
        ShareAction.VIEW,
        // Use share options configured in share dialog.
        it)
}

override fun onResume() {
    super.onResume()
    // As sharing dialog listener can't be retained, restore it in dialog after configuration changes.
    DocumentSharingDialog.restore(supportFragmentManager, listener)
}

private fun showSharingDialog() {
    // Build dialog configuration.
    val configuration = DocumentSharingDialogConfiguration.Builder(this, document, page)
        .dialogTitle("Custom sharing dialog title")
        .positiveButtonText("View")
        .build()

    // Show sharing dialog.
    DocumentSharingDialog.show(supportFragmentManager, configuration, listener)
}
Copy
MyActivity.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
private SharingDialogListener listener = new SharingDialogListener() {
    @Override
    public void onAccept(@NonNull SharingOptions shareOptions) {
        DocumentSharingManager.shareDocument(
                DocumentSharingExampleActivity.this,
                getDocument(),
                ShareAction.VIEW,
                // Use share options configured in share dialog.
                shareOptions);
    }
};

@Override protected void onResume() {
    super.onResume();
    // As sharing dialog listener can't be retained, restore it in dialog after configuration changes.
    DocumentSharingDialog.restore(getSupportFragmentManager(), listener);
}

private void showSharingDialog() {
    // Build dialog configuration.
    final DocumentSharingDialogConfiguration configuration =
            new DocumentSharingDialogConfiguration.Builder(this, getDocument(), getPage())
                .dialogTitle("Custom sharing dialog title")
                .positiveButtonText("View")
                .build();

    // Show sharing dialog.
    DocumentSharingDialog.show(getSupportFragmentManager(), configuration, listener);
}

Sharing Action

The PdfActivity provides a sharing action using the same sharing API described in this article. The action is enabled by default and can be used by simply tapping it. You can disable sharing within the PdfActivity using the method PdfActivityConfiguration.Builder#disableShare.

Copy
1
2
3
4
5
6
// Create a default configuration with sharing disabled.
val config = PdfActivityConfiguration.Builder(context)
    .disableShare()
    .build()

PdfActivity.showDocument(context, documentUri, config)
Copy
1
2
3
4
5
6
// Create a default configuration with sharing disabled.
final PdfActivityConfiguration config = new PdfActivityConfiguration.Builder(context)
    .disableShare()
    .build();

PdfActivity.showDocument(context, documentUri, config);

Bypassing the Sharing Dialog

By default our PdfActivity shows the DocumentSharingDialog whenever the share action is used. If you want to bypass the ialog you can provide a SharingOptionsProvider that creates SharingOptions using PdfActivity#setSharingOptionsProvider.

Copy
1
2
3
4
5
// Inside your activity.
setSharingOptionsProvider { document, currentPage ->
    // We always share the entire document, flattening the annotations.
    SharingOptions(PdfProcessorTask.AnnotationProcessingMode.FLATTEN)
}
Copy
1
2
3
4
5
6
7
8
9
// Inside your activity.
setSharingOptionsProvider(new SharingOptionsProvider() {
    @Nullable
    @Override
    public SharingOptions createSharingOptions(@NonNull PdfDocument document, int currentPage) {
        // We always share the entire document, flattening the annotations.
        return new SharingOptions(PdfProcessorTask.AnnotationProcessingMode.FLATTEN);
    }
});