PSPDFKit 6 Migration Guide
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.
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.
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.
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.
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
saveAnnotationsWithCompletionBlock: has been unified with
saveWithCompletionHandler:. These methods can safely be replaced with their new unified variants.
We streamlined the use of
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
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.
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.
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.
The stylus driver protocol
PSPDFStylusDriver doesn't extend
PSPDFPlugin anymore. To update your stylus drivers you need to:
- update the designated initializer to
- change the name of
- update keys in your
PSPDFPluginProtocolVersionKeyshould be removed.
Your stylus drivers have to be registered with
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
If you want to provide your custom implementation for the following
id<PSPDFFileManager> fileManagerand coordinated file manager
You can pass your own instances in the
options dictionary with
+[PSPDFKit setLicenseKey:options:] using the following keys:
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.