PSPDFKit 9 Migration Guide

This guide covers updating an iOS project from PSPDFKit 8.x to PSPDFKit 9. We encourage you to update as soon as possible, in order to take advantage of future new features and fixes.

PSPDFKit 9.0.0 for iOS fully supports iOS 11, 12, and 13. iOS 11 support will be removed later during the PSPDFKit 9 lifecycle. Xcode 11 or later is required to use this version of the SDK. Learn more in our version support guide.

XCFramework Integration

PSPDFKit 9 for iOS is bundled as .xcframework files (XCFrameworks) instead of as .framework files. If you’re using the manual integration, you need to remove the old frameworks from the Frameworks, Libraries, and Embedded Content section of your target and add the XCFrameworks instead.

embedded-binaries

For more details, follow our integrating PSPDFKit manually guide.

Dark Mode

The entire PSPDFKit user interface was audited for compatibility using the new systemwide Dark Mode, which led to some updates to used default colors and visual effect materials. On iOS 13, most user interface colors are now dynamic UIColors, which automatically adapt in Dark Mode. Color and material changes are mostly contained to iOS 13. However, due to the internal unification of used colors, certain defaults might also have changed slightly on previous iOS versions.

The addition of Dark Mode support also led to some behavioral changes with PSPDFKit’s own internal dark interface implementation.

On iOS 13, PSPDFAppearanceManager no longer transitions the UI into dark mode via UIAppearance-based theming when PSPDFAppearanceModeNight is selected. This is true for both programmatic switching via PSPDFAppearanceManager.appearanceMode and when the appearance mode is specified via the built-in UI on PSPDFSettingsViewController. Instead, the UI follows the global interface mode setting that the end user selects. The page rendering style is still adjusted when PSPDFAppearanceMode.appearanceMode changes.

We recommend following Apple guidelines and honoring the user’s selected interface mode. However, if you prefer to still use PSPDFKit’s UI to switch user interface styles inside your application, you can do so via PSPDFAppearanceManagerDelegate messages or PSPDFAppearanceModeChangedNotification messages, all of which are still being sent out on appearance updates. You can listen for those updates and then set overrideUserInterfaceStyle on a view controller or view appropriate for your application.

The behavior of PSPDFAppearanceManager, its delegates, and the related UI remains unchanged on iOS 11 and iOS 12.

PSPDFKitSwift Integration

The introduction of both ABI and module stability in the Swift 5.1 compiler enabled us to merge our PSPDFKitSwift wrapper into our main binary distribution. The standalone project is now deprecated and should be removed from your project when updating to PSPDFKit 9 for iOS. If you’re using CocoaPods or Carthage, you should remove the PSPDFKitSwift dependency from your Podfile or Cartfile.

During the integration, we made the following changes to the Swift and Objective-C APIs:

Changed

PSPDFKit Objective-C class
Renamed to PSPDFKitGlobal to avoid conflicts with the PSPDFKit module name. The previous PSPDFKitObject Swift typealias was removed.
Removed

Result struct
Removed in favor of the built-in struct with the same name in Swift 5.
Removed

PDFDocument convenience subclass
Most of its functionality was migrated to PSPDFDocument extensions. You should use PSPDFDocument instead.
Removed

Typealiases for annotation types
Use PSPDF-prefixed class names instead.

If your application is targeting iOS versions prior to iOS 12.2 and your application does not already contain any Swift code, then you need to make sure Xcode bundles Swift standard libraries with your application distribution. To do so, open your target Build Settings and enable Always Embed Swift Standard Libraries. After setting this, clean the project before building again.

If testing on iOS 11 and 12 still leads to issues similar to dyld: Library not loaded: @rpath/libswiftCore.dylib (observed for Objective-C-only test targets), then you can also try an alternative approach by including a minimal Swift class in your project that ensures Foundation libraries are loaded.

Sample Swift class:

import Foundation

class TokenSwiftFile {
    func tokenFunction () {
        NSLog("This file exists to force-load Swift libraries for iOS <12.2.")
    }
}

UIWebView Removal

PSPDFWebViewController switched from the deprecated UIWebView to use the more modern WKWebView by default a long time ago. Support for UIWebView was kept for a transitional period, and it has now been removed. This means the following API changes have been made:

