This guide covers updating an iOS or Mac Catalyst project from PSPDFKit 9.2.2 for iOS to PSPDFKit 9.3 for iOS. We encourage you to update as soon as possible, in order to take advantage of future new features and fixes.

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

Document Permissions

A PDF document defines a set of permissions that enable/disable certain actions a user can take with the document. These permissions cover things like printing, annotation modification, and content extraction.

Prior to this release, we could read and write user permissions on a PDF document, but most of them were ignored by the SDK. PSPDFKit 9.3 for iOS adds comprehensive support for all available document permissions(opens in a new tab) so that the relevant UI actions are enabled/disabled based on which permissions are available.

The permissions are defined using the DocumentPermissions API (PSPDFDocumentPermissions in Objective-C). Here’s a brief list of the effects each permission has when disabled:

• .printing — The UIActivityTypePrint activity will be removed from the available sharing activities when using the DocumentSharingConfiguration.Destination.activity sharing destination, and the DocumentSharingConfiguration.Destination.print sharing destination will not be available.
• .extract — The user will not be able to copy selected text or images.
• .assemble — The user will not be able to enter the Document Editor view mode.
• .annotationsAndForms — The user will not be able to create new annotations; move, resize, or rotate existing annotations; or add comments to existing annotations.
• .fillForms — If disabled along with .annotationsAndForms, the user will not be able to fill in form fields, including signature fields, checkboxes, and radio buttons.
• .modification — The user will not be able to add or edit bookmarks, redact portions of a document, or edit information like a document’s title and author information.

Make sure to read the document permissions(opens in a new tab) guide to learn more about this, including how to disable this behavior.

Objective-C Changes

If you’re using the PSPDFKit SDK with Swift, jump to the Swift-Only Changes section.

• Changed: Presentation option constants for the PSPDFPresentationActions protocol have been deprecated in favor of renamed constants with the PSPDFPresentationOption prefix. This is for consistency and improved Swift interoperability.

Deprecated API	Replacement API
PSPDFPresentationStyleKey	PSPDFPresentationOptionPresentationStyle
PSPDFPresentationHalfModalStyleKey	PSPDFPresentationOptionHalfModalStyle
PSPDFPresentationNonAdaptiveKey	PSPDFPresentationOptionNonAdaptive
PSPDFPresentationRectBlockKey	PSPDFPresentationOptionSourceRectProvider
PSPDFPresentationContentSizeKey	PSPDFPresentationOptionContentSize
PSPDFPresentationInNavigationControllerKey	PSPDFPresentationOptionInNavigationController
PSPDFPresentationReuseNavigationControllerKey	PSPDFPresentationOptionReuseNavigationController
PSPDFPresentationPopoverArrowDirectionsKey	PSPDFPresentationOptionPopoverArrowDirections
PSPDFPresentationPopoverPassthroughViewsKey	PSPDFPresentationOptionPopoverPassthroughViews
PSPDFPresentationPopoverBackgroundColorKey	PSPDFPresentationOptionPopoverBackgroundColor
PSPDFPresentationRectKey	PSPDFPresentationOptionSourceRect
PSPDFPresentationCloseButtonKey	PSPDFPresentationOptionCloseButton
PSPDFViewControllerSearchHeadlessKey	PSPDFPresentationOptionSearchHeadless

• Changed: Similarly, the existing constants used to access the contents of the dictionary objects of PSPDFGalleryItem have been deprecated in favor of a new type, PSPDFGalleryItemProperty.

Deprecated API	Replacement API
PSPDFGalleryItemTypeKey	PSPDFGalleryItemPropertyType
PSPDFGalleryItemContentURLKey	PSPDFGalleryItemPropertyURL
PSPDFGalleryItemCaptionKey	PSPDFGalleryItemPropertyCaption
PSPDFGalleryItemOptionsKey	PSPDFGalleryItemPropertyOptions

• Changed: The following cases from the PSPDFFlexibleToolbarPosition enum have been deprecated and replaced.

Deprecated API	Replacement API
PSPDFFlexibleToolbarPositionsVertical	PSPDFFlexibleToolbarPositionVertical
PSPDFFlexibleToolbarPositionsAll	PSPDFFlexibleToolbarPositionAll

• Changed: The existing PSPDFSettingKey constants have been deprecated in favor of the new ones, which are more semantically named.

