PSPDFKit 9.3 Migration Guide

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 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 guide to learn more about this, including how to disable this behavior.

Objective-C Changes

If you’re using the PSPDFKit SDK with Swift, please 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. Please use -[PSPDFFreeTextAnnotation convertIntentTypeTo:] instead.

  • Changed

    -[PSPDFSoundAnnotation initWithRecorder] has been deprecated. Please use -[PSPDFSoundAnnotation initWithRecorderOptions:] with a nil parameter for options instead.

Swift-Only Changes

If you’re using the PSPDFKit SDK with Objective-C, please 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).

ℹ️ Note: Most of the API changes can be reliably fixed using the Fix All Issues option (Ctrl + Option + Command + F) in Xcode. This fixes all the issues in the currently opened file. Some of the files may require multiple iterations of using Xcode’s fix option, as some the errors will only be caught after the initially shown errors are fixed.

  • 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

ℹ️ Note: If any of these types happen to clash with other declarations in Swift, this can be resolved by accessing the type using the module name. For example, use PSPDFKitUI.GalleryItem.Option.autoPlay instead of GalleryItem.Option.autoPlay.

  • 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. Please use the init?(kind:) initializer on Annotation.Tool instead.

  • Removed

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

  • Removed

    The PSPDFAnnotationStateVariantIDMake() helper for generating Annotation.ToolVariantID has been removed. Please use Annotation.ToolVariantID(tool:, variant:) instead.

  • Removed

    The PSPDFAnnotationStateFromStateVariantIdentifier() helper for extracting Annotation.Tool has been removed. Please use the tool property on Annotation.ToolVariantID instead.

  • Removed

    The PSPDFAnnotationVariantFromStateVariantIdentifier() helper for extracting Annotation.Variant has been removed. Please 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. Please 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. Please 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.

ℹ️ Note: The above change affects the NoteAnnotation API. Since the two types have been reorganized into a single type (Annotation.State), NoteAnnotation uses a single property (authorState) to show the author-specific state. This means that the other property, authorStateModel, has been removed.

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. Please 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. Please 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. Please 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
old-note-annotation-icon new-note-annotation-icon

Flexible Toolbar Position

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 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, please remove the conformance. It will no longer work with the class overriding mechanism.