Creating self-help kiosk app with Helpinator and PhoneGap / Cordova

Disclaimer: since Helpinator is a Windows desktop app we will set up Windows 10 environment for this task.

Helpinator allows to generate so called MobileHelp output. It is based on JQuery Mobile framework and by design was intended to provide online help capabilities for mobile apps, and since it is html/css/js-output it is cross-platform by default, so you can use it with Android or iOS apps.

However the design of it makes it perfect fit for self-help kiosk apps that you can see here and there at the entrances of offices. They provide maps, lists of offices and companies and even instructions what you have to do in case of fire. One of our clients asked for a way to turn MobileHelp into an Android kiosk app for this purposes and we publish the instruction created for him.

Two most important feats of a kiosk app:

  1. Touch-friendly navigation, font sizes that can be easily read.
  2. There should be no option to quit the app or go to the Android backbone of it. This is essentially what a kiosk app is. If you allow a means to do it, the kiosk becomes unmaintanable with constant calls to reopen the app.

What we need to accomplish this task:

  1. We will use Apache Cordova project to turn MobileHelp into an Andoid app (apk).
  2. We will have to install Cordove prerequisited to run it
    1. Node.js and Node Package Manager – required to install Cordova itself
    2. Java Development Kit (JDK)
    3. Android Studio (unfortunately “standalone” Android SKDs that are available do not do the job)
    4. Gradle (actually comes with Andoid Studio, but it’s better to install it on our own).

To install Node.js go to https://nodejs.org/en/download/ and select installer for Windows version that you use.

Node.js installer

Install it into a folder outside of Program Files, say C:\nodejs

Now let’s install JDK for Windows from https://www.oracle.com/java/technologies/jdk8-downloads.html Unfortunately most likely Oracle will force you to create an account to open download links. Download the installer and install JDK into a folder like C:\JDK.

Next step is to download and install Gradle. Do it here https://gradle.org/releases/ Unzip the package to “C:\” and rename gradle-X.X.X folder to just “C:\gradle” for simplicity.

The next step is to install Andoid Studio, download the installer here: https://developer.android.com/studio Install and run the studio, create a sample project, it will download and create important SDK entries.

Now even the more boring part – you need to put paths to bin folders of all tolls to the PATH system environment variable and add a couple more variables as well.

This article tells in detail how to reach environment variables on Windows 10: https://www.architectryan.com/2018/03/17/add-to-the-path-on-windows-10/

Add the following paths to the system PATH variable: “C:\JDK\bin”, “C:\nodejs”, “C:\gradle\bin”. If we assume that you also store “Users” folder on C: drive you need to add the following, where <Username> is your Windows user name: “C:\Users\<Username>\Android\SKD\tools”, “C:\Users\<Username>\Android\SDK\tools\bin” , “C:\Users\<Username>\Android\SDK\platform-tools”.

Add new system variables:

  1. JAVA_HOME=”C:\JDK”
  2. ANDROID_SDK_ROOT=”C:\Users\<Username>\Android\SDK\ “

Now let’s install Cordova itself. Open command prompt and go to the “C:\nodejs” folder. Execute the following command:

npm install -g cordova

Now create a folder to store your projects in, let’s call it “C:\projects”. Make it a current folder in the command prompt. Let’s say we want our app to be named “HelpinatorDocs”. Run the following command to create app folder structure for it:

cordova create helpinatordocs com.helpinator.docs HelpinatorDocs

Now you have “C:\projects\helpinatordocs” folder with a prototype app in it. We are about to generate an Android app so we need to add Android as a platform to our app. Go to the “C:\projects\helpinatordocs” folder in the command prompt and run the following command:

cordova platform add android

Now our app is ready to be compiled into an “apk” package.

Note that there’s a “C:\projects\helpinatordocs\www” folder. This is where we need to store MobileHelp generated by Helpinator to. Run Helpinator, open your project and click “lightning bolt” icon on the main tool bar. “Batch compile” dialog appears.

Batch compile “MobileHelp”

Now we need to make some adjustments to the Cordova project config file to make our app a kiosk app.

Locate the file “C:\projects\helpinatordocs\config.xml” and open it in a text editor of your choice (NotePad++ for example).

What we need to do is to add a reference to the Cordova plugin that will do the job of transforming the app into a kiosk for us. It is called “cordova-plugin-kiosk-launcher”. There’s already a line that says:

<plugin name="cordova-plugin-whitelist" spec="1" />

Add a line that references our plugin just below it:

<plugin name="cordova-plugin-kiosk-launcher" />	

You can also change app title and description in the “name” and “description” tags.

We are ready to go. Type the following command in the command prompt while in the “C:\projects\helpinatordocs” folder:

cordova build android

It may take some time, but in the end you will get an apk of your file in the folder “C:\projects\helpinatordocs\platforms\android\app\build\outputs\apk\debug”.

You can copy this file to your device and install using apk installer. It does not require any dangerous permissions, so it should be OK. Test how your help system works on the device. After that you can select your app as a “launcher” app in “Defaut apps” settings of Android OS and it will replace the default lanucher that allows to launch apps. Basically your help system will run on the device boot, there will be no option to quit it and run anything else. Congrats, you have a self-help kiosk!

Leave a comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.