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 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.
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.
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.
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.
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
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 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
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. Please 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.
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.
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.
PSPDFStylusDriver stylus driver protocol doesn’t extend
PSPDFPlugin anymore. To update your stylus drivers:
- Update the designated initializer to
- Change the name of
- Update keys in your
PSPDFPluginProtocolVersionKeyshould be removed.
Your stylus drivers have to be registered with the
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
You may want to provide your custom implementation for the following
id<PSPDFFileManager> fileManagerand coordinated file manager
If so, you can pass your own instances in the
options dictionary with
+[PSPDFKitGlobal setLicenseKey:options:] using the following keys:
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.