Deprecated API	Replacement API
PSPDFXCallbackURLStringKey	PSPDFSettingKeyXCallbackURLString
PSPDFApplicationPolicyKey	PSPDFSettingKeyApplicationPolicy
PSPDFFileManagerKey	PSPDFSettingKeyFileManager
PSPDFCoordinatedFileManagerKey	PSPDFSettingKeyCoordinatedFileManager
PSPDFFileCoordinationEnabledKey	PSPDFSettingKeyFileCoordinationEnabled
PSPDFLibraryIndexingPriorityKey	PSPDFSettingKeyLibraryIndexingPriority
PSPDFKitDebugModeKey	PSPDFSettingKeyDebugMode
PSPDFAdditionalFontDirectories	PSPDFSettingKeyAdditionalFontDirectories
PSPDFHonorDocumentPermissionsKey	PSPDFSettingKeyHonorDocumentPermissions

• Changed: The existing PSPDFAnnotationOption constants have been deprecated in favor of the new ones, which are semantically named for improved Swift interoperability.

Deprecated API	Replacement API
PSPDFAnnotationOptionAnimateViewKey	PSPDFAnnotationOptionAnimateView
PSPDFAnnotationOptionSuppressNotificationsKey	PSPDFAnnotationOptionSuppressNotifications

• Changed: The PSPDFRectAlignment API cases have been renamed to provide better interoperability in Swift.

Previous API	New API
PSPDFRectAlignCenter	PSPDFRectAlignmentCenter
PSPDFRectAlignTop	PSPDFRectAlignmentTop
PSPDFRectAlignTopLeft	PSPDFRectAlignmentTopLeft
PSPDFRectAlignTopRight	PSPDFRectAlignmentTopRight
PSPDFRectAlignLeft	PSPDFRectAlignmentLeft
PSPDFRectAlignBottom	PSPDFRectAlignmentBottom
PSPDFRectAlignBottomLeft	PSPDFRectAlignmentBottomLeft
PSPDFRectAlignBottomRight	PSPDFRectAlignmentBottomRight
PSPDFRectAlignRight	PSPDFRectAlignmentRight

• Changed: The fields property of PSPDFAbstractFormAnnotation is now typed NSArray<id<PSPDFFormFieldIdentifier>> *, in order to more clearly document what this property contains. The newly introduced PSPDFFormFieldIdentifier protocol is a trait added to NSString and NSNumber.

• Changed: -[PSPDFFreeTextAnnotation convertToIntentType:] has been deprecated. Use -[PSPDFFreeTextAnnotation convertIntentTypeTo:] instead.

• Changed: -[PSPDFSoundAnnotation initWithRecorder] has been deprecated. Use -[PSPDFSoundAnnotation initWithRecorderOptions:] with a nil parameter for options instead.

Swift-Only Changes

If you’re using the PSPDFKit SDK with Objective-C, check out the Objective-C Changes section.

The entire SDK has been carefully tweaked to make the entirety of our API semantic in Swift. We dropped the PSPDF prefix and tried to group related APIs by nesting them where appropriate and possible. Due to the vastness of the changes, and in order to keep the migration guide concise, we’ve only mentioned the API changes that could break your build and which cannot be fixed using Xcode’s suggestion (the Fix button).

• Changed: The String constants used in the PSPDFPresentationActions protocol have been removed in favor of the new Swift struct type, PresentationOption. All the places where the old constants are used as arguments will throw an error while compiling since the type of the method arguments has also been changed from String to the appropriate new struct type.

Previous API	New API
PSPDFPresentationStyleKey	.presentationStyle
PSPDFPresentationHalfModalStyleKey	.halfModalStyle
PSPDFPresentationNonAdaptiveKey	.nonAdaptive
PSPDFPresentationRectBlockKey	.sourceRectProvider
PSPDFPresentationContentSizeKey	.contentSize
PSPDFPresentationInNavigationControllerKey	.inNavigationController
PSPDFPresentationReuseNavigationControllerKey	.reuseNavigationController
PSPDFPresentationPopoverArrowDirectionsKey	.popoverArrowDirections
PSPDFPresentationPopoverPassthroughViewsKey	.popoverPassthroughViews
PSPDFPresentationPopoverBackgroundColorKey	.popoverBackgroundColor
PSPDFPresentationRectKey	.sourceRect
PSPDFPresentationCloseButtonKey	.closeButton
PSPDFViewControllerSearchHeadlessKey	.searchHeadless

• Changed: The constants used for accessing the dictionary values of a PSPDFGalleryItem have been replaced with the GalleryItem.Property struct.

Previous API	New API
PSPDFGalleryItemTypeKey	.type
PSPDFGalleryItemContentURLKey	.contentURL
PSPDFGalleryItemCaptionKey	.caption
PSPDFGalleryItemOptionsKey	.options

• Changed: The PSPDFAnnotationOption type has been renamed to AnnotationManager.ChangeBehaviorKey in Swift. Its existing values have been deprecated in favor of semantically named ones.

Deprecated API	New API
.animateViewKey	.animateView
.notificationsKey	.suppressNotifications

