Technical Articles
Adding third party or custom Cordova plugins to a hybrid app in SAP Web IDE
Updated 2 April 2020: added limitations.
In this blog I want to showcase a feature we’ve recently added to our Cloud Build Service: the capability to add custom or third-party Cordova plugins, instead of the publicly available plugins available in the npm repository.
When we phased out the HAT Local Add-on component from Hybrid Application Toolkit, we actually created a feature gap as custom plugins were supported only via a local build through HAT Local Add-on. When developing Cordova apps that include custom plugins, it actually makes more sense to develop the app completely in a local development environment. However, we were contacted by several customers who wanted to use custom or more importantly third-party plugins in our Cloud Build so they could develop their apps in a cloud environment. These third-party plugins are not distributed through a public repository. We’ve listened to this feedback and added this capability.
Before explaining how you can add custom plugins to your hybrid projects in SAP Web IDE, I have one important recommendation to share:
When you start developing a new mobile app, we strongly recommend that you consider developing this with either MDK (Mobile Development Kit) for cross platform applications, or our native SDKs (SAP Cloud Platform SDK for iOS or SAP Cloud Platform SDK for Android).
Adding a custom barcode scanner plugin to a Packaged app
In this section I am going to add a custom barcode scanner plugin to a Packaged Fiori app. This type of app has all web assets required for the container app packaged inside the app.
For this case, we will create a new project in SAP Web IDE based on the Fiori Master-Detail template. From the menu, please select File > New > Project from template. For the Neo environment, please select the SAP Fiori Master-Detail Application template, follow the wizard steps and make sure that for the Application Scenario you select the Standalone App type in the Template Customization step.
Once the project is created in your workspace, right-click and select Mobile > Enable as Hybrid Mobile Project. This will add the required code and configuration for building a Cordova app. This will also include a default set of Cordova plugins.
Before we add our custom plugin, you need to realise that the barcode scanner plugin is a special case. By default, we add the SAP Kapsel Barcode scanner plugin in Packaged Apps, which is SAP’s customised version of the plugin. To avoid conflicts between the plugins, we need to remove this from the list of plugins being included in the app. The main reason for picking this scenario is that we have customer case where they would like to use a third-party barcode scanner plugin.
Right-click on the project and in the context menu, select Mobile > Select Cordova Plugins > Kapsel. Find the kapsel-plugin-barcodescanner and unselect it. Save your changes.
Our Cloud Build Service will pick up custom plugins from a folder called plugins in the mobile folder of your project. Create a new folder called ‘plugins’ in the folder <projectname>/mobile.
We are going to add a customised version of the phonegap barcodescanner plugin. Open the github page for this plugin at https://github.com/phonegap/phonegap-plugin-barcodescanner and download the zip file of this plugin to your machine. You can also clone the git repo, but then you will have bit more work to create the zip file. Using a zip file makes it easy to import a large amount of files into your SAP Web IDE project.
Going back to the project in SAP Web IDE, right-click on the folder ‘plugins’ and select Import > File or Project. Browse to select the file you’ve downloaded.
It is important that the name of the plugin folder is exactly the same as the cordova id of the plugin specified in the plugin’s package.json. Our Cloud Build Service will determine which cordova plugin to add based on the name of the folder. If the name doesn’t match the Cordova id, the plugin will not be loaded.
In this case, the cordova id is phonegap-plugin-barcodescanner.
Rename the plugin folder to this (basically, you just remove the “-master” in case you selected a drop from the master branch).
Now, for the sake of this demonstration / blog, we are going to change the colours used in the barcode scanning interface for iOS. By default, you will see a slightly transparent green box and red horizontal line while scanning a barcode. We’ll change the colours to a yellow box with a blue horizontal line. You could potentially change the scanner UI drastically, but that is up to you.
For Android, you can modify something else (e.g. change success beep).
Open the file plugins/phonegap-plugins-barcodescanner/CDVBarcodeScanner.mm and search for ‘blue’. Modify the two lines where this is found and save your changes.
We will now add some code to the Fiori app to add a button that triggers the barcode scanner plugin.
To add a button in the header toolbar, go ahead and open the file <project>/webapp/view/Master.view.xml and add the following line after the searchfield:
<Button id="barcodeButton" icon="sap-icon://bar-code" tooltip="Barcode Scanner" press="onBarcodeScan"></Button>
This button will call the function onBarcodeScan when pressed. Let’s add this function in the master controller. Open the file <project>/webapp/controller/Master.controller.js and add the following code after the onInit function:
onBarcodeScan: function () {
var that = this;
try {
cordova.plugins.barcodeScanner.scan(
function (result) {
that.getView().byId("searchField").setValue(result.text);
var sQuery = result.text;
if (sQuery) {
that._oListFilterState.aSearch = [new Filter("BusinessPartnerID", FilterOperator.Contains, sQuery)];
} else {
that._oListFilterState.aSearch = [];
}
that._applyFilterSearch();
},
function (error) {
sap.m.MessageBox.show("Barcode scanning failed: ", error);
}
);
} catch (e) {
sap.m.MessageToast.show("Cordova plugin is not available.");
}
},
Since this piece of code is using sap.m.MessageBox, please add this to the dependencies listed at the start of Master.controller.js.
In the same file, please find the code !Device.system.phone and replace it with !sap.ui.Device.system.phone
Disclaimer: The above is a very simple and minimalistic implementation to showcase the use of a custom plugin. It is by no means a good example or best practice of how to add a barcode scanner to your Fiori app.
Now that we are done adapting the project, let’s go ahead and build the app in the cloud.
In the project context menu, select Mobile > Build Packaged App and go through the wizard steps. For most of the options you can simply leave the default settings. It is required to select a signing profile in the build settings.
When the build is done, you can use the hyperlink to download the app, or use the QR code to install the app over-the-air onto your device.
After starting the app, authenticating and setting up the passcode, you will be able to see the customized barcode scanner.
Adding a custom barcode scanner plugin to a custom Fiori Client app
Besides the Packaged app type, we also offer a container app that loads the required web assets from an online source and caches this. You can build this type of app in SAP Web IDE Full-Stack as well, as I’ve mentioned in this blog.
Before we create the client, lets first publish the sample application created above as a web application onto SAP Cloud Platform. From the project context menu, select Deploy > Deploy to SAP Cloud Platform and click Deploy. The web application is now hosted on SAP Cloud Platform.
Once deployed, we can open its url.
Now that the web application is deployed, we will create the custom Fiori Client.
In the workspace context menu, select New > Project for Template. For the Category, select Custom Fiori Client App. Select the template and click Next. Provide a name for this project and click Next.
Provide an App ID (e.g. com.company.customfioriclient) and click Next. Take note that in case the App ID is already defined in SAP Mobile Services, you will be required to change the App ID to a unique id.
For this demo, I will not select a Fiori Launchpad as Fiori Source. Instead, I will provide a Fiori Application URL, which is the URL of the application we’ve deployed to SAP Cloud Platform earlier.
The CustomFioriClient project is now created in your workspace.
By default, a set of Cordova and Kapsel SDK plugins are added in this project. Since we are going to add our custom barcode scanning plugin, we need to deselect the Kapsel Plugin Barcodescanner.
Similar as for the Packaged App, in the project’s context menu, select Mobile > Select Cordova Plugins > Kapsel and deselect the kapsel-plugin-barcodescanner and save the configuration.
Next, we’ll add the custom plugin. Select the plugins folder in the CustomBarcode project (the Packaged app / web app project created earlier) and select Edit > Copy in the context menu.
Go back to your CustomFioriClient project, select the www folder and Edit > Paste the plugins folder here.
We are now ready to build the Custom Fiori Client. Go to Mobile > Build Custom Fiori Client App.
You can change the app’s name, icon and splash screen to your needs and select a code signing profile. We’ll skip the Push Notification configuration for this case. Click Build and our Cloud Build Service will start building the app.
When the build is done, you can use the hyperlink to download the app, or use the QR code to install the app over-the-air onto your device.
After starting the app, setting up the passcode and authenticating, you will be able to see the customized barcode scanner. The first time you load your app, it will take a while to load. The client caches your app’s web assets, so the next time you open the app it will load significantly faster as most web assets have been cached. I could show the screenshot of the app below, but they look exactly the same as the screenshots shown for the Packaged App.
Limitations
There are limits to what our Cloud Build Service can do for you. Most developer won’t run into these, but you should be aware of the following:
- Custom plugins are supposed for builds using Mobile Services only (not Fiori Mobile)
- Custom plugins written in Swift are not supported
- Any plugin requiring any additional npm or cocoa dependencies is not supported
- The allowed maximum size of the source bundle (the project’s content) including plugins is 300MB.
If this feature/blog is useful for you, please leave a like.
Ludo Noens – SAP Digital Workplace
Hello,
Thanks for this blog.
I would like to add bluebird plugin to the fiori client : https://github.com/BlueFletch/cordova-bluebird-api
I imported zip file to plugins folder but it doesn't work. I noticed that there is no package.json file in the imported folder.
Could you tell me what could be wrong ?
Thank you,
Louis-Arnaud
Hello Louis-Arnaud,
This plugin hasn't been updated for 6 years. Are you able to use it in a locally created Cordova project ?
Thanks,
Ludo
Hi Ludo Noens,
Does SAP have any plans to automate this? Such as within the option in WebIDE where you can add a public Codova plugin to the project – have another option there to upload a zip file containing the custom plugin (like was available in Fiori Mobile in the past)?
That would make it nicer than manually creating the folders and files in the WebIDE project.
And do you have any plans to allow 3rd party or custom plugins to be added directly in the Mobile Services cockpit when doing a Cloud Build from there? This way we could avoid using WebIDE altogether when building simple custom Fiori Clients.
Regards,
Brendan
Hi Brendan,
The basic functionality for creating a folder and uploading a zip file is already available in SAP Web IDE. This allows you to get the same results. I don't see much added value in automating this further. One just need to know the steps.
We have purposely separated the development use case from the 'admin' use case and decided that developers should use SAP Web IDE to build custom Fiori Client apps. From the Mobile Services cockpit you can still build simple custom Fiori Client apps. However, this doesn't cover the inclusion of custom plugins. For this use case we expect you to make use of SAP Web IDE.
Regards,
Ludo
Hi Ludo,
thanks for your always great and valuable posts!
I hava a question regarding plugins. What is the requirement that plugins show up in the WebIDE. In specific i would like to add https://www.npmjs.com/package/cordova-plugin-androidx-adapter
Is there any details that you can share on the exact requirements for 3rd party plugins ?
Thanks!
Best regards,
Martin
Hi Martin,
Pardon the late response, I am way less focussed on this product nowadays...
We pull this list from the public npm repository and apply some filter on it. If you are looking for a specific plugin that is not showing up, please let us know.
Thanks,
Ludo
Hi Ludo,
How to use Instabug Plugin in Sap hybrid app.Please help me.
Thank and Regards,
Manojkumar
This plugin requires changes in source files that are not exposed in SAP Web IDE.
I recommend downloading the Android Studio and/or Xcode projects generated by our Cloud Build Service and modify the source files as required by the plugin, followed by a local build on your workstation.
Thanks,
Ludo
Thanks Ludo!!
Sap Hybrid application firebase cordova plugin is availble.I am using that plugin and I am getting the build failed.How to resolve firebase plugin issue.
S Manojkumar