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

Information

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.

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

    Import PSPDFKitUI
  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:

Removed API Migration Strategy
-[PSPDFViewController scrollToNextPageAnimated:] Use -[PSPDFDocumentViewController scrollToNextSpreadAnimated:] instead.
-[PSPDFViewController scrollToPreviousPageAnimated:] Use -[PSPDFDocumentViewController scrollToPreviousSpreadAnimated:] instead.
-[PSPDFViewController scrollingEnabled] Use -[PSPDFDocumentViewController scrollEnabled] instead.
-[PSPDFViewController viewLockEnabled] Use -[PSPDFDocumentViewController scrollEnabled] and -[PSPDFDocumentViewController zoomEnabled] instead.
-[PSPDFViewController scrollRectToVisible: animated:] Use either -[PSPDFDocumentViewController setSpreadIndex:] or -[PSPDFDocumentViewController zoomToPDFRect: forPageAtIndex: animated:].
-[PSPDFViewController zoomToRect: pageIndex: animated:] Use -[PSPDFDocumentViewController zoomToPDFRect: forPageAtIndex: animated:] instead.
-[PSPDFViewController setZoomScale: animated:] Use -[PSPDFDocumentViewController zoomToPDFRect: forPageAtIndex: animated:] instead.
-[PSPDFViewController pagingScrollView] Directly accessing the scroll view is no longer supported. Implement -[PSPDFDocumentViewControllerDelegate documentViewController: configureScrollView:] or -[PSPDFDocumentViewControllerDelegate documentViewController: configureZoomView: forSpreadAtIndex:], depending on your needs.
-[PSPDFViewController visiblePageIndexes] Visible page indexes should be collected from -[PSPDFViewController visiblePageViews] if needed.
-[PSPDFViewController doublePageMode] This method is no longer supported due to its inaccuracy. Use -[PSPDFDocumentViewLayout pageRangeForSpreadAtIndex:] instead and check the range’s length for the number of pages in a particular spread, or use -[PSPDFDocumentViewLayout spreadMode] to determine the mode the layout is in.
-[PSPDFViewController lastPage] Use -[PSPDFDocumentViewController spreadIndex] and compare it with the number of spreads.
-[PSPDFViewController firstPage] Check if -[PSPDFDocumentViewController spreadIndex] is 0.
-[PSPDFViewController captureCurrentViewState] Use -[PSPDFViewController viewState] instead.
-[PSPDFViewControllerDelegate pdfViewController: shouldScrollToPageAtIndex:] To prevent scrolling, use -[PSPDFDocumentViewController scrollEnabled] instead.
-[PSPDFViewControllerDelegate pdfViewController: didShowPageView:] Implement -[PSPDFViewControllerDelegate pdfViewController: willBeginDisplayingPageView: forPageAtIndex:] instead.
-[PSPDFViewControllerDelegate pdfViewController: didLoadPageView:] Implement -[PSPDFViewControllerDelegate pdfViewController: didConfigurePageView: forPageAtIndex:] instead.
-[PSPDFViewControllerDelegate pdfViewController: willUnloadPageView:] Implement -[PSPDFViewControllerDelegate pdfViewController: didCleanupPageView: forPageAtIndex:] instead.
-[PSPDFViewControllerDelegate pdfViewController: didBeginPageDragging:] Monitoring individual states of one of the scroll views is no longer possible. Instead, monitor spreadIndex or continuousSpreadIndex either through KVO or the available delegate methods.
-[PSPDFViewControllerDelegate pdfViewController: didEndPageDragging: willDecelerate: withVelocity: targetContentOffset:] Monitoring individual states of one of the scroll views is no longer possible. Instead, monitor spreadIndex or continuousSpreadIndex either through KVO or the available delegate methods.
-[PSPDFViewControllerDelegate pdfViewController: didEndPageScrollingAnimation:] Monitoring individual states of one of the scroll views is no longer possible. Instead, monitor spreadIndex or continuousSpreadIndex either through KVO or the available delegate methods.
-[PSPDFViewControllerDelegate pdfViewController: didBeginPageZooming:] Monitoring individual states of one of the scroll views is no longer possible. Instead, monitor spreadIndex or continuousSpreadIndex either through KVO or the available delegate methods.
-[PSPDFViewControllerDelegate pdfViewController: didEndPageZooming: atScale:] Monitoring individual states of one of the scroll views is no longer possible. Instead, monitor spreadIndex or continuousSpreadIndex either through KVO or the available delegate methods.
-[PSPDFConfiguration fitToWidthEnabled] Use -[PSPDFConfiguration spreadFitting] instead.
-[PSPDFConfiguration fixedVerticalPositionForFitToWidthEnabledMode] This option is no longer supported.
-[PSPDFConfiguration zoomingSmallDocumentsEnabled] This option is no longer supported.
-[PSPDFConfiguration alwaysBouncePages] Use -[PSPDFDocumentViewController alwaysBounce] instead.
-[PSPDFConfiguration showsHorizontalScrollIndicator] Use -[PSPDFDocumentViewController showsScrollIndicator] instead.
-[PSPDFConfiguration showsVerticalScrollIndicator] Use -[PSPDFDocumentViewController showsScrollIndicator] instead.
-[PSPDFConfiguration margin] Use -[PSPDFConfiguration additionalScrollViewFrameInsets] instead.
-[PSPDFConfiguration padding] Use -[PSPDFConfiguration additionalContentInsets] instead.
-[PSPDFConfiguration pagePadding] Use the customization options on the various PSPDFDocumentViewLayout subclasses to achieve the desired look.
-[PSPDFPageView scrollView] This was renamed to -[PSPDFPageView zoomView] to clarify that this isn’t the scroll view responsible for scrolling through the document.
PSPDFPageScrollViewController Use the new document view hierarchy, starting with PSPDFDocumentViewController.
PSPDFContentScrollView Use the new document view hierarchy, starting with PSPDFDocumentViewController.
PSPDFScrollView Use the new document view hierarchy, starting with PSPDFDocumentViewController.

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:

Removed API Migration Strategy
+[PSPDFDocument document] Use [PSPDFDocument new] or [[PSPDFDocument alloc] init].
+[PSPDFDocument documentWithURL:] Use [[PSPDFDocument alloc] initWithURL: URL].
+[PSPDFDocument documentWithData:] and -[PSPDFDocument initWithData:] This isn’t recommended. Since iOS doesn’t swap memory to disk, allocating too much by loading a large PDF this way will get your app terminated by iOS. If you really need to, use [[PSPDFDocument alloc] initWithDataProviders: @[[[PSPDFDataContainerProvider alloc] initWithData: data]]].
+[PSPDFDocument documentWithDataArray:] and -[PSPDFDocument initWithDataArray:] As above, this isn’t recommended, but if you really need to, create an array of PSPDFDataContainerProviders, one for each NSData (easy in Swift with map). Then use [[PSPDFDocument alloc] initWithDataProviders: dataProviders].
+[PSPDFDocument documentWithDataProvider:] and -[PSPDFDocument initWithDataProvider:] Use [[PSPDFDocument alloc] initWithDataProviders: @[dataProvider]].
+[PSPDFDocument documentWithDataProviderArray:] Use [[PSPDFDocument alloc] initWithDataProviders: dataProviderArray].
+[PSPDFDocument documentWithBaseURL: files:] and -[PSPDFDocument initWithBaseURL: files:] For each file, create a data provider like this: [[PSPDFCoordinatedFileDataProvider alloc] initWithFileURL: [baseURL URLByAppendingPathComponent: file isDirectory: NO] baseURL: baseURL]. Then use initWithDataProviders:. The baseURL argument should be set to ensure the UID is the same as before.
+[PSPDFDocument documentWithBaseURL: fileTemplate: startPage: endPage:] and -[PSPDFDocument initWithBaseURL: fileTemplate: startPage: endPage:] Similar to the above, create a PSPDFCoordinatedFileDataProvider for each index in the startPageendPage range, and then use initWithDataProviders:. Again, the baseURL should be set on each data provider to ensure the UID is the same as before.
+[PSPDFDocument documentWithContent:] and -[PSPDFDocument initWithContent:] If content was NSString or NSURL, use initWithURL:. Otherwise, use initWithDataProviders:. If it was NSData, create a PSPDFDataContainerProvider. If it was a collection, create an array of data providers.
+[PSPDFDocument documentWithContent: signatures:] and -[PSPDFDocument initWithContent: signatures:] As above. For signatures, create appropriate data providers and then set the new signature property on each one before creating the PSPDFDocument.
-[PSPDFDocument baseURL] and -[PSPDFDocument files] These don’t make sense now that the corresponding initializers have been removed. If this information is still necessary, extract whatever information is required from the fileURL or fileURLs property.
-[PSPDFDocument documentByAppendingObjects:] Use documentByAppendingDataProviders: instead. This no longer accepts instances of NSString, NSURL, or NSData, and it creates data providers in lieu of them.
-[PSPDFDocument dataProviderArray] This was renamed to dataProviders.
-[PSPDFDocument contentSignatures] Read the signatures property on each of the document’s dataProviders.

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:

Old API New API
+[PSPDFProcessor generatePDFFromConfiguration: saveOptions:...] family of methods Nutrient: [PSPDFProcessor generatePDFFromConfiguration: securityOptions:...] family of methods
[PSPDFProcessor saveOptions] Nutrient: [PSPDFProcessor securityOptions]
PSPDFProcessorSaveOptions Nutrient: PSPDFDocumentSecurityOptions
-[PSPDFDocumentSharingViewController delegateProcessorSaveOptions] NutrientUI: -[PSPDFDocumentSharingViewController delegateDocumentSecurityOptions]
-[PSPDFDocumentSharingViewControllerDelegate processorSaveOptionsForDocumentSharingViewController:] NutrientUI: -[PSPDFDocumentSharingViewControllerDelegate documentSecurityOptionsForDocumentSharingViewController:]
-[PSPDFDocument alwaysRewriteOnSave] Instead use PSPDFDocumentSaveOptionForceRewrite when saving.
-[PSPDFDocument save:] Use the saveWithOptions: error:, passing nil for options.
-[PSPDFDocument saveWithCompletionHandler:] Use saveWithOptions: completionHandler:, passing nil for options.

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:

Removed API Migration Strategy
-[PSPDFDocumentDelegate pdfDocument: didRenderPageAtIndex: inContext: withSize: clippedToRect: annotations: options:] There may be a few possibilities. See the section below this table.
-[PSPDFDocumentDelegate pdfDocument: provider: shouldSaveAnnotations:] Use annotationSaveMode or PSPDFAnnotationProvider to control whether or not annotations should be saved.
-[PSPDFDocumentDelegate pdfDocument: didSaveAnnotations:] Use -[PSPDFAnnotationProviderDelegate annotationProvider: didSaveAnnotations:] instead.
-[PSPDFDocumentDelegate pdfDocument: failedToSaveAnnotations: error:] Use -[PSPDFAnnotationProviderDelegate annotationProvider: failedToSaveAnnotations: error:] instead.
-[PSPDFDocumentDelegate pdfDocument: underlyingFileDidChange:] Subclass PSPDFDocument and override the PSPDFileCoordinationDelegate methods.