Removed

PSPDFWebKitLegacyModeKey setting on the PSPDFKit object (now PSPDFKitGlobal)
Removed

PSPDFCommonWebView protocol
Removed

PSPDFWebViewController.useModernWebKit
The more modern WebKit framework is now always used.
Changed

PSPDFWebViewController.webView
The property type has changed from UIView<PSPDFCommonWebView> to WKWebView.

Note that, by default, PSPDFKit asks the system to open links, which usually means they open in Safari (PSPDFLinkActionOpenSafari). This is our recommended user experience. If you would prefer to provide an in-app browser, then we recommend showing SFSafariViewController (PSPDFLinkActionInlineBrowser) rather than PSPDFWebViewController (PSPDFLinkActionInlineWebViewController).

Customizing Document Rendering

PSPDFKit 9 for iOS introduces a new class, PSPDFRenderOptions, which is a concrete representation of the options that can be used to customize how a document or annotations are rendered.

PSPDFRenderOptions replaces all the keys that were in the PSPDFRenderOption enumeration. This means keys such as PSPDFRenderOptionPreserveAspectRatioKey, PSPDFRenderOptionInvertedKey, and PSPDFRenderOptionFiltersKey are no longer available. Likewise, all of the rendering methods that take render options, such as -[PSPDFDocument imageForPageAtIndex:size:clippedToRect:annotationsoptions:error:], have been updated to take PSPDFRenderOptions as options, as opposed to taking NSDictionary<PSPDFRenderOption, id>. If you use or implement any of these methods yourself, you’ll have to update them to the correct signature to resolve any compilation issues.

APIs affected by this:

Changed

-[PSPDFPageView renderOptionsDictWithZoomScale:animated:]
Renamed to -[PSPDFPageView renderOptionsWithZoomScale:animated:].
Changed

PSPDFConfiguration.scrollOnTapPageEndAnimationEnabled
Renamed to animateScrollOnEdgeTaps.
Changed

PSPDFConfiguration.scrollOnTapPageEndMargin
Renamed to scrollOnEdgeTapMargin.
Changed

-[PSPDFAnnotation maybeRenderCustomAppearanceStreamWithContext:withOptions:]
Renamed to -[PSPDFAnnotation maybeRenderCustomAppearanceStreamWithContext:options:].
Changed

-[PSPDFAnnotation drawInContext:withOptions:]
Renamed to -[PSPDFAnnotation drawInContext:options:].
Changed

-[PSPDFAnnotation imageWithSize:withOptions:]
Renamed to -[PSPDFAnnotation imageWithSize:options:].
Changed

-[PSPDFAnnotationSet drawInContext:withOptions:]
Renamed to -[PSPDFAnnotationSet drawInContext:options:].
Changed

-[PSPDFDocument updateRenderOptions:type:]
Use -[PSPDFDocument updateRenderOptionsForType:withBlock:].
Changed

-[PSPDFDocument renderOptionsForType:context:]
Use -[PSPDFDocument renderOptionsForType:].

PDF Generation and Modification

PSPDFKit 9 for iOS improves the API for generating PDFs from website URLs and HTML strings, and it adds the ability to generate PDFs from NSAttributedStrings.

PDF generation methods are now unified in the form of class methods on PSPDFProcessor. They return one of several new operations — PSPDFURLConversionOperation, PSPDFHTMLConversionOperation, or PSPDFAttributedStringConversionOperation. The operations can be observed and canceled. The old instance method-based API for generating PDFs from URLs and HTML strings has been removed.

-[PSPDFProcessor cancel] no longer cancels all ongoing conversion operations. The cancelation call only affects operations performed on existing PDFs with the instance method-based API. Use the new +[PSPDFProcessor cancelAllConversionOperations] to cancel conversion operations.

APIs affected by this:

Removed

-[PSPDFProcessor initWithOptions:]
Pass options directly to the new PDF generation methods.
Removed

-[PSPDFProcessor convertHTMLString:]
Use the new +[PSPDFProcessor generatePDFFromHTMLString:options:completionBlock:].
Removed