• Changed: The PSPDFRectAlignment enumeration has been renamed to RectAlignment for Swift. Its cases have also been renamed.

Previous API	New API
.alignCenter	.center
.alignTop	.top
.alignTopLeft	.topLeft
.alignTopRight	.right
.alignLeft	.left
.alignBottom	.bottom
.alignBottomLeft	.bottomLeft
.alignBottomRight	.bottomRight
.alignRight	.right

• Changed: PSPDFFlexibleToolbarPosition has been updated with a new Swift name, FlexibleToolbar.Position. Some position values have been deprecated and replaced with new ones to ensure better translation to Swift names.

Previous API	New API
.positionNone	.none
.positionInTopBar	.inTopBar
.positionLeft	.left
.positionRight	.right
.positionsVertical	.vertical
.positionsAll	.all

• Changed: PSPDFSettingKey has been renamed to SDK.Setting, and the existing constants have been deprecated in favor of new ones, which are more semantically named.

Deprecated API	Replacement API
.PSPDFXCallbackURLStringKey	.xCallbackURLString
.applicationPolicyKey	.applicationPolicy
.fileManagerKey	.fileManager
.coordinatedFileManagerKey	.coordinatedFileManager
.fileCoordinationEnabledKey	.fileCoordinationEnabled
.libraryIndexingPriorityKey	.libraryIndexingPriority
.debugModeKey	.debugMode
.additionalFontDirectories	.additionalFontDirectories
.honorDocumentPermissionsKey	.honorDocumentPermissions

• Changed: PSPDFMetadataName has been renamed to PDFMetadata.Key, and the existing constants have been deprecated in favor of new ones, which are more semantically named.

Previous API	New API
.titleKey	.title
.authorKey	.author
.subjectKey	.subject
.keywordsKey	.keywords
.creatorKey	.creator
.producerKey	.producer
.creationDateKey	.creationDate
.modDateKey	.modificationDate
.trappedKey	.trapped

• Changed: PSPDFValueTransformerName has been renamed to ValueTransformerName, and the existing constants have been replaced. See below for the list.

Previous API	New API
.actionTypeTransformerName	.actionType
.annotationTriggerEventTransformerName	.annotationTriggerEvent
.borderEffectTransformerName	.borderEffect
.borderStyleTransformerName	.borderStyle
.freeTextAnnotationIntentTransformerName	.freeTextAnnotationIntent
.namedActionTypeTransformerName	.namedActionType
.polygonAnnotationIntentTransformerName	.polygonAnnotationIntent
.renditionActionTypeTransformerName	.renditionActionType
.verticalAlignmentTransformerName	.verticalAlignment

• Changed: PSPDFDocumentUnderlyingFileChangedNotificationOptions has been renamed to Document.UnderlyingFileChangedNotificationOption, and the existing constants have been replaced. See below for the list.

Previous API	New API
.urlKey	.changedFileURL
.willBeDeletedKey	.deleteFile

Annotation API Refinements

• Changed: AnnotationStyleType has been renamed to AnnotationStyle.Kind.

Previous API	New API
.titleKey	.title
.authorKey	.author
.subjectKey	.subject
.keywordsKey	.keywords
.creatorKey	.creator
.producerKey	.producer
.creationDateKey	.creationDate

• Changed: AnnotationStyleKey has been renamed to AnnotationStyle.Key.

• Changed: AnnotationString has been renamed to Annotation.Tool.

• Changed: AnnotationVariantString has been renamed to Annotation.Variant.

• Changed: AnnotationStateVariantID has been renamed to Annotation.ToolVariantID.

• Removed: The PSPDFStringFromAnnotationType() helper for creating Annotation.Tool from Annotation.Kind has been removed. Use the init?(kind:) initializer on Annotation.Tool instead.

• Removed: The PSPDFAnnotationTypeFromString() helper for creating Annotation.Kind from Annotation.Tool has been removed. Use the init(tool:) initializer on Annotation.Kind instead.

• Removed: The PSPDFAnnotationStateVariantIDMake() helper for generating Annotation.ToolVariantID has been removed. Use Annotation.ToolVariantID(tool:, variant:) instead.

• Removed: The PSPDFAnnotationStateFromStateVariantIdentifier() helper for extracting Annotation.Tool has been removed. Use the tool property on Annotation.ToolVariantID instead.

• Removed: The PSPDFAnnotationVariantFromStateVariantIdentifier() helper for extracting Annotation.Variant has been removed. Use the variant property on Annotation.ToolVariantID instead.

• Changed: The type of the Annotation.additionalActions property has been changed to [Annotation.TriggerEvent: Action].

• Changed: The type of the Annotation.dashArray property has been changed to [CGFloat].

