PSPDFKit 6 Migration Guide | iOS

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 across 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 isn’t officially supported.

Deprecations

As PSPDFKit 6 for iOS is 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 you were previously using marked as deprecated, check out the message and the header of the class.

Breaking Changes

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

Below you’ll find a list of these changes, along with 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 it’s still worth mentioning, since missing it could crash your app or get you rejected. It’s easy to add — see our permissions guide for details.

Document Saving

We unified our document-saving logic so that there are only two methods on PSPDFDocument to save a document, annotations, and bookmarks, and there are 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 conventions of Swift 3.

Rendering and Caching

We redesigned our APIs when it comes to rendering and caching to simplify use and improve performance. Throughout the next year, we’ll continue making performance improvements 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’s a good chance you’ll have to update your code to use PSPDFKit 6. Additionally, PSPDFKit now automatically chooses the best rendering mode for you, so the renderingMode property on PSPDFConfiguration is no longer needed and has been removed. Look at the two most relevant changes below; if you need more details on the rendering and caching changes, look at the rendering and caching guide.

Requesting an Image

PSPDFRenderJob is no longer available, and requesting an image is now a two-step process. First, configure a PSPDFRenderRequest and specify the parameters of the image you’re 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 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 quickly if one is available. Most people who 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 remove the first part and immediately create a render request and schedule a render task with this.

Plugins

The PSPDFPlugin API has been removed.

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

Stylus Drivers

The PSPDFStylusDriver stylus driver protocol doesn’t extend PSPDFPlugin anymore. To update your stylus drivers:

  • 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 and PSPDFPluginProtocolVersionKey should be removed.

Your stylus drivers have to be registered with the PSPDFKitGlobal.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. Let us know if you relied on custom implementation.

Other Components That Used to Conform to PSPDFPlugin

You may want to provide your custom implementation for the following PSPDFKit components:

  • id<PSPDFFileManager> fileManager and coordinated file manager

  • id<PSPDFApplicationPolicy> policy

If so, you can pass your own instances in the options dictionary with +[PSPDFKitGlobal setLicenseKey:options:] using the following keys: PSPDFApplicationPolicyKey, PSPDFFileManagerKey, and PSPDFCoordinatedFileManagerKey.

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

Framework Headers

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