iOS PSPDFKit 8 Migration Guide | Comprehensive Step-by-Step Tutorial

This guide covers updating an iOS project from PSPDFKit 7.x to PSPDFKit 8. Despite the major version change, the version 8 update should be relatively straightforward, so we encourage you to update as soon as possible, in order to take advantage of future new features and fixes.

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

Sharing Architecture Changes

Up until now, invoking the share action in PSPDFKit directly presented a UIActivityViewController. We then had to identify the activity that was selected from the share sheet to see if we could inject our customization logic. This allowed the user to decide if they wanted to embed, flatten, or ignore annotations, along with other customization options.

One major downside this approach had is that we couldn’t offer customization options for every item in the share sheet, which resulted in a less than optimal experience: Sharing a document to Mail.app would let the user decide whether or not they wanted to embed or flatten the annotations into the shared document, but sharing to WhatsApp or Messenger wouldn’t.

In PSPDFKit 8 for iOS, the way documents are shared was revamped to offer a significantly improved experience that allows the user to pick their desired sharing options while being flexible enough to offer customization options that allow developers to adjust the experience to their liking.

As a consequence, the API related to sharing changed a bit:

• PSPDFDocumentSharingCoordinator and its subclasses (Mail, Messages, OpenIn) were removed.

• All sharing-related properties in PSPDFConfiguration were removed. They were replaced with a new sharingConfigurations property that holds an array of PSPDFDocumentSharingConfiguration objects.

To learn more about the new document sharing flow and customization options, refer to our dedicated document sharing guide.

Note that, as part of this architecture revamp, a lot of code that hadn’t previously been deprecated has been removed, so you’re likely to see compilation errors if you’re upgrading from an earlier version and have been using sharing-related APIs.

As a concrete example, if you were using PSPDFDocumentActionExecutor before and you wish to replicate that behavior, you can do so by creating a PSPDFNamedAction and passing it to -executePDFAction:targetRect:pageIndex:animated:actionContainer::

let action = PSPDFNamedAction(namedActionType: .print)
controller.execute(action, targetRect: .zero, pageIndex: controller.pageIndex, animated: true, actionContainer: nil)

PSPDFNamedAction *action = [[PSPDFNamedAction alloc] initWithNamedActionType:PSPDFNamedActionTypePrint];
[controller executePDFAction:action targetRect:CGRectZero pageIndex:controller.pageIndex animated:YES actionContainer:nil];

The table below shows all APIs that were removed (and hadn’t been previously deprecated) as part of this change.

Page Coordinate System Normalization

Each page in a PDF document has its own Cartesian coordinate space, which is used to define the location of the page contents, annotations, and more. Usually, the origin of such a coordinate space is the bottom-left corner of the page. However, pages can be displayed rotated from how the coordinates are stored, and there can also be a crop box set on a page, which cuts down the displayed area. These are achieved by setting the Rotation or CropBox properties on the page dictionary in the PDF. This makes performing these changes very easy: You don’t need to change the content stream or any of the annotations on the page. Unfortunately, this can also be confusing to work with.

Versions before PSPDFKit 8 for iOS used the raw PDF coordinate space in the API, while our newer SDKs — PSPDFKit for Android, Windows, and Web — expose a normalized coordinate system where the origin is always in a consistent corner of the onscreen page. PSPDFKit for iOS has been updated to match this: The origin of each page coordinate space is now always in the bottom-left corner of what you see.

This is a breaking change. The API has been simplified accordingly, so compiler errors should guide you in updating. We anticipate that in most cases, you can simplify your code by deleting any handling of page rotation or offset.

If you need the bounding rectangle of the page, similar to a UIView’s bounds, you may have used PSPDFPageInfo’s rect or rotatedRect before. Instead, create a rectangle with an origin of zero and a size equal to the page info’s size:

let pageRect = CGRect(origin: .zero, size: pageInfo.size)

If you had specific code paths for each rotation value so that something appeared consistent regardless of page rotation, then you can just keep the zero case and delete the other paths:

switch pageInfo.rotation {
case rotation0:
    // This is the only code path that needs keeping.
    ...
case rotation90:
    ...
case rotation180:
    ...
case rotation270:
    ...
}

The normalization applies to PSPDFRenderDrawBlock too. The block signature can’t be changed without causing silent breaking changes. However, the page rectangle parameter now always has an origin of zero. The integer that previously passed the page rotation is no longer used and should be ignored.

The parameters of the coordinate space conversion functions have changed. PSPDFConvertViewPointToPDFPoint, PSPDFConvertPDFPointToViewPoint, PSPDFConvertPDFRectToViewRect, PSPDFConvertViewRectToPDFRect, PSPDFConvertViewLinesToPDFLines, PSPDFConvertViewLineToPDFLines, and PSPDFConvertPDFLinesToViewLines used to require a page rectangle and rotation. These two parameters have been replaced by PSPDFPageInfo. The other values were probably being obtained from a page info instance anyway. The conversion methods on PSPDFPageView are still preferred over these functions.

Render Options

More APIs expecting rendering options use PSPDFRenderOption instead of NSString, which makes expectations clearer. This reduces the need to use rawValue in Swift.

Removal of Deprecated APIs

All previously deprecated APIs have been removed.

PSPDFKitUI

PSPDFKit

Instant