-[PSPDFProcessor convertHTMLString:outputFileURL:]
Use the new +[PSPDFProcessor generatePDFFromHTMLString:outputFileURL:options:completionBlock:].
Removed

-[PSPDFProcessor convertHTMLString:outputFileURL:completionBlock:]
Use the new +[PSPDFProcessor generatePDFFromHTMLString:outputFileURL:options:completionBlock:].
Removed

-[PSPDFProcessor generatePDFFromURL:]
Use the new +[PSPDFProcessor generatePDFFromURL:options:completionBlock:].
Removed

-[PSPDFProcessor generatePDFFromURL:outputFileURL:]
Use the new +[PSPDFProcessor generatePDFFromURL:outputFileURL:options:completionBlock:].
Removed

-[PSPDFProcessor generatePDFFromURL:outputFileURL:completionBlock:]
Use the new +[PSPDFProcessor generatePDFFromURL:outputFileURL:options:completionBlock:].
Changed

PSPDFConversionOperation
Split into PSPDFURLConversionOperation, PSPDFHTMLConversionOperation, and PSPDFAttributedStringConversionOperation.

The PSPDFProcessor API for PDF document modification has also been cleaned up. The non-throwing methods data, writeToFileURL:, and outputToDataSink: have been removed in favor of their throwing counterparts.

APIs affected by this:

Removed

-[PSPDFProcessor data]
Use -[PSPDFProcessor dataWithError:].
Removed

-[PSPDFProcessor writeToFileURL:]
Use -[PSPDFProcessor writeToFileURL:error:].
Removed

-[PSPDFProcessor outputToDataSink:]
Use -[PSPDFProcessor outputToDataSink:error:].

The PSPDFProcessorDelegate-based error and completion handling via processor:didFinishWithError:, processor:didFinishWithData:, and processor:didFinishWithFileURL: have also been removed.

APIs affected by this:

Removed

-[PSPDFProcessorDelegate processor:didFinishWithError:]
Use the error parameter in the PDF document modification methods and completionBlock in the new PDF generation methods.
Removed

-[PSPDFProcessorDelegate processor:didFinishWithData:]
Use completionBlock in the new PDF generation methods.
Removed

-[PSPDFProcessorDelegate processor:didFinishWithFileURL:]
Use completionBlock in the new PDF generation methods.

All these changes result in simpler and safer APIs that are fully compatible with Swift.

Brightness Manager Cleanup

With modern devices supporting a lower screen brightness, PSPDFBrightnessManager has been cleaned up. Additional software dimming is now no longer supported.

Removed

-[PSPDFBrightnessManager brightness]
Use UIScreen.mainScreen.brightness instead.
Removed

-[PSPDFBrightnessManager wantsSoftwareDimming]
Use UIScreen.mainScreen.wantsSoftwareDimming instead.
Removed

-[PSPDFBrightnessManager wantsAdditionalSoftwareDimming]
Additional software dimming support has been removed, as this is less useful with modern devices supporting a lower screen brightness.
Removed

-[PSPDFBrightnessManager additionalBrightnessDimmingFactor]
Additional software dimming support has been removed, as this is less useful with modern devices supporting a lower screen brightness.
Removed

-[PSPDFBrightnessManager maximumAdditionalBrightnessDimmingFactor]
Additional software dimming support has been removed, as this is less useful with modern devices supporting a lower screen brightness.
Removed

-[PSPDFBrightnessViewController brightnessManager]
The brightness is now directly handled on the main screen instead of going through the brightness manager.

Status HUD Support for Multiple Windows

Previously, the status HUD was a singleton that was shared across the entire app. On iOS versions prior to 13, there was only ever a single window, so this was fine. But with the introduction of support for multiple windows in iOS 13, this approach was flawed, and each window scene needed its own status HUD to display content on the correct window. As a result, PSPDFStatusHUD and PSPDFStatusHUDItem changed a bit, since the status HUD now needs a window to coordinate where to show the status HUD item.

Removed

+[PSPDFStatusHUD items]
Changed to +[PSPDFStatusHUD itemsForHUDOnWindow:].
Removed