• Changed: The type of the Annotation.rects property has been changed to [CGRect].

• Changed: The type of the Annotation.points property has been changed to [CGPoint].

• Changed: The AbstractFormAnnotation.fields property has been renamed to fieldIdentifiers to more clearly document what this array contains. Its type has been changed from [Any]? to [FormFieldIdentifier]?, where the nested enum FormFieldIdentifier further documents the semantics. For coding convenience, the enum is both ExpressibleByIntegerLiteral and ExpressibleByStringLiteral.

• Added: A new type, PDFLine, which is a type alias for an array of DrawingPoint ([DrawingPoint]), has been added.

• Added: A new type, ViewLine, which is a type alias for an array of CGPoint ([CGPoint]), has been added.

• Removed: InkAnnotation(lines: [[NSValue]]) has been removed. Use InkAnnotation(lines: [PDFLine]) instead.

• Changed: The type of the InkAnnotation.lines property has been updated from [[NSValue]] to [PDFLine]).

• Changed: The type of the points parameter in initializers of AbstractLineAnnotation (formerly PSPDFAbstractLineAnnotation) and PolygonAnnotation has been updated to an array of CGPoint instead of an array of NSValue. Updated APIs: AbstractLineAnnotation(points: [CGPoint]), PolygonAnnotation(points: [CGPoint], intentType: PolygonAnnotation.Intent = .none)

• Removed: FreeTextAnnotation.convert(toIntentType:) has been deprecated. Use FreeTextAnnotation.convertIntent(to:) instead.

• Changed: The rects parameter to TextMarkupAnnotation’s class method — textOverlayAnnotation(withRects:,boundingBox:,pageIndex:) — has been changed from [NSValue] to [CGRect]. The signature of this method is now class func textOverlayAnnotation(withRects rects: [CGRect], boundingBox: CGRect, pageIndex: Int) -> Self?.

• Changed: The PSPDFAnnotationAuthorState and PSPDFAnnotationAuthorStateModel APIs have been consolidated into the Annotation.State API, which is an enum with associated values. Below is the list of the possible values for the Annotation.State type.

Annotation.State
.unspecified
.marking(Annotation.State.MarkedModel)
.reviewing(Annotation.State.ReviewModel)

• Changed: SoundAnnotation(recorderOptions:) has been updated to take a parameter of type Set<SoundAnnotation.RecorderOption> instead of a dictionary. SoundAnnotation.RecorderOption is an enum with associated values that can be used to configure a recorder.
• Removed: The SoundAnnotation.initWithRecorder() API has been removed. Use SoundAnnotation(recorderOptions:) by passing an empty set as the recorderOptions: parameter instead.

SoundAnnotation.RecorderOption
.encoding(SoundAnnotation.Encoding)
.channels(UInt32)
.sampleRate(hertz: SoundAnnotation.RecorderOption.SampleRate)
.bitsPerSample(SoundAnnotation.RecorderOption.Depth)

Document API Refinements

• Removed: The save(options: [PSPDFDocumentSaveOption : Any]) throws API on Document (formerly PSPDFDocument) has been removed. Use the save(options: Set<SaveOption>) throws API instead.
• Removed: The save(options: [PSPDFDocumentSaveOption : Any]?, completionHandler: ((Error?, [PSPDFAnnotation]) -> Void)?) API of Document has also been removed. Use save(options: Set<SaveOption> = [], completion: @escaping (Result<[Annotation], Error>) -> Void) instead.

Note Annotation Icon

• Changed: The icon used for representing the note annotation tool in the annotation toolbar has been replaced. You can read more about how to customize the icon in our customizing the annotation toolbar guide.

Old	New

Flexible Toolbar Position

• Changed: The default value for FlexibleToolbarPosition(opens in a new tab)’s supportedToolbarPositions(opens in a new tab) property has changed from .all(opens in a new tab) to .default(opens in a new tab). If you were programmatically setting your toolbar’s supportedToolbarPositions(opens in a new tab) to .all(opens in a new tab), use .default(opens in a new tab) instead to support the default toolbar positions. For more details on how to customize the toolbar positions, take a look at both our customizing the annotation toolbar guide and ToolbarPositionTopExample.swift(opens in a new tab) from the Catalog app(opens in a new tab).

Class Overriding

The class overriding mechanism is now more type-safe and better documented. All classes that can be overridden now conform to the Overridable(opens in a new tab) protocol. Classes that don’t conform to it are no longer accepted by overrideClass(_:with:) and can no longer participate in the mechanism.

If you were overriding an illicit class, you might now see compile warnings or errors. If you were implementing the Overridable protocol in your own classes, remove the conformance. It will no longer work with the class overriding mechanism.