PSPDFKit 6.0 Migration Guide

PSPDFKit 6 for iOS is our latest framework update.

iOS and Xcode Requirements

With PSPDFKit 6 for iOS, we dropped support for iOS 8. We follow our usual pattern of supporting n-1 major iOS versions, which currently spans iOS 9.0, 9.1, 9.2, 9.3 and 10.0. This build also requires Xcode 8. Xcode 8 runs on macOS 10.11 or 10.12, and we recommend macOS Sierra 10.12 or higher.

If you require support for iOS 8, we updated PSPDFKit 5 with more iOS 10 related fixes and you’re free to continue using this version until you can drop the old OS requirements. Note that PSPDFKit 5 works best with Xcode 7.3.1 and building it with Xcode 8 is not officially supported.

Deprecations

With PSPDFKit 6 for iOS being a major release, previously deprecated methods have been removed. While working on new features and improvements, we added new deprecations throughout the SDK. These deprecations include a message, telling you what to use instead. If you find some of the methods that you were previously using marked deprecated, check out this message and the header of the class.

Breaking Changes

Besides the deprecations, we also worked on a couple of features that fundamentally change the way things work, which makes deprecating the old API no longer practical and would have had an impact on the new API. As we believe the current API should be the best one possible, there are some cases where we introduced breaking changes. We tried to keep the amount of breaking changes at a minimum and do as many of these in this major release as possible, so that you only need to migrate things once. We put great effort in designing the new APIs so that we can keep improving the underlying components throughout the next year without any other breaking changes and we will do our best to stick with this approach.

Please find below a list of these changes as well as instructions on how to migrate your existing code.

Permissions

iOS 10 requires new keys in the Info.plist if you compiled with Xcode 8. This is a change by Apple but still worth mentioning, since missing that could crash your app or get you rejected. It's easy to add - see our permission documentation page for details.

Document Saving

We unified our document saving logic so there are only two methods on PSPDFDocument to save the document, annotations and bookmarks and no extra methods for annotation saving. saveAnnotationsWithError: has been integrated into save: and saveAnnotationsWithCompletionBlock: has been unified with saveWithCompletionHandler:. These methods can safely be replaced with their new unified variants.

Page Index

We streamlined the use of page, pageIndex and other similar wordings. All the properties and parameters that deal with page numbers now use the wording pageIndex. This clarifies that the parameter is not a page object of some sort, but, rather, the index that identifies a given page. It also plays nicely with the naming convention of Swift 3.

Rendering and Caching

We redesigned our API when it comes to rendering and caching to simplify the usage and improve performance. Throughout the next year, we will continue making performance improvements under the hood that have been made possible by these changes. If you don’t do any custom rendering or caching, there are no changes required to make use of this. However, if you previously made calls to PSPDFRenderQueue, PSPDFRenderJob, or PSPDFCache yourself, then there is a good chance that you will have to update your code in order to use PSPDFKit 6. Additionally, PSPDFKit now chooses the best rendering mode automatically for you, so the renderingMode property on PSPDFConfiguration is no longer needed and has been removed. Please have a look at the two most relevant changes below, if you need more details on the rendering and caching changes, take a look at the Rendering and Caching guide.

Requesting an Image

PSPDFRenderJob is no longer available and requesting an image now is a two-step process. First, you configure a PSPDFRenderRequest and specify the parameters of the image you are requesting. Then, create a PSPDFRenderTask with this request and hand it over to the queue. The task is used to influence the actual rendering by things like the priority of the request or by canceling a task you no longer need.

Caching

The changes to PSPDFCache are of a similar nature: Instead of passing a number of parameters to the cache directly, you now use the same PSPDFRenderRequest and pass it to the cache in order to get a cached image. The biggest change, however, is that the cache no longer is another module next to the render queue; instead, now the render queue accesses the cache automatically. So for most requests, you no longer need to access the cache directly; rather, always schedule a render task and the render queue will make sure to serve you with a cached image really quickly if there is one available. Most people that used the cache previously have code that first checks the cache and if the cache didn’t provide the required data, they scheduled a render job. With PSPDFKit 6 you most likely can simply remove the first part and immediately create a render request and schedule a render task with this.

Plugins

PSPDFPlugin API has been removed.

Dynamic plugin lookup had noticeable impact on app launch time, especially in bigger apps. Therefore, we decided to remove it in favor of explicit configuration patterns. We believe this gives the API more clarity and predictability.

Stylus Drivers

The stylus driver protocol PSPDFStylusDriver doesn't extend PSPDFPlugin anymore. To update your stylus drivers you need to:

  • update the designated initializer to - (instancetype)initWithDelegate:(id<PSPDFStylusDriverDelegate>)delegate,
  • change the name of pluginInfo method to driverInfo,
  • update keys in your driverInfo dictionary - PSPDFPluginIdentifierKey becomes PSPDFStylusDriverIdentifierKey and PSPDFPluginIdentifierKey, PSPDFPluginProtocolVersionKey should be removed.

Your stylus drivers have to be registered with PSPDFKit.sharedInstance.stylusManager.availableDriverClasses property.

With the previous plugin architecture you could provide your own instance of PSPDFStylusManager, which is now no longer needed because our default implementation should cover all scenarios. Please let us know if you relied on custom implementation.

Other components that used to conform to PSPDFPlugin

If you want to provide your custom implementation for the following PSPDFKit components:

  • id<PSPDFFileManager> fileManager and coordinated file manager
  • id<PSPDFApplicationPolicy> policy

You can pass your own instances in the options dictionary with +[PSPDFKit setLicenseKey:options:] using the following keys: PSPDFApplicationPolicyKey, PSPDFFileManagerKey, PSPDFCoordinatedFileManagerKey.

PSPDFMultimediaViewController used to support plugin architecture. Now you can customize it by subclassing PSPDFGalleryViewController and registering your subclass.

Framework Headers

We recommend you to include our framework in your app using the umbrella header #import <PSPDFKit/PSPDFKit.h> or via the module @import PSPDFKit. We don't recommend you to include one or more individual files on their own.