Capacitor tutorial – Integrate the Scanbot SDK with Ionic

January 14, 2021

We at Scanbot love native app development for Android and iOS. But we also understand the need for other cross-platform and hybrid app approaches. As an SDK provider, we are constantly following the latest developments in this area and are always open to new frameworks, tools, and approaches. That’s why we also offer corresponding wrappers and plugins for the Scanbot SDK to our customers. One of those plugins is the Cordova Plugin for the Scanbot SDK.

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

Install the Scanbot SDK plugin

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:

private SBSDK = ScanbotSDK.promisify();

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” 30 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.

So we can just iterate over all pages and use the documentPreviewImageFileUri property to display an image with an <img> element:

<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);
}

Full example project

The complete example project can be found on GitHub: scanbot–sdk-example-capacitor-ionic. It shows the integration of other API methods of the Scanbot SDK, such as Image Filters, PDF Rendering, and OCR and MRZ Scanners.

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.

At the time of writing this article, Capacitor is still a Beta version! Please read this blog post of Ionic for a preview of Capacitor in 2019. In case you are interested in the integration with Flutter or React Native, please check out our other blog posts.