Integrating the native Anyline MRZ scanner into a SAP Fiori App
I am an experienced SAP Mobile Consultant / Architect doing a lot of Fiori projects in the recent year(s). One question that I am confronted with very often is about how to use Fiori Apps on mobile devices (e.g. Smartphones and Tablet) and how to use native device capabilities within a Fiori App.
In this blog I am showing how easy it is to integrate native device capabilities. I had the requirement from a client to integrate OCR capabilites into a Fiori App for a PoC. The primary goal of the project was to eliminate the errorprone manual data capturing process and replace it with automated OCR processing. iOS doesn’t provide the required OCR capabilities out of the box. Therefore we used Anyline for the OCR part.
Anyline is an Austrian Startup that provides an groundbreaking OCR SDK for Mobile Devices offering Meter Reading for Utilities, License Plate Reading, Passport MRZ reading…
Integrating the native device capabilities into an SAP Fiori App is possible via Apache Cordova / SAP Kapsel. The tools required for covering the whole lifecycle are
- WebIDE
- Kapsel SDK (SAP Mobile Platform SDK, latest version)
- Hybrid Application Toolkit (HAT)
- XCode
- Anyline SDK
The toughest part was getting the HAT running on my Mac. It took me several hours searching xStackoverflow to fix all issues.
Download the Anyline SDK Cordova Plugin
The Anyline SDK Cordova Plugin is hosted on github and can be downloaded via https://github.com/Anyline/anyline-ocr-cordova-module/releases/tag/v3.15.0
Download the SDK, extract the ZIP File and copy it into the plugins directory of your local HAT installation.
The Anyline SDK requires a license key to work. We will generate the license key later in this blog.
Configure WebIDE
First of all we have to configure the WebIDE to support the HAT. This is done in the Plugins Section of the WebIDE.
Create a new Application in the WebIDE
Use the SAPUI5 Application Template for creating a new Application. Please do not use the Mobile Templates as they are deprecated. Depending on the project name you selected, the project structure should look like
Hybrid App Configuration
The next step is to configure the Hybrid Application in the WebIDE. Therefore open the project settings from the context menu of your project and navigate to the Hybrid App Toolkit section.
Enter the following details:
- App Name
- AppID (will be needed for Anyline Registration)
- Description
- Version
Select the target Platform iOS and add the required plugins. In the Plugins section select Custom and Local Repository and select the AnylineSDK plugin. Please verify that the HAT is running berfore performing this step. The Anyline Plugin can only be loaded from the local repository if the HAT is running.
Get an Anyline License Key
To get a license key for a trial you have to register at https://www.anyline.io/sdk-register/
According to the Anyline Terms and Conditions you can get a Trial License Key.
You have to provide the AppID you used in the WebIDE Hybrid App Configuration.
Copy the License into your WebIDE project
There are two options – either you save the license key in a separate file or you copy it into the controller. I’ve choosen the second option. The following code snippet shows how the configuration was added to the controller.
return Controller.extend("com.sap.mobileMobileDemo.controller.Main", { config: [ "your license key", { "captureResolution": "1080p", "cutout": { "style": "rect", "maxWidthPercent": "90%", "maxHeightPercent": "90%", "alignment": "top_half", "strokeWidth": 2, "cornerRadius": 4, "strokeColor": "FFFFFF", "outerColor": "000000", "outerAlpha": 0.3 }, "flash": { "mode": "manual", "alignment": "bottom_right" }, "beepOnResult": true, "vibrateOnResult": true, "blinkAnimationOnResult": true, "cancelOnResult": true } ],
Working with the EventBus
As we are working with a Cordova Plugin, the callbacks have to be implemented asynchronously. In order deal with the callbacks and not breaking the MVC concept, I’ve decided to facilitate the EventBus for communication inside the controller. The EventBus is initialized in the onInit lifecycle method.
onInit: function() { var oEventBus = sap.ui.getCore().getEventBus(); oEventBus.subscribe("MyChannel", "showData", this.showData, this); },
Calling the Anyline Plugin
I was really surprised how easy it was to integrate the Anyline Plugin. In the eventhandler method of the scan button the cordova.exec must be called. The plugin requires the following parameters:
- onResult: the callback for a successful scan
- onError: the callback for an error situation or if the scanning was cancelled by the user
- AnylineSDK: ensures that the anyline-sdk is called
- scanMode: “MRZ“, “BARCODE“, “ANYLINE_OCR“, “ELECTRIC_METER“, “GAS_METER“
- configuration: containing the license key and the plugin configuration
scan: function() { cordova.exec( this.onResult, this.onError, "AnylineSDK", "MRZ", this.config); },
The counterpart in the XML View looks the following:
Implementing the callback
The Anyline Plugin returns a json that can be used straightforward to instantiate a JSON Model. As I am dealing with asynchronous JavaScript, I have no direct access to the controller instance. I am publishing the showData EventBus. The listener is called on the UI thread and sets the response as model for the view.
onResult: function(oResult) { var oEventBus = sap.ui.getCore().getEventBus(); oEventBus.publish("MyChannel", "showData", oResult); }, showData: function(oChannel, oEventId, oParameters) { var oView = this.getView(); var oModel = new JSONModel(); var oData = oParameters; oModel.setData(oData); oView.setModel(oModel); }
Generating the iOS App
The final step is the generation of the Hybrid Application project. This requires a running HAT on the local Mac and an XCode installation. The prerequisites are checked during the HAT installation. The generation is triggered via the context menu of the project.
The WebIDE console can be used to monitor the progress of the build.
Build the Application in XCode
The final step is the XCode Build. The project is located in the hybrid –> platforms –> ios folder.
Open the project, and select your Team and trigger the build.
Test the App on the iPhone
To open the OCR Pluigin click the Scan Document button.
Place the document in the highlighted area
The extracted data is shown on the UI
I hope you enjoyed my first blog. If you have any questions please feel free to contact me!
New NetWeaver Information at SAP.com
Very Helpfull