+[PSPDFStatusHUD popAllItemsAnimated:completion:]
Changed to +[PSPDFStatusHUD popAllItemsAnimated:forHUDOnWindow:completion:].
Removed

-[PSPDFStatusHUDItem pushAnimated:completion:]
Changed to -[PSPDFStatusHUDItem pushAnimated:onWindow:completion:].
Removed

-[PSPDFStatusHUDItem pushAndPopWithDelay:animated:completion:]
Changed to -[PSPDFStatusHUDItem pushAndPopWithDelay:animated:onWindow:completion:].

Other API Changes

Removed

+[PSPDFAnnotation isWriteable]
All non-abstract PSPDFAnnotation subclasses except the non-standard PSPDFEraserAnnotation can be considered writable.
Removed

PSPDFBlurView class
This class provided backward compatibility with iOS versions that did not support UIVisualEffectView. UIVisualEffectView should now be used directly.
Removed

PSPDFTabbedBar.interactiveReorderingGestureRecognizer
The tabbed bar reordering has been changed to use the system drag-and-drop feature instead of interactive reordering.
Changed

PSPDFKit class
Renamed to PSPDFKitGlobal to avoid conflicts with the PSPDFKit module name in Swift.
Changed

+[PSPDFAnnotation isDeletable] and PSPDFAnnotation.shouldDeleteAnnotation
Replaced by a single PSPDFAnnotation.isDeletable property that consolidates both values.
Changed

PSPDFConfiguration.scrollOnTapPageEndEnabled
Renamed to scrollOnEdgeTapEnabled.
Changed

PSPDFConfiguration.scrollOnTapPageEndAnimationEnabled
Renamed to animateScrollOnEdgeTaps.
Changed

PSPDFConfiguration.scrollOnTapPageEndMargin
Renamed to scrollOnEdgeTapMargin.
Changed

PSPDFUsernameHelperWillDismissAlertNotification
Renamed to PSPDFUsernameHelperDidDismissViewNotification. This is posted after the dismissal ends rather than before in order to work better with sheets on iOS 13 that can be dismissed by swiping down.

Removal of Deprecated APIs

All of the previously deprecated APIs have been removed.

PSPDFKitUI

Removed

-[PSPDFAnnotationPresenting didShowPageView:]
Implements -willShowPageView: instead, which is functionally the same but better conveys the timing involved in this method.
Removed

-[PSPDFAnnotationStateManager drawingInputMode]
Sets the state to PSPDFAnnotationStringEraser to use the eraser.
Removed

[PSPDFAnnotationPresenting didShowPageView:]
Implements -willShowPageView: instead, which is functionally the same but better conveys the timing involved in this method.
Removed

[PSPDFAnnotationStateManager drawingInputMode]
Sets the state to PSPDFAnnotationStringEraser to use the eraser.
Removed

[PSPDFHSVColorPickerController minimumSize]
No longer used.
Removed

[PSPDFColorSelectionViewController minimumSize]
No longer used.
Removed

[PSPDFDocumentSharingViewControllerDelegate documentSharingViewController:willShareFiles:]
The returned value from this method is now discarded. Use -[PSPDFDocumentSharingViewControllerDelegate documentSharingViewController:filenameForGeneratedFileForDocument:destination:] to change the names of the generated files.
Removed

[PSPDFDocumentSharingProcessingManagerDelegate sharingProcessingManager:willShareFiles:]
The returned value from this method is now discarded. Use -[PSPDFDocumentSharingProcessingManager sharingProcessingManager:filenameForGeneratedFileForDocument:destination:] to change the names of the generated files.
Removed

[PSPDFSignatureViewController lines]
Use the signature view controller’s drawView.pointSequences instead.
Removed

[PSPDFSignatureViewController keepLandscapeAspectRatio]
A landscape ratio for drawing is now always used by default. Not using a landscape aspect ratio will cause drawing to be cut off on rotation or on app size changes.
Removed

[PSPDFSaveViewController initWithDocumentEditorConfiguration:]
Use initWithSaveDirectories: instead.
Removed

[PSPDFSaveViewController documentEditorConfiguration]
Use saveDirectories and selectedSaveDirectory instead to configure the Document Editor.
Removed

