Capacitor tutorial – Integrate the Scanbot SDK with Ionic

Cordova

Cordova is an open source framework for developing hybrid mobile apps. It has a large community and has proven to be successful in production. But since in app development the things are going very fast, some drawbacks and new challenges have emerged over time. Examples include:

• support for modern languages like Swift
• management of native project code and artifacts
• support for dependency managers like CocoaPods
• progressive Web Apps
• etc.

Due to these challenges the guys from Ionic have decided to build Capacitor as a successor to Cordova.

Capacitor

Capacitor is a new open source project, maintained by the Ionic team and its community. It is a cross-platform app runtime and a great tool providing the ability to develop modern hybrid apps with HTML, CSS & JavaScript. Capacitor comes with a number of Native APIs as well as with its own Plugin System. And the best thing is – it has backwards-compatible support for Cordova plugins! So you can use Capacitor with most existing Cordova plugins.

In this blog post we want to introduce and evaluate Capacitor with a real world use-case by integrating our Cordova Plugin for Scanbot SDK in a simple Capacitor app. And, of course, we also would like to show how easy it is to integrate the features of the Scanbot SDK into a modern hybrid mobile app.

Getting Started

Requirements

• Node v8.6.0 or higher, with NPM v5.6.0 or higher

For android apps:

• Latest Android Studio with Android SDK installed

For iOS apps:

• Mac with latest version of Xcode
• CocoaPods

For more details please see the full requirements for Capacitor.

Installation

We are going to use Capacitor with an Ionic App.

Install Ionic

npm install -g ionic

Create an empty Ionic app

ionic start myApp blank

If prompted…

• Choose to create an Ionic 3 app for this tutorial (Ionic 4 Beta might also work with some small modification).
• ⚠️ Don’t add Cordova to your project since we are going to use Capacitor!

Install Capacitor

In order to install and add Capacitor into your project, you must run npm run build at least once to prepare your project (create the www folder for web assets):

cd myApp/
npm run build

Add and install Capacitor into your project:

npm install --save @capacitor/cli @capacitor/core

Initialize Capacitor with your app information

npx cap init MyCapacitorApp com.example.mycapacitorapp

“MyCapacitorApp” is the name of your app.

“com.example.mycapacitorapp” is an identifier (app ID / bundle ID) of your app. You will need to use this unique ID to register your app on Apple AppStore and Google PlayStore. Furthermore we will use this ID later to generate a trial license key for the Scanbot SDK.

Add android and iOS as platforms

Once Capacitor is initialized, we add the Android and iOS as platforms:

npx cap add android
npx cap add ios

Your blank Capacitor app project is now ready to go. Just open it by following commands in corresponding IDE (Android Studio or Xcode) and try to run it:

npx cap open android
npx cap open ios

As already mentioned, Capacitor supports Cordova plugins. You can simply install a plugin by npm install ….

So we are going to install the cordova-plugin-scanbot-sdk to our project and synchronize it with Capacitor:

npm install cordova-plugin-scanbot-sdk
npx cap sync

Please note that npx cap sync is required to update the dependencies and copy the web assets to native projects (android and ios).

Integrate the Scanbot SDK plugin

Now we are ready to start coding.

Navigate to the Ionic generated folder src/pages/home/ and edit the home.ts TypeScript file.

Import Scanbot SDK classes:

import ScanbotSDK from 'cordova-plugin-scanbot-sdk';

Get an instance of the “promisified” version of the Scanbot SDK API:

Get an instance of the “promisified” version of the Scanbot SDK API:

The ScanbotSDK.promisify() method returns an object that has all the functions of ScanbotSDK but with a promisified signature, that is, where every method returns a promise, instead of taking success/error callbacks as parameters.

Initialize the Scanbot SDK

The Scanbot SDK must be initialized before usage. Use the SBSDK.initializeSdk() method for that:

constructor(public navCtrl: NavController, platform: Platform) {
  platform.ready().then(() => this.initScanbotSDK());
}

