PSPDFAnnotationProvider 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
PSPDFDocumentProvider, each of which has one
PSPDFAnnotationManager, which, in turn, contains one or more annotation providers.
By default, the
annotationProviders array simply contains the
fileAnnotationProvider. This provider will parse the PDF and load annotations from it, and it will also handle saving back into the PDF, subject to the value of
The file annotation provider also handles our internal
NSCoder-based format for saving and loading annotations. This is an internal file format, and it should not be used for long-term storage of annotations. PSPDFKit usually supports loading and saving using this format at least one version back. So, for example, v4 can load v3 but not v2 or v5.
Transferring Annotations to Other Clients
Annotations are only useful if they can be shared across multiple clients. In order to do this, there are several options available, detailed below.
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 shortly after the 1.0 release). 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.
Annotations can be exported to JSON and imported back from it at a later time. Use the
PSPDFJSONAdapter class with
JSONDictionaryFromModel: to convert a
PSPDFAnnotation object to a JSON dictionary, and convert it back using
PSPDFAnnotation. Please take a look at the Exporting to/Importing from JSON guide for more details.
ℹ️ Note: The
PSPDFModel-based JSON serialization is iOS specific and is not compatible with PSPDFKit for Web or Android. It has been deprecated since PSPDFKit 7.2 for iOS in favor of Instant JSON, our cross-platform format.
XFDF is an XML-like standard from Adobe XFDF used for encoding annotations and forms (see this XFDF overview). It is compatible with Adobe Acrobat and several other third-party frameworks. PSPDFKit supports both reading and writing XFDF and also offers a
PSPDFXFDFAnnotationProvider subclass that will save/load annotations to/from XFDF automatically. There are several examples in PSPDFCatalog and in our XFDF Support guide that show the exact usage. XFDF can be used in combination with
PSPDFAESCryptoOutputStream 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 the file very large.
PSPDFAnnotationProvider 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 very specific use case, take a look at the
PSPDFContainerAnnotationProvider subclass. The latter implements several of the harder-to-get-right details of the annotation provider protocol.