Technical Articles
Streamline Hybrid Application development using Web IDE and the Hybrid App Toolkit Add-on
Introducing the SAP Web IDE Hybrid App Toolkit Add-on
In my last post, I wrote about our plans to implement hybrid development capabilities in the Web IDE. I hinted at some capabilities that were coming that allow Web IDE to interact with a local Cordova development environment. Well, the tools have been released, so it’s time to tell you about them.
What we have released is the SAP Web IDE Hybrid App Toolkit Add-on; the toolkit only works today with Web IDE running on the Trial Edition of the HANA Cloud Platform. The software is available for download from SCN (https://store.sap.com/sap/cp/ui/resources/store/html/SolutionDetails.html?pid=0000013586) and documentation for HAT is available as well at https://scn.sap.com/docs/DOC-60529. This is an early preview of the software, that’s why it’s running in the trial environment, and it cannot be used in production environments (for now).
The Hybrid App Toolkit (HAT) consists of three components:
- Web IDE plugin
- Hybrid App Toolkit Connector
- Web IDE Companion Application
The toolkit supports hybrid application development for Android and iOS, support for Microsoft Windows is on the roadmap for a potential future release.
The remaining sections of this post will describe each of the components and how they work.
Web IDE Plugin
The Web IDE Plugin adds mobile hybrid application awareness to Web IDE; capabilities that allow a developer to set mobile properties within an application. With those properties are settings that define the target mobile device platforms for the application as well as the Cordova or SMP Hybrid SDK (Kapsel) plugins that are used by the application. Developers use Web IDE to add Cordova plugins to the project then code the application’s interaction with those plugins adding code as needed to deliver whatever capabilities are required by the application. The plugin also provides code completion for the hybrid plugin APIs and a catalog of code snippets a developer can use to quickly inject plugin code into the application.
When it comes time to test the web application, Web IDE provides several options. Web IDE already has live preview capabilities, the Web IDE plugin will add capabilities that allow Web IDE live preview to simulate the native capabilities exposed by the plugins (and code) added to the project (through mock data or perhaps someday some alternate mechanism).
A Web IDE developer may also want to test the application on a physical device or on a device emulator or simulator (Google provides Android emulators and Apple iOS simulators; yes, there is a difference). Web IDE can display a QR code a developer can use to launch the web application in a mobile device browser – simply point the device camera at the QR code and use a code scanning application to load the application URL wrapped in the QR code. To test the web application on a device emulator or simulator, a developer can simply copy the web application URL and paste it into the browser on the simulated device or into the SAP Fiori Client’s configuration and test away.
Hybrid App Toolkit Connector
If the web application is a hybrid application and makes use of native APIs, then testing the web application in the browser may not be enough. The application may utilize mobile device-specific hardware (such as the camera, accelerometer or compass) or make use of a mobile-specific native API (such as the Contacts application or network information APIs) that are not available in the browser or inside Web IDE’s Preview mode. The Web IDE may be adding capabilities in the future that can make some of this testing easier, but for right now for some things you just need a mobile device.
To accommodate this, the Hybrid App Toolkit provides the Connector (In the initial release, this component is called Communicator, this name will change to Connector in the January update of the toolkit so I’m going to use the new name here), a locally installed module that allows Web IDE to communicate with a local Cordova development environment. A developer installs and configures a local Apache Cordova development environment (installing Git, node.js then platform-specific tools such as Java, Ant (or Gradle) & ADT for Android or Xcode and some Xcode command-line tools for iOS development) before installing HAT.
With that in place, the developer simply right-clicks on a project in Web IDE and selects Deploy –> Deploy to local Hybrid Toolkit. Web IDE opens a connection to the Connector and passes it the Web IDE project configuration file and associated content. The Connector parses the project’s configuration file then uses the local Cordova development environment to create a new project, adds the selected mobile device platforms and Cordova or Hybrid SDK plugins then copies the web application content into the new Cordova project.
Developers can also select Run on –> Android Emulator/Device or Run on –> iOS Simulator/Device. With this option, the Connector will initiate the Cordova build process for the selected platform and launch the compiled application on a connected device or the appropriate device emulator or simulator.
The Connector is written in JavaScript and executed using Node.js, just like the Cordova command-line tools, so what we’ve implemented fits cleanly within the Cordova development approach.
Two of the drawbacks of the current implementation of this is that the Connector creates the full Cordova project every time, so there’s no incremental update nor is there any way to upload any changes you’ve made to the local project back to the Web IDE. My expectation is that we’ll fix these two limitations in a future release.
Hybrid App Toolkit Companion App
If you think about the process I just described, you may have noticed that there’s a lot going on there and it will take a while to create, build and deploy the native project to the device or simulator. You’re right and we don’t expect developers to use this approach for the majority of their testing. The deploy to device option is for final testing, once you’ve worked through all of the kinks in your application and are ready to deploy the application to alpha or beta testers. For iterative testing, we have another approach you can use.
Included with HAT is a native application project we’re calling the Hybrid App Toolkit Companion App. The Companion App is a native application developers can use to streamline testing of hybrid applications created using Web IDE on a mobile device. Instead of packaging the web application content into a Cordova application as described in the previous paragraphs, the Companion App allows a developer to make changes in Web IDE and see those changes reflected immediately in the Companion App. The source code for the Companion App is included with HAT and eventually we hope to have a version of the application available in the public app stores.
Let me explain how it works.
A developer working in Web IDE creates an application and publishes it on the Hana Cloud Platform. Then, within the Web IDE, the developer can initiate a live preview through the Companion App. Web IDE will push the web application URL through the Connector to the Companion app. With the URL in place, the application can be instantly viewed within the Companion App and refreshed whenever the content on the server is changed.
We hope to simplify this process in a future release by enhancing the Companion app with the Kapsel Barcode Scannerplugin. With this in place, a developer will be able to populate the web application URL in the Companion App using the QR code capabilities already included in Web IDE.
The Companion App contains all of the Cordova core and Hybrid SDK (Kapsel) plugins, so any code within the web application that utilizes the plugin APIs will work within the Companion App.
This approach dramatically reduces the cycle time when iteratively coding and testing changes to a hybrid application, especially when native plugins are involved. The Companion App is similar to the PhoneGap Developer App or the AppGyver Scanner application, but has direct integration with Web IDE and supports the SMP Hybrid SDK (Kapsel) plugins as well.
Wrap-Up
As you can see, the Web IDE team has been busy and taking a serious look at the hybrid developer use cases. The toolkit is free, available to anyone with a Web IDE license. What’s available today is a trial version of the toolkit; we will continue work on solidifying the toolkit’s capabilities and make it available for productive use soon.
Note that these tools are for Apache Cordova development scenarios. It’s easy to think that this toolkit was created specifically for SMP Hybrid SDK (Kapsel) developer, but that is not the case. The Hybrid SDK (Kapsel) is a set of plugins for Apache Cordova, but there are many Web IDE developers that won’t be using the Hybrid SDK. That’s why HAT supports Cordova developers as well as SMP Hybrid SDK developers.
As we continue to enhance the toolkit, I’ll post updates here. Stay tuned!
In my next post, I’ll show you how to install and use the Hybrid App Toolkit; hopefully before the end of the year.
Dear John,
today I've stumbled upon the SAP Web IDE Hybrid App Toolkit Add-on and was able to run the Hybrid App that I've created in the Web IDE in the Hybrid App Toolkit Companion App. There also the OData Service which feeds data to the app from my backend is called.
But now I also want to do the next step and run an on App on my Android device (Nexus 5). But here the list of results from the OData Service stays empty. In chrome://inspect I see that the app tries to call the OData Service via file://... I haven't found an example/documentation on this. Perhaps you have a pointer for me.
Best regards
Gregor
Hi Gregor!
Did you found the answer for you question? I am having the same issue..
Best Regards
Luis
Hi Luis,
the recent apps that I've created with HAT worked as soon as I used the Kapsel Logon Manager (enabled in the Project Settings of Web IDE).
Best regards
Gregor
Hi Gregor, thank you for your answer!
Actually, I already have the Kapsel Logon Manager enabled on my Project Settings. I was able to find a workaround by providing the full URI of my OData service (component.js). But this way, the destination I have defined on HCPms as the back end of my app is not being used. It doesn't seem to me to be the best approach..
Right now, I have only enabled the Kapsel Logon Manager and for the first time I run the app on my Android device, it shows me kapsel logon screen. After logging in, my device is registered in HCPms and I can now access my app
In chrome://inspect I see that the app tries to call the OData Service via file:// unless I change my OData Service definition in Component.js. In this case it will access via url://
Did you made any other configuration?
Best Regards,
Luis
In my test environment and on the phone this was working fine - super cool developement !
We are on SMP 3.0 SDK 5
In this Test we used an on premise SAP Backend with installed Gateway and just proxied the OData through the SMP (App creation with cloud connector).
Points to take care of:
One question: why is the APK so huge ? is it because its a hybrid App ?
I mean in the index.html there is just the sap.m library included ?!
Am I even using the correct APK?
C:\Users\%UNAME%\SAPHybrid\%WebIDEProjectName%\hybrid\platforms\android\ant-build\%WebIDEProjectName%-debug.apk
Second Question: Now we must create a special Kapsel Project in the Web IDE -> is it planned to get this possibility also for other kind of projects? Maybe as a general option while creating a new project 🙂
Best regards and keep developing on this project !!
Hi Thomas,
As for the App ID, where exactly are you forced to use 2 dots ? Is that in Web IDE or maybe the SMP Admin Cockpit ?
The APK is so large because we are currently packaging a large amount of UI5 libraries in the app. This is not optimised yet. We are working on this.
We are also working on mobile enablement of a large amount of project types; not specifically the Kapsel templates we now provide.
Stay tuned, there is some more interesting stuff coming.
Regards,
Ludo
Hi Ludo,
in the "Device Configuration" in the Web IDE in the property "App ID"
I can enter an App ID without two dots but then I get an error while deploying to the local hybrid toolkit:
When I enter a App ID with two dots all just works fine:
but maybe the error is something else 🙂
Best,
Thomas
I wonder if HAT is trying to set the AppID as the package name - the native SDKs expect it to be in reverse domain format (two dots minimum).
Hi John
When we try to deploy Web IDE Kapsel App to Local Hybrid Application Toolkit(HAT), we are getting errors in the Web IDE Console "XMLHttpRequest cannot load https://localhost:9010/Kapsel. Method PUT is not allowed by Access-Control-Allow-Methods".
Below link has details about our issues, please provide your insight what we are missing out...Thank you.
http://scn.sap.com/thread/3717542
Hi Ludo
I have developped a sample hybrid app in web ide, but the .apk file generated was like xxxx-debug.apk, how to get the apk file without debug? Also why it is adding debug to the .apk file?
Regards
Sreenivas
Sreenivas,
What steps are you using to generate the apk file?
A late reply via this channel; but we now support both debug and release builds.
Hi John, I installed the HAT to benefit from code completion for plugins and getting snippets. But when I create Apps there is no code completion and where can I find the snippets?
I really appreciate your help, Thomas
Hi Thomas,
The code snippets can be made visible and selected by typing kapsel followed by CTRL-space.
Thanks Ludo, but I think I'm totally wrong. We want to create Fiori Apps that run in the Fiori Client (so actually we don't have a Kapsel) and I thought I can use HAT for code completion if I want to call plugins like "navigator.camera.getPicture()"
Because there is no way to find out how the different plugins have to be called if you don't find an example from somebody else who already used the plugin.
Actually, the Kapsel plugins are also included in the Fiori Client.
I agree there should be code completion available for navigator.camera.getPicture(). But for some reason I cannot get this to work on the trial landscape either.
I have contacted my colleagues to check this.
Now I was able to test also the offline store plugIn and faced some problems on iOS devices (notwith the offline store but with the resource libraries) -> it seems that the app don't use the local libraries.
I tested this for android and iOS.
Android is working like charm - no problems at all.
on iOS after I configured my account in xCode I am able to create the app with "run on device" and can install the app on the iPhone.
The online mode runs without problems.
But when I turn on the airplane mode and start the app nothing happens. And when I turn the airplane mode on after I started the app already - I don't see the icons and so anymore. But the offline store itself is working and I can redceive data.
It looks like the recources can't be found somehow ?
Do I need to do something special in xcode or in the HAT config that the app will access the resources in the resource instead accessing the internet for accessing the libraries ?
When I am online all is fine:
But when I am offline the app can't find the resources ?
Hi Thomas,
In your index.html file, there is a line that specifies the resource location.
<script src="resources/sap-ui-core.js"
In the neo-app.json file the online resources are mapped (routes).
For a packaged app, the resources should be loaded from the local file system (in the above case, from the resource folder).
I suspect that in your app, the resources are coming from a specific url (online).
Hope this helps. If not, can you send me some code ?
Thanks,
Ludo
Yes this did the trick 🙂
I think the problem was that I created the Kapsel application with the older version of the WebIDE and in my index.html file was not the local version of the resource folder mentioned. instead of this there was a line like this
src="https://sapui5.netweaver.ondemand.com/resources/sap-ui-core.js"
I changed this to
src="resources/sap-ui-core.js"
and now all is working fine in the test. Thanks for pointing me to this. I also tested this now with the current WebIDE version and here the kapsel index.html is created like it should be 🙂
thanks - a very awsome tool
Dear Thomas Schmidt / Ludo Noens , at the end the offline app works ? I have the doubt about how the offline app gets the master data information ?
Also, do you have any post, document, use case or knowledge on how to make a Fiori app available in offline mode tru SMP ?
THanks in advance,
Rodolfo
The Kapsel Offline OData plugin is very well explained by Daniel Van Leeuwen
Getting Started with Kapsel - Part 15 -- Offline OData (New in SP05)
The first time you register to the app you need to be online and then there is a local database created on the device which gets refresht when you are online, when you are offline the app applies a separat oData client to access the local offline store and show data even there is no connection to the SAP backend.
Hi,
Can we develop iOS apps using Hybrid App tool kit in Windows system(Desktop) ? Is it compulsory to have Mac system?
Thanks
Sreenivas
How to generate the apk files from the webide?
Just to make sure the community knows the answer we have provided:
For now, the local Cordova build happens on your local PC, there is no export of apk file. A simple way is to go to your local folder: C:\Users\[userABC]\SAPHybrid\[ProjectName]\hybrid\platforms\android\out, copy the apk from there.
In our Cloud Build feature planned for a future release, a URL will be returned to developers to download the build apk or ipa file.
This blog post is outdated. We have reached end-of-maintenance for HAT local add-on. You can no longer download this tool from the SAP Store. We no longer support this tool. You are strongly advised to make use of our Cloud Build Service provided through Mobile Services to build hybrid apps. More information can be found here: https://blogs.sap.com/2018/08/16/announcing-end-of-maintenance-for-hybrid-app-toolkit-local-add-on-local-builds-only
Ludo Noens
Product Owner – Hybrid Application Toolkit