Save PDF Annotations to External Storage on iOS

PSPDFKit enables you to save and store annotations in an external file even if a PDF file is writable. Saving annotations to external files is handy for use cases where you have multiple users that should each have their own set of annotations but the original file shouldn’t be modified.

Using the External File Annotation Save Mode

The easiest way to save annotations to an external file is to set your Document’s annotationSaveMode property to .externalFile, like so:

let document = ...
document.annotationSaveMode = .externalFile

When saving annotations to an external file, PSPDFKit will save the file in /Library/PrivateDocuments/annotations.pspdfkit, with annotations serialized in an NSCoder-based format.

ℹ️ Note: This file is only intended for internal use. Don’t upload this to your web server, as the file format is subject to change. This is an internal file format, and it shouldn’t be used for long-term storage of annotations.

Using Instant Sync

PSPDFKit Instant is our in-house syncing solution for seamless collaboration for PSPDFKit-powered apps. It not only takes care of near-real-time annotation syncing, but it also manages file downloads and other metadata, such as bookmarks (which will be available in a future update). Instant is highly optimized for PSPDFKit and uses a deep API integration, which is faster and more reliable than anything you can achieve writing your own code.

Annotation Providers

The AnnotationProvider protocol defines methods for getting and setting annotations. PSPDFKit is structured in such a way that a document can have several of these providers. Each document has one or more instances of PDFDocumentProvider, each of which has one AnnotationManager, which, in turn, contains one or more annotation provider(s).

By default, the annotationProviders array contains the fileAnnotationProvider. This provider will parse a PDF and load annotations from it, and it’ll also handle saving back into the PDF, subject to the value of annotationSaveMode.

The file annotation provider also handles our internal NSCoder-based format for saving and loading annotations.

Using an XFDF Annotation Provider

XFDF is an XML-based standard from Adobe XFDF used for encoding annotations and form field values. An XFDF file will contain a snapshot of a PDF document’s annotations and form field values. It doesn’t include the form elements or the form fields themselves — only the filled values. It’s compatible with Adobe Acrobat and several other third-party frameworks. PSPDFKit supports both reading and writing XFDF, and it also offers an XFDFAnnotationProvider subclass that will save/load annotations to/from XFDF automatically. There are several examples in the PSPDFKit Catalog and in our XFDF Support guide that show the exact use. XFDF can be used in combination with AESCryptoInputStream and AESCryptoOutputStream to build an encrypted annotation store. Please note that XFDF is problematic for binary attachments such as sound annotations and images, which are saved inline and might make a file large.

Using a Custom Annotation Provider

The AnnotationProvider protocol can also be implemented to have fully custom saving and loading. This is an advanced method, and we recommend using PSPDFKit Instant instead. However, if you have a specific use case, take a look at the PDFContainerAnnotationProvider subclass, which implements several of the harder-to-get-right details of the annotation provider protocol.

Importing and Exporting Using the Instant JSON Format

Instant JSON is our approach to bringing annotations into a modern format. It’s compatible with our SDK on all platforms while keeping all important properties to make the Instant JSON spec work with PDFs. It’s fully documented and supports long-term storage. Please take a look at the Instant JSON guide for more details.