Upgrade Smoothly | iOS PSPDFKit 7 Migration Guide - Step-by-Step Tutorial

This guide covers how to update an iOS project from PSPDFKit 6.5–6.9 to PSPDFKit 7. It covers the split into a separate framework for user interface components, and it lists all the breaking API changes, with information on how to update each case. If you’re using an older version, see our PSPDFKit 6.5 Migration Guide.

PSPDFKit 7 for iOS fully supports iOS 9, 10, and 11. We plan to drop support for iOS 9 in 2018. Learn more in our version support guide. Xcode 9 is required — support for Xcode 8 was dropped to fully embrace the new Drag and Drop API available in iOS 11.

PSPDFKit has been split into two frameworks:

• PSPDFKit.framework for model and parser classes, such as PSPDFDocument and PSPDFAnnotation

• PSPDFKitUI.framework for user interface and view controllers, such as PSPDFViewController and PSPDFPageView

Unless you don’t use our UI components, you’ll want to include both frameworks. These frameworks have a hard version dependency, so always update both at the same time.

Migrate Your Project to PSPDFKit 7

If you’re using CocoaPods, run pod update and skip to step 4.

1. Download PSPDFKit 7 from the PSPDFKit Portal.

2. Open the disk image and copy both PSPDFKit.framework and PSPDFKitUI.framework into your project where PSPDFKit.framework used to be located. Replace the old version of PSPDFKit.framework with the new one when prompted.

3. Embed PSPDFKitUI by dragging PSPDFKitUI.framework into the Embedded Binaries section of your target.

   

4. Import PSPDFKitUI. In most cases, you’ll need to add @import PSPDFKitUI wherever you’re importing PSPDFKit.

   

5. Update your use of the API that has been changed or removed. The easiest way to do this is to repeatedly try to build your app, and then for each build error, search this page for the relevant API to find the suggested migration path.

6. Build and run your app.

The rest of this page lists every breaking API change, along with a suggested migration strategy. In many cases, a simple rename is all that’s required; where larger changes are required, the changes are described in detail.

A New View Hierarchy

One of the bigger changes is a completely overhauled view hierarchy for displaying documents. This step is necessary to improve performance down the road and allows us to implement new features faster. The new API is more convenient and opens up the possibility of you implementing your own layouts to display documents, enabling you to further customize the experience your users have when viewing PDF documents.

The new API results in a streamlined PSPDFViewController, with only a few common use cases available on the view controller itself. To customize and control the layout in more detail, use the new PSPDFDocumentViewController class, which is accessible via the documentViewController property on PSPDFViewController. This gives you full control over the layout.

We took this opportunity to rename some methods that no longer properly expressed what was going on under the hood. For example, almost all methods on PSPDFViewController that were dealing with pages have been replaced with methods that deal with spreads on the new document view controller. The caveats of the page-based methods have been documented on the remaining convenience methods on PSPDFViewController. Make sure you understand them before using these methods.

To learn all about the new view hierarchy and how things work together, check out the documentation on PSPDFDocumentViewController and read our guide about the view controller hierarchy.

A list of the main changes and the recommended migration strategy can be found below:

Instead of some of the direct replacements for methods, there might be other methods available on PSPDFDocumentViewController or PSPDFDocumentViewLayout, depending on what you want.

spreadFitting

-[PSPDFConfiguration spreadFitting] changes two properties, depending on which layout you’re using. It changes fillAlongsideTransverseAxis on PSPDFContinuousScrollingLayout, and it adjusts the contentScale property on PSPDFScrollPerSpreadLayout. This results in a similar but slightly more optimized layout compared to the previous fitToWidthEnabled configuration. For more options, you can also set the layout yourself and directly modify PSPDFScrollPerSpreadLayout‘s contentScale property to make each spread cover either the full width or the full height of the view. Depending on your scroll direction and layout, this may lead to a better user experience.

Paddings, Margins, and Spacing

Instead of properties for margin, padding, and pagePadding, there are now options to control these on the layout. Both PSPDFContinuousScrollingLayout and PSPDFScrollPerSpreadLayout support interitemSpacing to define the distance between two spreads. You can also add insets around the layout by setting contentInsets. If you want even more control, subclass one of these layouts and implement -sizeForSpreadAtIndex: to configure the exact size of each spread.

Signatures

signatureSavingEnabled and customerSignatureEnabled have been replaced with a more versatile signatureSavingStrategy on PSPDFConfiguration. signatureSavingStrategy is also available on PSPDFSignatureViewController, and it’s automatically set from -[PSPDFConfiguration signatureSavingStrategy] when used in the signature flow. If you manually use and show PSPDFSignatureViewController, this isn’t the case, and you can manually set its signatureSavingStrategy.

The shouldSaveSignature parameter has been dropped from - [PSPDFPageView showSignatureControllerAtRect:withTitle:shouldSaveSignature:options:animated:] in favor of using savingStrategy.

The My Signature and Customer Signature menu that appeared when customerSignatureEnabled was enabled has been replaced. There’s now a checkbox control on PSPDFSignatureViewController, which exists to determine if a signature should be saved if signatureSavingStrategy is configured that way.

signatureSavingStrategy has three possible values:

• PSPDFSignatureSavingStrategyAlwaysSave — Created signatures are always saved. The signature-saving checkbox is hidden.

• PSPDFSignatureSavingStrategyNeverSave — Created signatures are never saved. The signature-saving checkbox is hidden.