private async initScanbotSDK() {
  await this.SBSDK.initializeSdk({
    loggingEnabled: true,
    licenseKey: '', // see the license key notes!
    storageImageFormat: 'JPG',
    storageImageQuality: 80
  }).then((result) => {
    console.log(result);
  }).catch((err) => {
    console.error(err);
  });
}

For the full API reference of the Scanbot SDK Plugin please see the docs.

License key

⚠️ Please note: The Scanbot SDK will run without a licenseKey for one minute per session! After the trial period is over all Scanbot SDK functions as well as the UI components will stop working or may be terminated.

You can get an unrestricted, no-strings-attached 7-day trial license for free. Please submit the Trial License Form on our website by using the app identifier (app ID / bundle ID) you have specified on initialization of Capacitor above (e.g. com.example.mycapacitorapp).

Once you have successfully implemented the initialization of Scanbot SDK, you are ready to call the UI components or perform some image operations.

Starting the document scanner

The Scanbot SDK provides a ready-to-use Document Scanner UI for guided, automatic document scanning. Use the async API method SBSDK.UI.startDocumentScanner() to launch it:

async startDocumentScanner() {
  const result = await this.SBSDK.UI.startDocumentScanner({
    uiConfigs: {
      // Customize colors, text resources, behavior, etc..
      cameraPreviewMode: 'FIT_IN',
      orientationLockMode: 'PORTRAIT',
      pageCounterButtonTitle: '%d Page(s)',
      multiPageEnabled: true
      // ...
    }
  });

  if (result.status === 'CANCELED') {
    // user has canceled the scanning operation
    return;
  }

  // Get the scanned pages from result:
  this.pages = result.pages;
}

<button ion-button block (click)="startDocumentScanner()">
    Open Document Scanner
</button>

When making changes to the web code in a Capacitor project, you have to rebuild the web project by npm run build and then update the Capacitor native projects with the transpiled JS code and web assets by npx cap copy:

npm run build
npx cap copy

After that run the app in Android Studio or Xcode and try the Document Scanner.

Show image results

The Document Scanner returns an array of Page objects which contain the scanned document and original images. A document image is the cropped and perspective corrected image, while the original image is the unprocessed image. All images are stored as files and represented as file URIs (file:///…). Furthermore a Page object provides preview images which can bed used as thumbnails for displaying.

<ion-grid>
  <ion-row>
    <ion-col padding col-4 *ngFor='let page of pages'>
      <img [src]='convertFileUri(page.documentPreviewImageFileUri)'/>
    </ion-col>
  </ion-row>
</ion-grid>

The function convertFileUri() is required to convert a file URI (file://) to an Ionic WebView compatible URL.

convertFileUri(fileUri) {
  return (<any>window).Ionic.WebView.convertFileSrc(fileUri);
}

Please visit the WebView docs for more details about Ionic WebView and how to handle file URIs.

Start cropping UI

You can use the Cropping UI for manual cropping correction of an image. It is based on document detection and contains some smart UI elements like magnetic lines and a magnifier. Use the async API method SBSDK.UI.startCroppingScreen() and pass an existing Page object to launch the Cropping UI:

async startCroppingScreen(page: Page) {
  const result = await this.SBSDK.UI.startCroppingScreen({
    page: page,
    uiConfigs: {
      // Customize colors, text resources, behavior, etc..
      doneButtonTitle: 'Save'
      // ...
    }
  });

  if (result.status == 'CANCELED') { return; }

  // handle the updated page object:
  this.updatePage(result.page);
}

Conclusion

In this tutorial we have done a short introduction of Capacitor by creating a simple app and adding the Cordova Plugin for Scanbot SDK. The integration of Cordova Plugins in Capacitor seems to work very well. We find Capacitor quite interesting and believe it will replace Cordova in the long term.

Since Capacitor provides its own Plugin System, we will most likely build and offer a plugin for it as well. So keep an eye on our GitHub repos and our NPM account to stay up to date.