Annotation Saving Mechanism

By default, the annotationSaveMode of PSPDFDocument is set to PSPDFAnnotationSaveModeEmbeddedWithExternalFileAsFallback. This means, PSPDFKit will analyze the PDF and see if it can write annotations into it, and if that fails, an external file format will be used to save annotations.

PSPDFKit can write annotations into the PDF under following conditions:

  • The PDF is not password protected. (Note: Some PDFs are protected with an empty password, just to make sure they can’t be modified. PSPDFKit will auto-unlock those, but can’t add annotations in that case.)
  • The PDF must be in a writable location. This is pretty much every folder except the application bundle folder, since that one is signed. If you pre-populate PDFs with your app, they will be in the app bundle and thus not writable. Copy them to the documents folder to make them writable.
  • The PDF must be valid according to the Adobe PDF Spec. Some PDFs are broken, but still work somewhat so PSPDFKit can render the content. If PSPDFKit detects a mismatch in the object tree or is unable to find objects, external annotation saving will be stopped, since there would be a risk of damaging the document.

If annotations can’t be saved, PSPDFKit uses an internal file format with the default location in /Library/PrivateDocuments/annotations.pspdfkit. This file is only intended for internal use. Don’t upload this to your web server as the file format is subject to change.

PSPDFKit will save “dirty” (changed/created/deleted) annotations on several occasions. Learn more about these triggers here.

Read more about Annotation Providers here.