Introduction

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:

Link Content
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

Prerequisites

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
  • Plugman

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)

Further recommendations:

  • UAC must be set as by default

/wp-content/uploads/2015/07/04_743951.jpg

  • All the commands in the Terminal window must be executed WITHOUT administrator’s rights, otherwise you won’t be able to perform HAT setup.

Getting started

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:

Part 1:

  • Install Java Development Kit (JDK)
  • Install Android SDK
  • Install Apache Ant

Part 2:

  • 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

Part 3:

  • 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)

/wp-content/uploads/2015/07/01_828011.jpg


2) Once the download is finished double click on the downloaded file to start the installation

/wp-content/uploads/2015/07/02_828012.jpg


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

/wp-content/uploads/2015/07/03_828013.jpg


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

/wp-content/uploads/2015/07/04_743951.jpg

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

/wp-content/uploads/2015/07/2015_06_25_11_38_06_743956.jpg

2) Choose the recommended download option (for Windows), which is the one by the installer

/wp-content/uploads/2015/07/05_828015.jpg

3) Once the download is finished, double click on the downloaded file to start the installation

/wp-content/uploads/2015/07/06_828016.jpg

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

/wp-content/uploads/2015/07/07_828017.jpg

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

/wp-content/uploads/2015/07/2015_06_25_11_54_49_743960.jpg

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:

Tools

     Android SDK Tools (it comes already installed)

     Android SDK Platform-Tools

     Android SDK Build-Tools

Android 5.1.1 (API 22)

     SDK Platform

     ARM EABI v7a System Image

Android 4.4.2 (API 19)

     SDK Platform

     ARM EABI v7a System Image

Extras

     Android Support Repository

     Android Support Library

     Google Play Services

     Google Repository

     Google USB Driver


I’ve just 11 packages to install. Click on the Install 11 packages button

/wp-content/uploads/2015/07/08_828018.jpg

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

/wp-content/uploads/2015/07/09_828019.jpg

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

     /wp-content/uploads/2015/07/03_828013.jpg

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

/wp-content/uploads/2015/07/2015_06_27_19_58_24_743963.jpg

18) Specify the required parameters (this is just an example and click on OK)

19) When the summary screen appears click on OK

     /wp-content/uploads/2015/07/04_743951.jpg

20) You should be able to get your emulator in the list

/wp-content/uploads/2015/07/06_828016.jpg

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

/wp-content/uploads/2015/07/10_828020.jpg


2) Select the downloaded zip file, right click on it and choose Extract All

/wp-content/uploads/2015/07/11_828021.jpg


3) Just put the extracted folder on your C: drive’s root. A subfolder will be automatically created

/wp-content/uploads/2015/07/2015_06_25_13_08_42_743968.jpg


4) Rename the new folder simply with “apache-ant

/wp-content/uploads/2015/07/12_828022.jpg

Good job so far! Please continue with the part 2 of this H2G!


APPENDIX

Configure proxy for Android SDK Manager

1) Click on Tools –> Options

/wp-content/uploads/2015/07/2015_06_25_11_55_08_743970.jpg

2) Enter your proxy settings (i.e. for SAP Network proxy:8080)

/wp-content/uploads/2015/07/2015_06_25_11_55_39_743971.jpg

3) Close SDK Manager and reload it by double clicking on the SDK Manager executable

/wp-content/uploads/2015/07/03_828013.jpg

To report this post you need to login first.

26 Comments

You must be Logged on to comment or reply to a post.

  1. Georgi Nushev

    Hi Simmaco,

    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?

    Regards,

    Georgi

    (0) 
    1. SIMMACO FERRIERO Post author

      Hi Georgi,

      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.

      Regards,

      Simmaco

      (0) 
  2. Georgi Nushev

    Hi Simmaco,

    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:

    (0) 
    1. Georgi Nushev

      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

      Regards,

      Georgi

      IBsolution Bulgaria

      (0) 
  3. Matthias Hubert

    Hello Simmaco,

    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)

    Kind regards,

    Matthias

    (0) 
    1. SIMMACO FERRIERO Post author

      Hi Matthias,

      in order to debug the app you need the Android Device Monitor.

      /wp-content/uploads/2015/12/ss_841845.jpg

      If you have installed all correctly, you should be able to call it by typing “monitor” in the Command prompt window.

      Regards,

      Simmaco

      (0) 
  4. Matthias Hubert

    Hi Simmaco,

    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:

    Application Error

    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?

    Best regards,

    Matthias

    (0) 
  5. Matthias Hubert

    Hi Simmaco,

    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,

    Matthias

    (0) 
  6. Matthias Hubert

    Hi Simmaco,

    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,

    Matthias

    (0) 
    1. SIMMACO FERRIERO Post author

      Hi Matthias,

      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 ?

      Regards,

      Simmaco

      (0) 
  7. Hiago de Oliveira

    Hi,

    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.

    ERRO_HAT.jpg

    (0) 
  8. sanjo thomas

    Hi,

    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?

    thanks,

    Sanjo Thomas

    (0) 
    1. SIMMACO FERRIERO Post author

      Sanjo,

      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.

      Regards,

      Simmaco

      (0) 
      1. sanjo thomas

        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 outerr.PNG

        (0) 
  9. Daniel Rosenbaum

    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:


    • Part 2, Step “Download and install SAP Kapsel Plugin”:
      • There is a small directory change. The new one “\modules\KapselFramework\smp-plugins-dist” is equivalent to “\modules\KapselSDK” in the guide.
    • Part 2, Step “Install Node.js”:
    • Part 2, Step “Install Apache Cordova 5.2.0”:
      • Version 6.0.0 is required, so just use the command: npm install -g cordova@6.0.0
    • Part 2, Appendix:
      • In all descriptions of the proxy settings there is a small typo (double colon in proxy address). The right way is: <protocol>://<proxyhost>:<proxyport>
    • Part 3, Step “Run HAT and test its connectivity with SAP Web IDE”:
      • In the Web IDE you have to activate the “Hybrid App Toolkit” at first in “Preferences -> Plugins”


    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 🙂

    Best regards

    Daniel

    (0) 
  10. VIDYA S

    Hi Simmaco,

     

    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 – 3.0.13.0

     

    Regards

    Vidya

    (0) 
    1. SIMMACO FERRIERO Post author

      Vidya,

      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?

       

      Regards,

      Simmaco

      (0) 

Leave a Reply