How to install Hybrid Application Toolkit (HAT) on Windows (part 1 of 3)
*** 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. 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 ***
Today I’m gonna show you how to install the Hybrid Application Toolkit (HAT) on a Windows machine. Hybrid Application Toolkit (from now on simply HAT) is the tool which allows you to deploy SAP Hybrid applications on mobile devices. Hybrid application (also known as Kapsel applications) can be created by using SAP Web IDE and then deployed on mobile devices with this tool. In order to get more information on this tool and on SAP Web IDE I suggest you to give a look to this page (SAP Web IDE – Overview). Here you can find a lot of other useful resources for SAPUI5 application development.
This blog is just for Windows: if you want to know how to do the same on Mac please also follow this blog: How to install Hybrid Application Toolkit (HAT) on Mac.
HAT installation is NodeJS based: it guides you through all the steps for a successful result. However in order to avoid the needing to start the installation and then going back and forth installing the missing components, with this blog, I’m giving you a sort of good starting point so that when you start the HAT installation it will be as smooth as possible and you will be no longer required to leave the installation process for installing other mandatory software.
This blog has been split in 3 parts:
|Part1||Install JDK, Android SDK and Apache ANT|
|Part2||Install NodeJS, Cordova, Kapsel, Git, Plugman and configure environment variables|
|Part3||Install HAT and test it|
In this blog I would like to start with a very blank Windows machine, so I’m gonna show you how to install all the needed tools for SAPUI5 application development. We will go through the installation of the following components:
- Java JDK 8
- Android SDK rel. 24.4.1
- Apache Ant 1.9.6
- SAP Kapsel Plugin SP10 PL1
- Node.JS v.0.12.7
- Git client
- Hybrid Application Toolkit 1.9.7
- Cordova 5.2.0
The prerequisites here are nothing more then the following ones:
- Windows 8.1 64bit
- Google Chrome browser
- An account on the SAP HANA Trial Landscape accessible by this link (SAP HANA Cloud Platform)
- UAC must be set as by default
- All the commands in the Terminal window must be executed WITHOUT administrator’s rights, otherwise you won’t be able to perform HAT setup.
As I said, for your comfort, I will start from the very beginning, so with a very blank machine. I’ve split the complete how-to-guide over 3 parts. This is the complete list of the steps we will go through:
- Install Java Development Kit (JDK)
- Install Android SDK
- Install Apache Ant
- Download and install SAP Kapsel Plugin
- Configure some environment variables (JAVA_HOME, ANT_HOME, KAPSEL_HOME, ANDROID_HOME and PATH)
- Install a GIT client
- Install Node.js
- Install Kapsel CLI
- Install Cordova
- Install Plugman
- Download HAT
- Setup HAT
- Run HAT and test its connectivity with SAP Web IDE
- Deploy your first Kapsel app to local Hybrid App Toolkit
So, let’s focus here just on the first part!
Install Java Development Kit (JDK)
Java Development Kit is required by the Android SDK, so as first step we need to install this component. In this guide I’m using JDK 8, but 7 is fine as well.
1) Go to JDK download page “Java SE Development Kit 8 – Downloads“, accept the license agreement and download the JDK according to your Windows platform (32 or 64 bit)
2) Once the download is finished double click on the downloaded file to start the installation
3) Leave all by default and click Next at every step. When you reach the step where you can change the installation path, take note of this path because it will be required later when you are going to configure the JAVA_HOME system variable
4) When the installation finishes, you can check that all worked fine by opening a Terminal window and typing the command “java -version“. You should get something like this
Install Android SDK
For the Android SDK you can go to the following URL: Download Android Studio and SDK Tools | Android DevelopersNow you have two possibilities:
- download the complete Android Studio suite which contains in bundle the Android SDK
- download the stand-alone version of SDK without the Android Studio.
In this guide, I’ll follow the second approach, but the first one is fine as well: just write down the path where the bundled SDK tool is installed.
1) Go to the download URL and click on Other Download Options
2) Choose the recommended download option (for Windows), which is the one by the installer
3) Once the download is finished, double click on the downloaded file to start the installation
4) Accept the UAC request by clicking on Yes
5) Click on Next on the Welcome screen
6) Click on Next on the screen where the current installed Java version is verified
7) Choose if you want to install this just for you or for everyone and click on Next
8) Take note of the installation path (it will be required later) and click on Next
9) Click on Install
10) When the installation is completed click on Next
11) Choose to Start the SDK Manager and click on Finish
12) The SDK manager starts: if you get an error like this, it’s because most probably you are behind a firewall and you need to configure your proxy settings; so click on Close and read the APPENDIX to this section named Configure proxy for Android SDK Manager.
If you have no “Failed to fetch” error, you can continue with next step
13) Now you need to specify the packages you want to install. For this H2G we will choose to install Android 5.1.1 (API 22). This because, at moment, this is the highest supported Android version by the latest Kapsel plugin. You can install newer versions of Android, but the installation process will always check and require the presence of API 22 to work. In my case these are the packages I’m going to install:
Android SDK Tools (it comes already installed)
Android SDK Platform-Tools
Android SDK Build-Tools
Android 5.1.1 (API 22)
ARM EABI v7a System Image
Android 4.4.2 (API 19)
ARM EABI v7a System Image
Android Support Repository
Android Support Library
Google Play Services
Google USB Driver
I’ve just 11 packages to install. Click on the Install 11 packages button
NOTE: After the installation of Google USB Driver, in order to have it fully working with your mobile device, you have to follow the instructions reported at this link: OEM USB Drivers | Android Developers
14) Select the root Android SDK License, click on Accept License and then on Install
15) The installation of the required packages starts. It might require some time depending on your network speed, so be patient. If you get an error saying “Stopping ADB server failed (code -1)” at the beginning of the installation process, don’t worry, it’s normal!
16) When the installation finishes, you might need to restart your Android SDK manager
17) We need to create an Android Virtual Device(AVD) in order to test our Android applications. Of course, this shouldn’t be mandatory, because I could test my applications just by using my Android phone, but at moment the HAT setup looks for it, so we need to configure it. In the future probably this won’t be a mandatory step.
In order to create your first AVD, select Tools –> Manage AVDs, click on the Device Definitions tab, select a suitable device for your Android emulator (i.e. Nexus 4) and click on Create AVD
18) Specify the required parameters (this is just an example and click on OK)
19) When the summary screen appears click on OK
20) You should be able to get your emulator in the list
21) You can close the tool.
NOTE: Using the Android Emulator with this kind of ARM processor might result very slow. I suggest you to use (if possible) Virtual Machine Acceleration as explained here. In this way you can have a better emulated device for your development.
Install Apache Ant
For the Apache Ant software installation, you can download it from Apache Ant – Binary Distributions
The latest version at the time I’m writing this guide is 1.9.6.
1) Download this version
2) Select the downloaded zip file, right click on it and choose Extract All
3) Just put the extracted folder on your C: drive’s root. A subfolder will be automatically created
4) Rename the new folder simply with “apache-ant“
Good job so far! Please continue with the part 2 of this H2G!
Configure proxy for Android SDK Manager
1) Click on Tools –> Options
2) Enter your proxy settings (i.e. for SAP Network proxy:8080)
3) Close SDK Manager and reload it by double clicking on the SDK Manager executable
thanks for the great blog, but could you please post the exact version prerequisites, because here you are installing all the latest components, but I do have most of them already installed on my computer. Do I need Windows 8.1 machine, or it is also possible to install it on Windows 7?
Windows 7 is also fine! You can find all the prerequisites in the installation guide here
SAP Web IDE Hybrid App Toolkit Add-on
The installation process, however, which is web based, will guide you through the installation of all the missing or old components you have on your machine.
You can start the installation and do a preliminary check to see what is missing and what is not up to date.
Hi Simmaco and thanks for your replay,
could you also please check my discussion with an issue I got during installation:
i fixed the above issue, but now in the web based installation check, I get issue in the Cordova Build Android Project with Error: "please install android target : "andoird-22".
For Andoird 5.1.1(API 22), i do have installed the SDK Platform, I also have installed the latest Andoird SDK Platform and Build-tools.
Here is a screen shot from the issue:
Thanks to Simmaco, we solved the above issue.
For the Android version, somehow I had 2 Android SDK installed, so the path pointed to the wrong one, so I just needed to add the right path.
Also if you had a older version of the KapselSDK installed, you need to type in the cmd :
npm -g install C:\KapselSDK\cli (or you installation path) to install the new version.
You could check the installed version by running: kapsel -v
I have the same problem.
What do you mean that you just had to add the right path? My ANDROID_HOME path is correct.
Why do we need some local tools while developing in WEB IDE??? Are there any plans privide cordova build in the cloud?
at the moment we need this local tool. Very soon there will be Cloud service for this. You can get a sneak preview of it by taking a look to the SAP TechEd 2015 Barcelona Keynote video you can find here:
SAP Executive Keynote: Björn Goerke, Barcelona 2015 | SAP TechEd Online</title></head><body> …
Starting from the minute 34 you can see it.
fine! Thanks a lot 🙂
I installed HAT as described in this and the preceding tutorials.
Then I used web IDE to convert a SAP UI5 app to a Kapsel app. The app is very simple it displays a dropbox and displays some text depending on the selected entry on the dropbox. The app does not use ODATA.
I ran the app as Web Application in WEB-IDE. It works there.
Then I deployed the app on the device. I did not select any plugin.
I can see that the app is available in the SAPHybrid directory on my local pc. When I use web-ide to run the app on an Emulator I see in the WEB-IDE console that the apk file is built and the app is installed successfully on the emulator. However when I click on the icon for the app in the emulator a white screen is displayed and then the following error message is displayed in the emulator: Application Error The connection to the server was unsucessful. (file:///android_asset/www/index.html).
In the WEB-IDE console I can see the following entries:
12:17:33 AM (hybrid-toolkit) Unlocking screen...
12:17:33 AM (hybrid-toolkit) deploying...
12:17:34 AM (hybrid-toolkit) Launching application...
12:17:43 AM (hybrid-toolkit) LAUNCH SUCCESS
12:17:43 AM (hybrid-toolkit) emulate android process exited normally
Can you please tell me how I can debug the application in the emulator in order to find the reason for the application error? (As mentioned before the kapsel application works if you run it as an web application in WEB-IDE)
in order to debug the app you need the Android Device Monitor.
If you have installed all correctly, you should be able to call it by typing "monitor" in the Command prompt window.
thank you for your help. When I run the app on the on the emulator I can see the following error message in the emulator screen:
The connection to the server was unsuccessful. (file:///android_asset/www/index.html)
In the Android Device Monitor I can see the following log entries:
E/CordovaWebViewImpl(1161): CordovaWebView: TIMEOUT ERROR!
12-04 18:27:49.254: E/AndroidProtocolHandler(1161): Unable to open asset URL: file:///android_asset/www/resources/sap/ui/core/library-preload.json
12-04 18:27:49.714: E/AndroidProtocolHandler(1161): Unable to open asset URL: file:///android_asset/www/resources/sap/m/library-preload.json
12-04 18:27:58.574: E/AndroidProtocolHandler(1161): Unable to open asset URL: file:///android_asset/www/parentapp/manifest.json
12-04 18:27:59.214: E/AndroidProtocolHandler(1161): Unable to open asset URL: file:///android_asset/www/resources/sap/ui/core/themes/sap_bluecrystal/library-parameters.json
12-04 18:27:59.264: E/AndroidProtocolHandler(1161): Unable to open asset URL: file:///android_asset/www/resources/sap/m/themes/sap_bluecrystal/library-parameters.json
12-04 18:27:59.554: E/AndroidProtocolHandler(1161): Unable to open asset URL: file:///android_asset/www/webapp/Component-preload.js
12-04 18:28:00.364: E/AndroidProtocolHandler(1161): Unable to open asset URL: file:///android_asset/www/resources/sap/ui/layout/library-preload.json
12-04 18:28:00.634: E/AndroidProtocolHandler(1161): Unable to open asset URL: file:///android_asset/www/resources/sap/ui/layout/themes/sap_bluecrystal/library-parameters.json
I have to mention that I converted a UI5 app to a Kapsel app automatically in web-ide.
When I start the Kapsel app it is working in web-ide. The app is quite simple it contains just a field with a combobox and a form for the text output. The app neither uses ODATA service nor a kapsel-plugin/cordova-plugin. Therefore I did not specify an ODATA service and I did not specify any plugin when deploying the app to device.
I checked the project folder on my local PC C:\Users\...\www\resources: It does not contain the files which are mentioned in the error messages (e. g. library-preload.json).
As far as I understand are the missing files system files. From where can I get the missing files and how can I include the missing files into the deploy process of the HAT in order to solve the errors described above?
are you able to send me in some way your application? You can export it from SAP Web IDE and send it to me.
now I have a question regarding the ui5 version which is used by HAT to create an Android app. I had a look at the folder which contains the android app generated by HAT:
C:\Users\SAPHybrid\<name of my application>\hybrid\platforms\android\assets\www\resources
There the file sap-ui-core.js is located.
When I open that file I can see in the comment
* UI development toolkit for HTML5 (OpenUI5)
* (c) Copyright 2009-2015 SAP SE or an SAP affiliate company.
* Licensed under the Apache License, Version 2.0 - see LICENSE.txt.
I would like to distribute my app according to the regulations specified in the apache licence version 2.0. Therefore I have the following questions:
a) Does the android app consist only of components covered by apache licence version 2.0?
b) Does the app contain also sap components which are not covered by that licence (e. g. sap components for which I have to buy a licence in order to be allowed to distribute the app)?
Thanks for your help,
I developed a kapsel app and I can run that app on an emulator.
However when I select in Web IDE the index.html in my app and then select right mouse button and select 'Run' - 'Run on' - 'Android Device' the following popup appears:
'Select a Signing Key for Android Release Builds'
In the popup I select the radio button for 'Test Key' and press the 'OK' button.
Then another popup appears saying 'WARNING: No device found! Try to use emulator.
However an Android Device (Samsung Galaxy S2 mobile phone) is connected to the PC via USB. I downloaded the Samsung USB driver and installed it on the PC.
From the windows explorer I can access the S2 mobile phone which is connected to the PC via USB. Therefore I assume that the USB connection between PC and S2 mobile phone is available.
However when I go to WEB IDE and try to run the app on an Android Device I get the warning: No device found (as described above).
Did you encounter a similar problem? Any help would be appreciated.
Thank you and best regards,
maybe it would be better if you could ask these kind of questions by opening a new Discussion marked as a Question with your issue. It will get better visibility and it is also the proper way to proceed. However, regarding your problem I never experienced such kind of thing and I've also tried with a couple of Android devices. Have you tried with another one? Did you check if the Google USB Driver is properly installed and configured as described here OEM USB Drivers | Android Developers ?
Thank you very much for your valuable guide.
I'm almost done. But I stuck up at Level 3 "Build Hybrid Companion App" -> "Build the companion app" step.
Please check the below screenshot and help me out.
I have a doubt, I have created an app which consists of charts(i.e vizframe charts), it runs on the web perfectly, but when I tried it running on android phone after converting it to .apk, it didn't recognize viz libraries. So, is the fault on my side or is it not supported?
Viz is supported. Do you mind to share the project or give me more information about the error that you can capture in the background?
You can write me in private.
Yes sure,please follow me so that I could send direct message. Actually it isn't identifying the resources/sap/viz/library.js and resources/ui/thirdparty/d3.js. Help me out
First of all, thank you Simmaco Ferriero for this very detailed how-to-guide! That is some excellent and useful work!
When I went through the steps, I have found some minor mistakes and some outdated stuff and I thought I might share these issues for other people who are completing the installation of HAT:
As you can see, these are mostly minor remarks, but the newer versions of Node.js and Cordova were inevitable during my installation.
I hope this will be of use to someone 🙂
Thanks! I'll try to update my blog taking your suggestions into account.
Do you know why node.js is still 5.4.1? Is there a chance to use 8.x.x?
I know there were some plans about the HAT as a Cloud version?
Is there any update on that?
unfortunately I have no news regarding this. Probably we still need to wait.
I was able to install HAT successfully following the blog However, when I deploy an app , I see the below error on the emulator:
The connection to the server was unsuccessful (file:///android_asset/www/main.html)
Cordova Version - 6.3.1
Kapsel - 3.13.0
SMPSDK - 18.104.22.168
make sure you are able to navigate on internet from your Android device. Secondly, I'm not sure why you are having an error on "main.html". The first page to be loaded should be "index.html". Could you please try by creating a new very basic app from SAP Web IDE starting from the SAPUI5 Application template?
while installig HAT 1.29
we are getting an error plz suggest.
cordova build android project error!
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. 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
Product Owner – Hybrid Application Toolkit