-[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

Old API New API
PSPDFHUDView PSPDFUserInterfaceView
PSPDFHUDViewMode PSPDFUserInterfaceViewMode
PSPDFHUDViewAnimation PSPDFUserInterfaceViewAnimation
PSPDFHUDControls PSPDFUserInterfaceControls
-[PSPDFViewController HUDVisible] userInterfaceVisible
-[PSPDFConfiguration shouldShowHUDOnViewWillAppear] shouldShowUserInterfaceOnViewWillAppear
-[PSPDFConfiguration HUDViewMode] userInterfaceViewMode
-[PSPDFConfiguration shouldHideHUDOnPageChange] shouldHideUserInterfaceOnPageChange
-[PSPDFConfiguration shouldHideNavigationBarWithHUD] shouldHideNavigationBarWithUserInterface
-[PSPDFConfiguration shouldHideStatusBarWithHUD] shouldHideStatusBarWithUserInterface

Other API Changes

PSPDFKitUI

Removed API Migration Strategy
-[PSPDFTextSelectionView selectionRect] Renamed to innerRect to better describe what it is. If you want the bounding rectangle enclosing the entire selection, compute this from firstLineRect, innerRect, and lastLineRect.
-[PSPDFToolbarButton setImage:] Set the image property. This is only a breaking change in Swift. Use button.image = someImage instead of button.setImage(someImage).
-[PSPDFViewController updatepageIndex:animated:] This was renamed to reloadPageAtIndex:animated:.
PSPDFAnnotationViewProtocol This was renamed to PSPDFAnnotationPresenting.
PSPDFStatefulViewControllerProtocol This was renamed to PSPDFStatefulViewControlling.
PSPDFLinkActionInlineBrowserLegacy This was renamed to PSPDFLinkActionInlineWebViewController.

PSPDFKit

Removed API Migration Strategy
PSPDFAbstractTextOverlayAnnotations This was renamed to PSPDFMarkupAnnotation.
-[PSPDFAnnotation isFixedSize] Instead, compare the fixedSize property to the new PSPDFAnnotationFixedSizeDisabled constant.
-[PSPDFCache cacheDocument: pageSizes: withDiskCacheStrategy: aroundPageAtIndex: imageRenderingCompletionBlock:] The disk cache strategy is controlled automatically now. Use -[PSPDFCache cacheDocument: withPageSizes: imageRenderingCompletionBlock:] instead.
-[PSPDFCache cacheDocument: pageSizes: withDiskCacheStrategy: aroundPageAtIndex:] The disk cache strategy is controlled automatically now. Use -[PSPDFCache cacheDocument: withPageSizes:] instead.
-[PSPDFDocument annotationsByDetectingLinkTypes: forPagesInRange: options: progress: error:] This was renamed to annotationsByDetectingLinkTypes: forPagesAtIndexes: options: progress: error:.
-[PSPDFDocument isAnnotationsEnabled] Use areAnnotationsEnabled instead.
-[PSPDFDocument isBookmarksEnabled] Use areBookmarksEnabled instead.
-[PSPDFDocument isFormsEnabled] Use areFormsEnabled instead.
-[PSPDFDocument isPageLabelsEnabled] Use arePageLabelsEnabled instead.
PSPDFileCoordinationDelegate This was renamed to PSPDFFileCoordinationDelegate.
-[PSPDFileCoordinationDelegate accommodatePresentedItemDeletionForPresenter: completionHandler:] Use accommodatePresentedItemDeletionForDataProvider: completionHandler: instead.
-[PSPDFileCoordinationDelegate presentedItemDidChangeForPresenter:] Use presentedItemDidChangeForDataProvider: instead.
-[PSPDFLibrary updateIndex] Use -[PSPDFLibrary updateIndexWithCompletionHandler:] instead, passing nil for the completion handler.
PSPDFUndoProtocol This was renamed to PSPDFUndoSupport.
-[PSPDFXFDFParser initWithInputStream: documentProvider:] Create an object conforming to PSPDFDataProviding instead of an NSInputStream, and then use initWithDataProvider: documentProvider:.
-[PSPDFXFDFParser inputStream] Use dataProvider instead.
-[PSPDFXFDFWriter writeAnnotations: toOutputStream: documentProvider: error:] Create an object conforming to PSPDFDataSink instead of an NSOutputStream, and then use writeAnnotations: toDataSink: documentProvider: error:.

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

Removed API Migration Strategy
-[PSPDFAnnotationStateManager allowedImageQualities] Use -[PSPDFImagePickerController allowedImageQualities] instead.
-[PSPDFAnnotationStateManager isHighlightAnnotationState:] Use isMarkupAnnotationState: instead.
-[PSPDFAnnotationTableViewController annotationForIndexPath:] Use annotationForIndexPath: inTableView: instead.
-[PSPDFConfiguration(Builder) doublePageModeOnFirstPage] Use !firstPageAlwaysSingle instead.
-[PSPDFConfiguration(Builder) pageCurlDirectionLeftToRight] This is now derived from the document. See -[PSPDFDocument pageBinding].
-[PSPDFConfiguration(Builder) signatureSavingEnabled] Use signatureSavingStrategy instead.
-[PSPDFConfiguration(Builder) customerSignatureEnabled] Use signatureSavingStrategy instead.
-[PSPDFDocumentActionExecutor document] Use documents instead.
-[PSPDFDocumentActivity document] Use documents instead.
-[PSPDFDocumentSharingCoordinator initWithDocument:] Use initWithDocuments: instead.
-[PSPDFDocumentSharingViewController document] Use documents instead.
-[PSPDFDocumentSharingViewController initWithDocument: visiblePageRange: allowedSharingOptions:] Use initWithDocuments: visiblePageRange: allowedSharingOptions: instead.
-[PSPDFDrawView allowedTouchTypes] Use drawGestureRecognizer.allowedTouchTypes instead.
-[PSPDFGalleryViewController transitioning] and -[PSPDFMultimediaViewController transitioning] The view controller was no longer transitioning when its content went fullscreen so this property would always return NO.
-[PSPDFOutlineCell heightForCellWithOutlineElement: documentProvider: constrainedToSize: outlineIntentLeftOffset: outlineIntentMultiplier: showPageLabel:] PSPDFOutlineCell is now a self-sizing table view cell.
-[PSPDFPageView trailingPage] Removed for new PSPDFDocumentViewLayout-based architecture. The page view no longer contains this information.
-[PSPDFPresentationContext isRightPageInDoublePageMode:] Removed for new PSPDFDocumentViewLayout-based architecture. The page view no longer contains this information.
-[PSPDFPresentationContext landscapePageIndexForPortraitPageIndex:] Removed for new PSPDFDocumentViewLayout-based architecture. The page view no longer contains this information.
-[PSPDFPresentationContext portraitPageIndexForLandscapePageIndex:] Removed for new PSPDFDocumentViewLayout-based architecture. The page view no longer contains this information.
-[PSPDFSignatureViewControllerDelegate signatureViewControllerDidSave:] Use signatureViewControllerDidFinish: withSigner: shouldSaveSignature: instead.
-[PSPDFTabbedViewController allowsClosingDocuments] Use closeMode instead. YES corresponds to PSPDFTabbedViewControllerCloseModeOnlySelectedTab, andNO corresponds to PSPDFTabbedViewControllerCloseModeDisabled.
-[PSPDFThumbnailViewController stickyHeaderEnabled] Use -[PSPDFThumbnailFlowLayout stickyHeaderEnabled] instead, if your layout supports it. The default layout does.
-[PSPDFUnsignedFormElementViewControllerDelegate unsignedFormElementViewController: signedDocument: error:] Use -[PSPDFCertificatePickerViewControllerDelegate certificatePickerViewController: didPickSigner:] and PSPDFDigitalSignatureCoordinator instead.
-[PSPDFViewControllerDelegate pdfViewController: didRenderPageView:] Use either pdfViewController: didFinishRenderTaskForPageView: or pdfViewController: didUpdateContentImageForPageView: isPlaceholder:, depending on your needs.
PSPDFDocumentSharingOptionVisiblePages Use PSPDFDocumentSharingOptionPageRange instead.
PSPDFThumbnailFlowLayoutAttributesTypeLeft Changed for right-to-left support. Use PSPDFThumbnailFlowLayoutAttributesTypeLeading instead.
PSPDFThumbnailFlowLayoutAttributesTypeRight Changed for right-to-left support. Use PSPDFThumbnailFlowLayoutAttributesTypeTrailing instead.

PSPDFKit

Removed API Migration Strategy
+[PSPDFAnnotation fixedSize] Instead of this class method, use the corresponding instance property, fixedSize.
+[PSPDFAnnotation isFixedSize] Instead of this class method, check if the fixedSize instance property is different than PSPDFAnnotationFixedSizeDisabled.
-[PSPDFAnnotation indexOnPage] You shouldn’t rely on an annotation having a certain index on the page it belongs to.
-[PSPDFBookmark pageOrNameString] Use displayName instead.
-[PSPDFCache allowedDiskSpace] Use diskCache.allowedDiskSpace instead.
-[PSPDFCache cacheDirectory] Use diskCache.cacheDirectory instead.
-[PSPDFCache decryptFromPathBlock] Use diskCache.decryptionHelper, which has data parameter instead of a path.
-[PSPDFCache diskCacheStrategy] The disk cache strategy is controlled automatically now. To disable the disk cache completely, set its allowedDiskSpace to 0.
-[PSPDFCache encryptDataBlock] Use diskCache.encryptionHelper, which returns immutable data instead of modifying a mutable data parameter.
-[PSPDFCache JPGFormatCompression] Use diskCache.jpegCompression instead.
-[PSPDFCache pauseCachingForService:] Pause caching is no longer supported. The cache handles this on its own.
-[PSPDFCache resumeCachingForService:] Pause caching is no longer supported. The cache handles this on its own.
-[PSPDFCache usedDiskSpace] Use diskCache.usedDiskSpace instead.
-[PSPDFCache useJPGFormat] Use diskCache.fileFormat == PSPDFDiskCacheFileFormatJPEG instead.
-[PSPDFDocument annotationsByDetectingLinkTypes: forPagesInRange: options: progress: error:] Use annotationsByDetectingLinkTypes: forPagesAtIndexes: options: progress: error: instead.
-[PSPDFDocument annotationsFromDetectingLinkTypes: pagesInRange: options: progress: error:] Use annotationsByDetectingLinkTypes: forPagesAtIndexes: options: progress: error: instead. Note that the new method returns nil on failure.
-[PSPDFDocument diskCacheStrategy] The disk cache strategy is controlled automatically now. To disable the disk cache completely, set its allowedDiskSpace to 0.
-[PSPDFDocument filesWithBasePath] Use fileURLs instead.
-[PSPDFDocument metadata] This property has been replaced by the PSPDFDocumentPDFMetadata class.
-[PSPDFLibrary enqueueDocuments:] Use updateIndexWithCompletionHandler: and provide the desired documents to the library’s data source.
+[PSPDFProcessorSaveOptions optionsWithOwnerPassword: userPassword: keyLength: permissions:] Use -[PSPDFDocumentSecurityOptions initWithOwnerPassword: userPassword: keyLength: permissions:] instead.
+[PSPDFProcessorSaveOptions optionsWithOwnerPassword: userPassword: keyLength:] Use -[PSPDFDocumentSecurityOptions initWithOwnerPassword: userPassword: keyLength:] instead.
-[PSPDFRenderQueue cancelAllJobs] Use cancelAllTasks instead.
-[PSPDFRenderQueue concurrentRunningRenderRequests] The render queue manages this internally based on various factors.
-[PSPDFRenderQueue minimumProcessPriority] The render queue manages prioritization itself.
-[PSPDFSignatureFormElement drawArrowWithText: andColor: inContext:] Rendering the signature arrow is now handled internally.
-[PSPDFSignaturePropBuildEntry nonEFontNoWarn] Use nonEmbeddedFontNoWarning instead.
-[PSPDFSignaturePropBuildEntry OS] Use operatingSystem instead.
-[PSPDFSignaturePropBuildEntry REx] Use textRevision instead.
-[PSPDFSignaturePropBuildEntry R] Use revisionNumber instead.
-[PSPDFSignaturePropBuildEntry V] Use minimumVersion instead.
-[PSPDFUndoController undoEnabled] This property was always true.
PSPDFDiskCacheStrategy This enum is no longer used, so it has been removed.
PSPDFErrorCodeFileCoordination BackgroundTaskCreationFailed This error doesn’t occur. Handling of this error case should be removed.
PSPDFIgnoreDisplaySettingsKey Use PSPDFRenderOptionIgnoreDisplaySettingsKey instead.
PSPDFPreserveAspectRatioKey Use PSPDFRenderOptionPreserveAspectRatioKey instead
PSPDFRenderAllowAntiAliasingKey Use PSPDFRenderOptionAllowAntiAliasingKey instead.
PSPDFRenderBackgroundFillColorKey Use PSPDFRenderOptionBackgroundFillColorKey instead.
PSPDFRenderDrawBlockKey Use PSPDFRenderOptionDrawBlockKey instead.
PSPDFRenderFiltersKey Use PSPDFRenderOptionFiltersKey instead.
PSPDFRenderIgnorePageClipKey Use PSPDFRenderOptionIgnorePageClipKey instead.
PSPDFRenderInteractiveFormFillColorKey Use PSPDFRenderOptionInteractiveFormFillColorKey instead.
PSPDFRenderInterpolationQualityKey Use PSPDFRenderOptionInterpolationQualityKey instead.
PSPDFRenderInvertedKey Use PSPDFRenderOptionInvertedKey instead.
PSPDFRenderOverlayAnnotationsKey Use PSPDFRenderOptionOverlayAnnotationsKey instead.
PSPDFRenderPageColorKey Use PSPDFRenderOptionPageColorKey instead.
PSPDFRenderQueuePriorityHigh Use PSPDFRenderQueuePriorityUserInitiated instead.
PSPDFRenderQueuePriorityLow Use PSPDFRenderQueuePriorityBackground instead.
PSPDFRenderQueuePriorityNormal Use PSPDFRenderQueuePriorityUtility instead.
PSPDFRenderQueuePriorityVeryHigh Use PSPDFRenderQueuePriorityUserInteractive instead.
PSPDFRenderQueuePriorityVeryLow Use PSPDFRenderQueuePriorityUnspecified instead.
PSPDFRenderRequestCachePolicy ReloadIgnoreingCacheData Use PSPDFRenderRequestCachePolicyReloadIgnoringCacheData instead.
PSPDFRenderSkipAnnotationArrayKey Use PSPDFRenderOptionSkipAnnotationArrayKey instead.
PSPDFRenderSkipPageContentKey Use PSPDFRenderOptionSkipPageContentKey instead.

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"]