• PSPDFSignatureSavingStrategySaveIfSelected — Created signatures are only saved if the signature-saving checkbox in the UI is checked (this is the default).

This process allows for a faster and more streamlined signature experience, as there’s no additional menu involved, and all the possible options are now shown directly on the signature creation dialog.

Signatures in PSPDFSignatureStore are now stored using PSPDFSignatureContainer instead of PSPDFInkAnnotations. When retrieved, any previously stored ink annotations will automatically be migrated to the new signature container.

Digital Signatures

Now it’s possible to digitally sign a document with a certificate and an ink signature via PSPDFSignatureViewController or PSPDFSignatureSelectorViewController. This flow has replaced the document-signing logic of PSPDFUnsignedFormElementViewController (renamed to PSPDFCertificatePickerViewController). Adding a digital signature in the UI is now handled by PSPDFDigitalSignatureCoordinator.

If you want to manually sign a document with a chosen signer, you can use PSPDFCertificatePickerViewController to let the user pick a PSPDFSigner, and then use this signer to handle the digital signing.

For more information, take a look at our dedicated digital signatures guide.

Simplified PSPDFDocument Initializers

Most PSPDFDocument initializers and all class factory methods have been removed. The three remaining initializers are the convenient initWithURL: and the flexible initWithDataProviders: and initWithDataProviders:loadCheckpointIfAvailable:. Checkpoints are an advanced feature you can read about in our document checkpointing guide. Below you’ll find the APIs for creating documents and the migration strategy for the recently removed APIs:

To learn more about data providers, see our data providers guide, and for help choosing between PSPDFFileDataProvider and PSPDFCoordinatedFileDataProvider, see our file coordination guide.

Document Save Options

Prior to PSPDFKit 7.0, you’d have to use PSPDFProcessor to save a document with password protection and permissions by providing a PSPDFProcessorSaveOptions object.

With PSPDFKit 7.0, we renamed PSPDFProcessorSaveOptions to PSPDFDocumentSecurityOptions and allow you to pass the options via the new saveWithOptions:error: and saveWithOptions:completionHandler: document methods. See the PSPDFDocumentSaveOptionSecurityOptions API documentation for more details. Note that PSPDFFeatureMaskDocumentEditing must be part of your license; otherwise, passing PSPDFDocumentSaveOptionSecurityOptions will throw an exception.

Due to the above, we also had to rename some properties and methods to reflect the new document security options naming:

PSPDFDocumentDelegate Cleanup

PSPDFDocumentDelegate has been cleaned up to only include document-relevant callback methods. Any callbacks that were related to rendering, annotation saving, or file coordination have been removed and, if necessary, replaced with a more fitting solution.

Refer to the following table for information on how to migrate the removed delegate callbacks:

-[PSPDFDocumentDelegate pdfDocument:didRenderPageAtIndex:inContext:withSize:clippedToRect:annotations:options:] has multiple use cases:

• If you want a callback when a render task has finished rendering, use pdfViewController:didFinishRenderTaskForPageView: instead. Note that this method is only called if the page has been rendered, and not if the page image has been retrieved from the cache.

• If you want a callback every time the content image for the page view has been set — which includes rendering and retrieving the image from the cache — use pdfViewController:didUpdateContentImageForPageView:.

• If you used this callback for customizing the drawing on the page via context, use -[PSPDFDocument updateRenderOptions:type:] with @{ PSPDFRenderOptionDrawBlockKey: drawBlock } set in the options instead.

Refer to our document processing guide, which covers how to add watermarks.

Renaming HUD to User Interface

Other API Changes

PSPDFKitUI

PSPDFKit

The PSPDFDataProvider protocol has been renamed to PSPDFDataProviding, and the more specialized protocols, PSPDFFileDataProviding and PSPDFCoordinatedFileDataProviding, have been added. The fileURL property has moved to PSPDFFileDataProviding. File-backed data provider implementations should change to conform to PSPDFFileDataProviding instead of PSPDFDataProvider. PSPDFAESCryptoDataProvider has done this. Data providers can cooperate with PSPDFKit to support file coordination by implementing PSPDFCoordinatedFileDataProviding.

Metadata handling — which could previously be read with -[PSPDFLibrary metadataForUID:] — has been removed from PSPDFLibrary. The largest use case was to store the path to the document, which is no longer necessary when using PSPDFLibraryFileSystemDataSource. You can get this information using -[PSPDFLibraryFileSystemDataSource indexItemDescriptorForDocumentWithUID:]. For any other metadata, you’ll need to write your own handling code.

The block signature of -[PSPDFRenderTask completionHandler] has changed. Since, in rare cases, render tasks can fail, the block is now passed either an image or an error. Change the block you set to add an NSError parameter and be prepared for the case when the block is called with the image as nil.

Removal of a Deprecated API

All previously deprecated APIs have been removed.

PSPDFKitUI

PSPDFKit

PSPDFKit.bundle

PSPDFKit 7 adds vector images and support for asset catalogs. Images from PSPDFKit.bundle that used to be named an-image.png are now named an_image.pdf and have been moved to PSPDFKitUI.framework/Assets.car.

For example, edit-annotations.png, which used to be in PSPDFKit.framework/PSPDFKit.bundle, has now been renamed to edit_annotations.pdf and has been moved to PSPDFKitUI.framework/Assets.car.

Vector images can be accessed via:

let image = PSPDFKit.imageNamed("an_image.pdf")

UIImage *image = [PSPDFKit imageNamed:@"an_image.pdf"]