Codiva is open source

Capacitor app scanner with Ionic

At Scanbot, we love developing native apps for Android and iOS, but we also absolutely understand the need for cross-platform and hybrid app approaches. As an SDK provider, we closely monitor developments in this area and are always open to new frameworks, tools and approaches. That is why we also offer our customers corresponding wrappers and plugins for the Scanbot SDK. One of these plugins is the Cordova plugin for the Scanbot SDK.

What is cordova

Cordova is an open source framework for developing hybrid mobile apps. It has a large community and has proven itself in production. However, since development in the app area is very fast, some disadvantages and new challenges have arisen over time, such as:

  • Support for modern programming languages ​​like Swift
  • Management of native project code
  • Support for dependency managers like CocoaPods
  • Progressive web apps
  • etc.

That is why the developers at Ionic decided to build the Capacitor Framework as the successor to Cordova.

And what is capacitor?

Capacitor is a new open source project that is being developed and maintained by the Ionic team and the community behind it. It is a cross-platform runtime and a tool that can be used to develop modern hybrid apps based on HTML, CSS and JavaScript. Capacitor brings a lot of native APIs as well as its own plugin system. And best of all - it offers backward compatibility for Cordova plugins! So you can use Capacitor with most of the existing Cordova plugins.

In this blog article we would like to present and evaluate Capacitor based on a real use case by integrating our Cordova Plugin for Scanbot SDK into a simple Capacitor app. And of course we would also like to show how easy it is to integrate the functions of the Scanbot SDK into a modern mobile hybrid app.

How do you integrate the Cordova plugin into a capacitor app?

Requirements

For Android apps:

For iOS apps:

Please also see the full for further details Requirements for Capacitor.

installation

We would like to create an app based on Capacitor with Ionic.

Install Ionic

Create an empty Ionic app

Upon request:

  • Choose one Ionic 3 App for this tutorial (Ionic 4 Beta should work with a few small adjustments).
  • ⚠️ Please do not add Cordova to the project, as we want to use Capacitor instead!

Install Capacitor

In order to be able to install or add Capacitor to the project, you first have to run npm run build. This prepares the project accordingly (the www folder for web assets is created, etc.):

Then Capacitor is installed in our project:

Initialize the capacitor with the app information

"MyCapacitorApp" is the name of the app and "com.example.mycapacitorapp" is the app ID or bundle ID. You will need this unique ID later to register the app with the Apple AppStore and Google PlayStore. We will also need this ID to request a test license key for the Scanbot SDK.

So add platforms to Android and iOS

When Capacitor has successfully initialized, let's add Android and iOS as platforms:

The blank capacitor project is now ready for use. To run it, it can be opened in the corresponding IDEs (Android Studio or Xcode) with the following commands:

Install Scanbot SDK plugin

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

So we install the cordova-plugin-scanbot-sdk in our project and then have to synchronize it with Capacitor:

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

Integrate Scanbot SDK plugin

Now we are ready to code.

To do this, open the TypeScript file home.ts in the src / pages / home / folder generated by Ionic and import the Scanbot SDK classes:

Then create an instance of the "promisified" version of the Scanbot SDK API:

The ScanbotSDK.promisify () method returns an object that provides all of the Scanbot SDK's API functions. Instead of Success & Error callback parameters, however, these functions return a promise.

Initialize Scanbot SDK

Before it can actually be used, the Scanbot SDK must be initialized. To do this, use the SBSDK.initializeSdk () method:

💡 The full API documentation for the Scanbot SDK can be found here.

License key

⚠️ Please note: Without a license key (licenseKey) the Scanbot SDK will only work for one minute per app session! After this test period, the Scanbot SDK functions as well as the UI components will stop working. The app will also be terminated. Restart the app to get another minute of testing. Or register for a free and non-binding 30-day test license. To do this, fill out this test license form on our website. Enter the unique app ID that we defined above when initializing the capacitor (e.g. com.example.mycapacitorapp).

If you have successfully implemented the initialization of the Scanbot SDK, you can now call the SDK UI components or perform image operations.

Start the document scanner

The Scanbot SDK provides a complete and ready-to-use document scanner UI component for scanning documents.

Use the async API method SBSDK.UI.startDocumentScanner () to start the scanner:

If you make changes to the web code, the web project must be rebuilt with npm run build. Then the transpiled JavaScript code and the web assets must be copied into the native projects of Capacitor via npx cap copy:

Now you can run the app in Android Studio or Xcode and try out the document scanner.

Show image results

The document scanner returns a list of Page objects that contain the scanned document and original images. A document image is the cropped image, while the original image is the unprocessed image. All images are saved as files and represented as file URIs (file: /// ...). Furthermore, a page object offers preview images that can be used, for example, as thumbnails for display.

So we can simply iterate over all Page objects and use the documentPreviewImageFileUri property to display a document image via the element:

The function convertFileUri () is required to convert the file URIs (file: //) into Ionic WebView compatible URLs:

For more details on the Ionic WebView and File URIs, please see the WebView documentation.

Start cutting UI

The Crop UI offers manual crop correction of a document image. It is based on document recognition and contains some smart UI elements, such as magnetic edges. Use the async API method SBSDK.UI.startCroppingScreen () to start the cropping UI and transfer an existing page object:

Where can I find the entire sample project?

The whole sample project can be found on GitHub under scanbot-sdk-example-capacitor-ionic. It shows examples for the integration of all API methods of the Scanbot SDK, such as color filters, PDF creation, OCR and MRZ scanners.

Conclusion

With this tutorial we created a brief introduction to Capacitor by creating a simple app and integrating the Cordova Plugin for Scanbot SDK. The integration of Cordova plugins in Capacitor seems to work very well. We find Capacitor very interesting and believe it will replace Cordova in the long term. Since Capacitor offers its own plug-in system, we will most likely develop and offer a plug-in for it.

The best thing to do is to keep an eye on our GitHub repos and our NPM account to stay up to date.

📌 At the time of this writing, Capacitor is still beta! Please see this one Blog article from Ionic about a preview of Capacitor for the year 2019. If you want to get started with the integration right away, we recommend our Github documentation.