--- title: "PSPDFKit 3 Migration Guide" canonical_url: "https://www.nutrient.io/guides/ios/migration-guides/pspdfkit-3-migration-guide/" md_url: "https://www.nutrient.io/guides/ios/migration-guides/pspdfkit-3-migration-guide.md" last_updated: "2026-06-08T17:11:05.545Z" description: "Discover how to transition to PSPDFKit 3.0 for iOS, including new licensing, project settings, and API changes. Get started with our essential guide!" --- PSPDFKit 3.0.0 for iOS is the forthcoming major release of [PSPDFKit](http://pspdfkit.com), an extensive PDF displaying and editing framework for iOS. As a major release, 3.0 introduces several API-breaking changes and new architecture. This guide is a starting point to ease the transition to PSPDFKit 3.0 for iOS. ## Requirements PSPDFKit 3 for iOS requires iOS 6 and Xcode 5.x. Starting with PSPDFKit 3.3, we require Xcode 5, and we no longer support compilation with legacy mode. ### New Licensing Model PSPDFKit 3 now requires a serial number to unlock its features. Log in at http://my.pspdfkit.com with your account details. If you don’t yet have an account, request one at [support@pspdfkit.com](mailto:support@pspdfkit.com). You’ll have to add the call to `PSPDFSetLicenseKey()` in your app delegate before you call or use any PSPDFKit classes. ## Project Settings PSPDFKit 3 requires several new frameworks. If you use `PSPDFKit.xcconfig`, you’re all set, unless you manually changed the Other Linker Flags setting in your project. Either merge the settings, remove yours, or manually add the required frameworks (you’ll find all the details if you open the `PSPDFKit.xcconfig` file). ## API Changes Several API methods, enums, and constants have been renamed to improve clarity in the API. Most constants are now named like `PSPDFObjectsGlyphs`; previously, in PSPDFKit 2 for iOS, they were named inconsistently and mostly had a style like `kPSPDFObjectsGlyphs`. In general, a look at the header should help you find the new matching API quickly. Several methods also have additional parameters and no simple counterpart to keep the API clean. For example, the `dismissAnimated:` method in `PSPDFBarButtonItem` has been extended to `dismissAnimated:completion:`. ### Classes Several classes have been renamed. All `PSPDFAction***` classes now are named `PSPDF***Action` to better reflect their types. ### Deprecations All deprecated methods in PSPDFKit 2 for iOS have been removed. PSPDFKit 3 for iOS doesn’t feature deprecated methods, so for deeper integrations, you’ll need to invest some time up front to upgrade your codebase. ### Class Overriding Direct access to `overrideClassNames` has been removed. Use [`overrideClass:withClass:`](https://www.nutrient.io/api/ios/documentation/pspdfkit/document/overrideclass(_:with:)) to register your subclasses. Remember that all view/controller-related classes need to be registered in [`PSPDFConfiguration`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/pdfconfiguration), while model classes are in [`PSPDFDocument`](https://www.nutrient.io/api/ios/documentation/pspdfkit/document). ### New Annotation Toolbar The annotation bar has been completely redesigned. Several subclassing hooks have been changed as well to reflect this. PSPDFKit 3 for iOS also has several new annotation tools that you might want to enable if you manually set the contents of the [`editableAnnotationTypes`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/pdfconfiguration/editableannotationtypes) dictionary in [`PSPDFDocument`](https://www.nutrient.io/api/ios/documentation/pspdfkit/document). Notable additions are the [`PSPDFAnnotationStringEraser`](https://www.nutrient.io/api/ios/documentation/pspdfkit/annotation/tool/eraser) and [`PSPDFAnnotationStringSelectionTool`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/pspdfkit/annotation/tool/selectiontool) instruments. ## The Annotation Data Model In PSPDFKit 2 for iOS, several annotation types were groups for multiple annotations. This has been simplified. Starting with PSPDFKit 3 for iOS, each annotation type string corresponds to exactly one annotation type. You can convert between these two representations via [`PSPDFStringFromAnnotationType()`](https://www.nutrient.io/api/ios/documentation/pspdfkit/pspdfstringfromannotationtype) and [`PSPDFAnnotationTypeFromString()`](https://www.nutrient.io/api/ios/documentation/pspdfkit/pspdfannotationtypefromstring). Furthermore, the annotations string name has been simplified from `PSPDFAnnotationTypeString***` to `PSPDFAnnotationString***`. To create an underline annotation, you can now use [`PSPDFUnderlineAnnotation`](https://www.nutrient.io/api/ios/documentation/pspdfkit/underlineannotation) instead of setting a custom `PSPDFHighlightAnnotationType` on the `PSPDFHighlightAnnotation`. ### Saving Previously, `saveChangedAnnotationsWithError:` was only allowed to be called on the main thread, took a lot of time, and afterward destroyed the current `documentProviders`. Then annotations were parsed again. This process has been greatly optimized and streamlined. PSPDFKit 3 for iOS can now deal with saving in the background and can correctly update the current annotation set without the need to reparse. There’s a new asynchronous API for saving — [`saveAnnotationsWithCompletionBlock:`](https://www.nutrient.io/api/ios/documentation/pspdfkit/document) — and the synchronous API has been renamed to `saveAnnotationsWithError:`, since depending on the set of `annotationProviders`, save might save all annotations and not just the changed ones. ### The External Annotation Data Model (NSCoder) The `NSCoder` data model for saving annotations has been radically changed. To support archives that have been saved with v2, you need to call `PSPDFAnnotationSupportLegacyFormat()` with the `NSKeyedUnarchiver` as an argument and afterward process the unarchived annotations with `PSPDFPostprocessAnnotationInLegacyFormat()` to convert them to the v3 format. ### JSON Serialization There’s no direct support to parse the v2 JSON format in v3 — you need to write your own converter if this is required. In v3, you can create JSON using the `PSPDFJSONAdapter` class and by calling `JSONDictionaryFromModel:`. [`PSPDFAnnotation`](https://www.nutrient.io/api/ios/documentation/pspdfkit/annotation) now also has a factory method that converts the JSON to the correct types via the static `+ annotationFromJSONDictionary:document:error:` method. The `document` parameter is only required if you have subclasses defined that should be used in place of the default annotation types. ### XFDF Support PSPDFKit now supports the [Adobe XFDF 3.0 spec](https://www.iso.org/obp/ui/#iso:std:iso:19444:-1:ed-1:v1:en), which can be read in Adobe Acrobat and other frameworks that support XFDF. This is your new preferred way to send data to a server, since it’s standardized XML. This is compared to the proprietary way of encoding annotation data that’s used in `NSCoder` and JSON serialization. There’s also a [`PSPDFXFDFAnnotationProvider`](https://www.nutrient.io/api/ios/documentation/pspdfkit/xfdfannotationprovider) for your convenience, which takes a `fileURL` to load/save but can be used as a template to build your web-based version for sending/receiving XFDF. ### Value Transformers JSON serialization uses various value transformers to convert things — for example, enums — into more a useful representation (strings). The `NSValueTransformer` subclasses have been directly exposed in v2. In PSPDFKit 3 for iOS, we use the more appropriate way of only exposing the name (like `PSPDFLinesTransformerName`). You can fetch the subclasses from the global registry of the `NSValueTransformer` class with `valueTransformerForName:`. ### Change Notifications In PSPDFKit 2 for iOS, it was necessary to call `copyAndDeleteOriginalIfNeeded` for changing annotations and to send a `PSPDFAnnotationChangeNotificationOriginalAnnotationKey`. This was the reason for lots of subtle bugs and unnecessary complexity, and it’s been removed in v3. You still need to send change notifications ([`PSPDFAnnotationChangedNotification`](https://www.nutrient.io/api/ios/documentation/pspdfkit/foundation/nsnotification/name/pspdfannotationchanged)), but it’s no longer necessary to create a copy of the annotation. ### Deleting Annotations In v2, the only way to delete annotations was setting `deleted = YES` on the annotation object. Starting with v3, there’s an API for this, both in [`PSPDFDocument`](https://www.nutrient.io/api/ios/documentation/pspdfkit/document) [`removeAnnotations:`](https://www.nutrient.io/api/ios/documentation/pspdfkit/document/remove(annotations:options:)) and also in the `PSPDFAnnotationManager`. Annotations might still use the above soft delete or a real delete; this is decided in the current [`PSPDFAnnotationProvider`](https://www.nutrient.io/api/ios/documentation/pspdfkit/annotationprovider) implementation. #### PSPDFAnnotationProvider Annotation providers now have to deal with annotation deletion, and the API has been changed in several other ways. Study the new protocol header for details. #### PSPDFAnnotationManager `PSPDFAnnotationParser` has been renamed to `PSPDFAnnotationManager` to better reflect what it actually does (collecting annotations and managing annotation providers). Accessor methods have been changed from `annotationParser` and `annotationParserForPage:` to `annotationManagerForPage:`. ### Document Sharing The methods to send a document via email or use the Open In... feature have been unified. Both have lost their custom configuration methods and were replaced with the new `PSPDFDocumentSharingController`, which features a simpler and more flexible way of selecting flattening/annotations and the page range. ### PSPDFViewControllerDelegate - The `pdfViewController:willDisplayDocument:` delegates were confusing and mostly just a forwarding of `viewWillAppear:`. They’ve been replaced by `pdfViewController:shouldChangeDocument:` and `pdfViewController:didChangeDocument:`. - APIs that had one annotation as an argument have been replaced with `NSArray*`, since v3 now supports selecting multiple annotations at once. For example, `pdfViewController:didSelectAnnotation:onPageView:` is now called `pdfViewController:didSelectAnnotations:onPageView:` and sends an `NSArray*` instead of a single `PSPDFAnnotation*`. - The `pdfViewController:shouldShowController:embeddedInController:animated:` API now offers an additional `options:` argument. - The `pdfViewController:willShowHUD:` method was redundant and has been removed. Use `pdfViewController:shouldShowHUD` and return `YES` to be notified before the HUD shows. --- ## Related pages - [14 9 Migration Guide](/guides/ios/migration-guides/14-9-migration-guide.md) - [14 2 Migration Guide](/guides/ios/migration-guides/14-2-migration-guide.md) - [Migrating From Apple Pdfkit](/guides/ios/migration-guides/migrating-from-apple-pdfkit.md) - [Pspdfkit 10 3 Migration Guide](/guides/ios/migration-guides/pspdfkit-10-3-migration-guide.md) - [Migrating To Advanced Digital Signatures Api](/guides/ios/migration-guides/migrating-to-advanced-digital-signatures-api.md) - [Pspdfkit 10 4 Migration Guide](/guides/ios/migration-guides/pspdfkit-10-4-migration-guide.md) - [Pspdfkit 10 Migration Guide](/guides/ios/migration-guides/pspdfkit-10-migration-guide.md) - [Migrate to electronic signatures](/guides/ios/migration-guides/migrating-to-electronic-signatures.md) - [Pspdfkit 11 3 Migration Guide](/guides/ios/migration-guides/pspdfkit-11-3-migration-guide.md) - [Pspdfkit 11 5 Migration Guide](/guides/ios/migration-guides/pspdfkit-11-5-migration-guide.md) - [Pspdfkit 12 2 Migration Guide](/guides/ios/migration-guides/pspdfkit-12-2-migration-guide.md) - [Pspdfkit 13 3 Migration Guide](/guides/ios/migration-guides/pspdfkit-13-3-migration-guide.md) - [Pspdfkit 12 3 Migration Guide](/guides/ios/migration-guides/pspdfkit-12-3-migration-guide.md) - [Pspdfkit 13 Migration Guide](/guides/ios/migration-guides/pspdfkit-13-migration-guide.md) - [Pspdfkit 4 Migration Guide](/guides/ios/migration-guides/pspdfkit-4-migration-guide.md) - [Pspdfkit 6 5 Migration Guide](/guides/ios/migration-guides/pspdfkit-6-5-migration-guide.md) - [Pspdfkit 12 Migration Guide](/guides/ios/migration-guides/pspdfkit-12-migration-guide.md) - [Pspdfkit 11 4 Migration Guide](/guides/ios/migration-guides/pspdfkit-11-4-migration-guide.md) - [Pspdfkit 5 Migration Guide](/guides/ios/migration-guides/pspdfkit-5-migration-guide.md) - [Pspdfkit 6 Migration Guide](/guides/ios/migration-guides/pspdfkit-6-migration-guide.md) - [Pspdfkit 7 6 Migration Guide](/guides/ios/migration-guides/pspdfkit-7-6-migration-guide.md) - [Pspdfkit 9 2 Migration Guide](/guides/ios/migration-guides/pspdfkit-9-2-migration-guide.md) - [Upgrading](/guides/ios/getting-started/upgrading.md) - [Pspdfkit 9 4 Migration Guide](/guides/ios/migration-guides/pspdfkit-9-4-migration-guide.md) - [Pspdfkit 9 3 Migration Guide](/guides/ios/migration-guides/pspdfkit-9-3-migration-guide.md) - [Pspdfkit 9 5 Migration Guide](/guides/ios/migration-guides/pspdfkit-9-5-migration-guide.md) - [Pspdfkit 9 Migration Guide](/guides/ios/migration-guides/pspdfkit-9-migration-guide.md) - [Migrate to PSPDFKit 7 with ease](/guides/ios/migration-guides/pspdfkit-7-migration-guide.md) - [PSPDFKit 8 migration guide for iOS developers](/guides/ios/migration-guides/pspdfkit-8-migration-guide.md)