[PSPDFDocumentEditorToolbarController toggleSaveActionSheet:presentationOptions:completionHandler:]
Use the new -toggleSavingConfirmationViewController:presentationOptions:completionHandler: method.
Removed

PSPDFPersistentCloseButtonMode
Persistent close buttons are no longer used by PSPDFKit itself and will be removed in a future release.
Removed

[PSPDFNavigationController persistentCloseButtonMode]
Persistent close buttons are no longer used by PSPDFKit itself and will be removed in a future release.
Removed

[PSPDFNavigationController setDelegate:]
Not available.
Removed

[PSPDFNavigationController persistentCloseButton]
Persistent close buttons are no longer used by PSPDFKit itself and will be removed in a future release.
Removed

[PSPDFUserInterfaceView thumbnailBarInsets]
Use -[PSPDFUserInterfaceView scrubberBarInsets:] instead to add insets to the thumbnail bar.
Removed

PSPDFPresentationPersistentCloseButtonKey
This option is no longer used by PSPDFKit itself and will be removed in a future release.
Removed

[PSPDFDigitalSignatureCoordinator presentSignedDocument:showingPageIndex:]
Use presentSignedDocument:showingPageIndex:withPresentationContext: instead.
Removed

[PSPDFFlexibleToolbarContainer isFlickToCloseEnabled]
The flick-to-close feature has been removed, and modifying this property no longer has any effect.
Removed

[PSPDFBookmarkCell bookmarkString]
The bookmark cell contains multiple labels now. Use the appropriate text fields or labels instead.
Removed

[PSPDFScrubberBar isSmallToolbar]
The toolbar can have more than two different sizes now. Override scrubberBarHeight to change the scrubber bar size. Overriding isSmallToolbar no longer has any effect.

PSPDFKit

Removed

[PSPDFBookmarkManager removeBookmarkForPageAtIndex:]
Use the more accurately named removeBookmarksForPageAtIndex: method instead.
Removed

+[PSPDFStampAnnotation stampColorForSubject:]
Use colorForStampType: instead.
Removed

[PSPDFStampAnnotation initWithSubject:]
For a standard stamp, use initWithStampType:. For custom text, use initWithTitle:.
Removed

[PSPDFStampAnnotation localizedSubject]
Use title instead.
Removed

[PSPDFStampAnnotation subtext]
Use subtitle instead.
Removed

[PSPDFStampAnnotation subject]
Consider stampType or title, or cast to PSPDFAnnotation if you really want the subject.
Removed

[PSPDFDocument applyInstantJSONFromDataProvider:toDocumentProvider:error:]
Use applyInstantJSONFromDataProvider:toDocumentProvider:lenient:error: instead
Removed

PSPDFDocumentSaveOptionForceRewrite
Use PSPDFDocumentSaveOptionForceSaving instead.
Removed

[PSPDFSigner externalSignatureDelegate]
Instead of the externalSignatureDelegate property, you can use the delegate property for greater flexibility.
Removed

[PSPDFSigner signFormElement:withCertificate:writeTo:appearance:biometricProperties:completionBlock:]
Call signFormElement:withCertificate:writeTo:completionBlock: instead and set the dataSource to configure the signature properties.
Removed

[PSPDFSigner signFormElement:withCertificate:writeToDataSink:appearance:biometricProperties:completionBlock:]
Call signFormElement:withCertificate:writeToDataSink:completionBlock: instead and set the dataSource to configure the signature properties.
Changed

PSPDFSignatureInputMethodNone
Enum has been renamed to PSPDFDrawInputMethod*.
Changed

PSPDFSignatureInputMethodFinger
Enum has been renamed to PSPDFDrawInputMethod*.
Changed

PSPDFSignatureInputMethodApplePencil
Enum has been renamed to PSPDFDrawInputMethod*.
Changed

PSPDFSignatureInputMethodThirdPartyStylus
Enum has been renamed to PSPDFDrawInputMethod*.
Changed

PSPDFDrawInputMethodThirdPartyStylus
Enum has been renamed to PSPDFDrawInputMethod*.
Changed

PSPDFSignatureInputMethodMouse
Enum has been renamed to PSPDFDrawInputMethod*.