Creating a Native Plugin for PSPDFKit

The following is a guest blog post from Stefan Kieleithner, a developer at PSPDFKit. PSPDFKit is a tool for working with documents in your app. Head over to PSPDFKit.com to learn more about all their products.

Third-party plugins are a vital part of the Ionic platform, helping developers to easily enhance their apps with new functionality. In this post, we would like to show you how PSPDFKit created a plugin using their native platform’s SDKs to bring PDF functionality to Ionic apps.

Creating a Third-Party Plugin: From Cordova to Capacitor

Creating a third party plugin for Ionic is quite straightforward. The first step would be to decide what technology to use for creating a new plugin. With Capacitor being at the forefront and becoming more and more popular, the decision is easy nowadays.

When we created our plugin, Capacitor was not yet available, so we opted for creating a Cordova plugin at the time. Since Capacitor is backwards compatible with most existing Cordova plugins, integrating our plugin nowadays with Capacitor works as well without any issues.

Ideally, plugins should be small, and focus on a single task that helps developers achieve a specific task in their apps. That’s why having multiple smaller plugins is preferred and useful for the community, as the added functionality is better suited for a single feature. For PSPDFKit, this task is viewing and annotating PDFs, enabling users to work with documents easily, and providing developers with a very straightforward and uncomplicated integration of PDF features in their apps.

How to Approach Creating a Plugin

The most important questions are how you want the plugin to look and what features and API should be exposed?

We used our existing iOS and Android SDKs to provide a unified plugin with a similar JavaScript API that can be used on both platforms.

We started implementing the plugin by following the Plugin Development Guide.

Since we already have native SDKs available, we actually use those under the hood of the plugin to offer a native platform experience, running with our optimized PDF rendering and annotation engine.

For iOS, this meant creating a new CDVPlugin, that handles all functionality of the plugin. The iOS part of the plugin is created using Objective-C, so the starting point would look something like this:

#import <Foundation/Foundation.h>
#import <Cordova/CDV.h>

@interface PSPDFKitPlugin : CDVPlugin
@end

In the implementation of this custom plugin class, all the code and the wrapping methods for the plugin are located here.

The logic for wrapping a function call from JavaScript to Objective-C allowing custom parameters could look like this:

- (void)present:(CDVInvokedUrlCommand *)command {
    NSString *path = [command argumentAtIndex:0];
    NSDictionary *options = [command argumentAtIndex:1];

    [self configurePDFViewControllerWithPath:path options:options];

    // Present the PDF View controller.
    [self.viewController presentViewController:pdfController animated:YES completion:^{
        [self.commandDelegate sendPluginResult:[CDVPluginResult resultWithStatus:CDVCommandStatus_OK] callbackId:command.callbackId];
    }];
}

The approach for Android is similar.

If you would rather use Capacitor instead of Cordova, creating a Capacitor plugin from scratch can be done as explained in the Creating Capacitor Plugins guide.

Cross Platform Approach

We, at PSPDFKit, offer our native SDK on various platforms, with an API that feels at home on every single system. That sometimes means that the API needs to be structured differently across platforms. This turned out to be a challenge that needed more thought once we started developing the plugin.

In the beginning, we offered a separate plugin for each platform. However, this turned out to be not optimal for Ionic developers creating apps for both iOS and Android, as it works against its premise of being a cross-platform technology, and adds a maintenance cost. So we made a push and made it a goal to unify the plugins, and only offer a single Cordova plugin that works across both platforms.

Therefore, since we wanted to offer a single combined plugin that covers both iOS and Android, we had to make sure that the API we exposed worked the same on both platforms with minimal exceptions, to accommodate for platform and feature differences. It was important for the API to be as similar as possible, so users of the plugin wouldn’t have to conditionalize logic depending on the platform.

For example, to present a PDF, we adhere to platform conventions on iOS and Android in the UI, but we expose a unified JavaScript API in the plugin that handles presentation of a PDF using ways that are native on each platform.

Using our native iOS SDK, the code would look like this:

let document = Document(url: url)
let pdfController = PDFViewController(document: document)
present(UINavigationController(rootViewController: pdfController), animated: true)

On Android the logic would look like this:

val config = PdfActivityConfiguration.Builder(context).build()
PdfActivity.showDocument(this, uri, config)

And the unified API in our plugin that handles presentation on each platform simultaneously is this:

PSPDFKit.present(path, options, success, failure);

Using the Plugin in an App

When using the PSPDFKit plugin in your app, here are some of the most useful features that can be done programmatically via the JavaScript API.

To simply present a document, you can call the present function:

const documentPath = cordova.file.applicationDirectory + "www/Document.pdf"
PSPDFKit.present(documentPath);

The plugin also supports additional customization options, like changing the page transition mode and changing the background color:

PSPDFKit.present(documentPath, {
    pageTransition: 'scrollContinuous',
    backgroundColor: 'black',
});

It’s also possible to programmatically switch pages by setting a specific page index:

PSPDFKit.setPage(3, true);

Capacitor Compatibility

Even though the PSPDFKit plugin was originally made for Cordova, it is also fully compatible with Ionic and Capacitor. Since Capacitor is backwards compatible and supports most Cordova plugins, we verified that our plugin can be integrated in Capacitor apps without any issues. Capacitor is very good at supporting existing plugins, and they should run fine in most cases.

To install a Cordova plugin in a Capacitor app, have a look at the dedicated documentation explaining this. Plugins can be installed like any other package.

For PSPDFKit, the main install steps would look like this:

npm install https://github.com/PSPDFKit/PSPDFKit-Cordova.git

For further steps and troubleshooting, please have a look at the installation instructions of the PSPDFKit Cordova plugin.

What is PSPDFKit?

PSPDFKit for iOS and Android, which runs under the hood of the Cordova plugin, is a feature-rich SDK for viewing, annotating, editing, and creating PDFs. It offers developers powerful APIs for quickly adding PDF functionality to any application. It contains a beautiful UI, which is simple and easy to use, and is highly customizable; a highly accurate and reliable PDF rendering engine; support for viewing, annotating, editing, signing, filling forms, and more PDF related features.

PSPDFKit offers a variety of products for working with documents. The native iOS and Android SDKs that are used to provide the Ionic plugin are only a subset of the solutions that PSPDFKit offers.

Head over to PSPDFKit.com to learn more about all our products.