How to Embed Files Using File Annotations

With PSPDFKit 4.6 for Android, PSPDFKit 7.6 for iOS, and PSPDFKit 2.6 for macOS, we added the ability to create embedded files using file annotations.

You can embed any file type. You can even embed a PDF, which embeds another PDF, which, in turn, embeds a PDF, and so on.

Embedding files can be a handy feature for various business cases. For example, you can embed an Excel document in your monthly report (a PDF document). Your recipients can then preview and open a copy in another application such as Microsoft Excel; they can even make changes to the Excel document and send it back to you.

In this article, we’ll discuss how to preview and open embedded files and how to programmatically embed an Excel document into a PDF using file annotations. Let’s get started!

Preview and Open Embedded Files

You can preview file attachments directly in PSPDFKit.

You can then open a copy in third-party applications or, on iOS, open it in Apple’s Files app using the share action.

Programmatically Create a File Annotation with an Embedded File

You can create a file annotation with an embedded file using the URL of any file. Here’s how this looks in code:

Android

// Open PdfDocument.
val document = PdfDocument.openDocument(context, uri)

// Create an embedded file source serving file data from assets.
val embeddedFileSource = EmbeddedFileSource(
    AssetDataProvider("Monthly Budget"),
    "Monthly Budget.xlsx",
    "Monthly Budget"
)

// Create a file annotation instance.
val fileAnnotation = FileAnnotation(
    // Page index 0.
    0,
    // Page rectangle (in PDF coordinates).
    RectF(500f, 250f, 532f, 218f),
    // Use the created embedded file source.
    embeddedFileSource
)
fileAnnotation.iconName = FileAnnotation.GRAPH
fileAnnotation.color = Color.BLUE

// Add the newly created file annotation to the document.
document.annotationProvider.addAnnotationToPage(fileAnnotation)

iOS

// Create PSPDFDocument.
let document = PSPDFDocument(url: documentURL)

// Create the URL of the appearance stream that uses a PDF file.
let samplesURL = Bundle.main.resourceURL!.appendingPathComponent("Samples")
let embeddedFileURL = samplesURL.appendingPathComponent("Monthly Budget.xlsx")

// Create a new file annotation and set its properties.
let fileAnnotation = PSPDFFileAnnotation()
fileAnnotation.pageIndex = 0
fileAnnotation.iconName = .graph
fileAnnotation.color = .blue
fileAnnotation.boundingBox = CGRect(x: 500, y: 250, width: 32, height: 32)

// Create an embedded file and add it to the file annotation.
let embeddedFile = PSPDFEmbeddedFile(fileURL: embeddedFileURL, fileDescription: "Monthly Budget")
fileAnnotation.embeddedFile = embeddedFile

// Add the newly created annotation to the document.
document.add([fileAnnotation])

To learn more about how to programmatically create file annotations with embedded files, check out FileAnnotationCreationExample on Android and AddFileAnnotationProgrammaticallyExampleon iOS inside the Catalog apps, or review the in-depth guide articles on iOS and Android.

Create a File Annotation with an Embedded File from the UI

In addition to the above, you can also create a file annotation from a UI element. We’ve added the AddFileAnnotationWithEmbeddedFileExample example in the Catalog app to illustrate how to do it using a custom menu. We also plan on building the ability to create file annotations from the UI (annotation toolbar, menu item, etc.) into our SDKs in a future update. Stay tuned!