Need help with cordova-plugin-kiosk?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

hkalina
134 Stars 81 Forks Apache License 2.0 53 Commits 22 Opened issues

Description

Cordova plugin to use Cordova application "in kiosk mode" and as Android launcher

Services available

!
?

Need anything else?

Contributors list

No Data

Cordova Kiosk Mode

A Cordova plugin to create a Cordova application with "kiosk mode". An app with this plugin can be set as an Android launcher. If the app starts as a launcher, it blocks hardware buttons and statusbar, so an user cannot close the app until the app request it.

This plugin does not change behavior of application until it is set as launcher - home screen of the device.

Escape from the app is possible only using javascript call

KioskPlugin.exitKiosk()
or by uninstalling the app using
adb
. (Keeping USB debug allowed necessary.) If the application starts as usual (not as a launcher), no restrictions are applied.
  • Official plugin website: https://github.com/hkalina/cordova-plugin-kiosk
  • Example app: https://github.com/hkalina/cordova-kiosk-demo

This plugin is for Android platform only. For kiosk on iOS platform check its Guided Access feature.

About

By adding this Cordova plugin the Cordova app becomes a homescreen (also known as a launcher) of Android device and should block any attempt of user to leave it.

To add plugin into existing Cordova / Phonegap application use:

cordova plugin add https://github.com/hkalina/cordova-plugin-kiosk.git

To add specific version of this plugin (like

v2.0
) use:
cordova plugin add https://github.com/hkalina/cordova-plugin-kiosk.git#v2.0

Android platform files (like

AndroidManifest.xml
) should be updated immediately. If you will modify plugin code, you will need to re-add android platform to plugin modifications take effect:
cordova platform rm android
cordova platform add android

To has it working, user have to set this application as launcher (see below) and start it by pressing Home button or by restarting the device.

WARNING Before installation ensure you have USB debug mode enabled. Without USB debug enabled you can get stuck in broken kiosk application.

Short API description

Exiting from Kiosk mode using Javascript in the page (for hidden/authenticated button to escape the kiosk application):

KioskPlugin.exitKiosk();

Detecting whether the app is successfly running in kiosk mode (kiosk activity is opened):

KioskPlugin.isInKiosk(function(isInKiosk){ ... });

Detecting whether the app (kiosk activity) is set as launcher:

KioskPlugin.isSetAsLauncher(function(isLauncher){ ... });

The device is effectively locked only when both methods returns

true
. When the app is "in kiosk", but not set as a launcher, user can escape the app by pressing a Home button (but other buttons are still locked).

Defining allowed buttons - buttons whose event propagation should not be prevented - so you can for example allow setting volume up/down:

KioskPlugin.setAllowedKeys([ 24, 25 ]); // KEYCODE_VOLUME_UP, KEYCODE_VOLUME_DOWN

For list of keycode values check KeyEvent reference: https://developer.android.com/reference/android/view/KeyEvent#KEYCODE_0

For complete example application check: https://github.com/hkalina/cordova-kiosk-demo

Tips

  • To remove this application use

    adb
    : (Do not install it without USB debug mode enabled!) (com.example.hello replace with package of your app defined in your config.xml)

    $ANDROID_HOME/platform-tools/adb uninstall com.example.hello
    
  • To change launcher (reset setting which launcher is default):

    • Alcatel: Settings - Applications - All - (This Application) / Launcher - Clear defaults, after Home press will be asked for default to set
    • Xiaomi: Settings - Installed apps - Defaults - Launcher
  • To disable screenlock: ("slide to unlock")

    • Alcatel: Settings - Security - Set up screen lock - None
    • Xiaomi: Settings - Additional settings - Developer options - Skip screen lock

"Application Error - The connection to the server was unsuccessful. (file:///android_asset/www/index.html)" occurred

  • One reason can be too long loading of

    index.html
    - you can set timeout of Cordova's WebView in
    config.xml
    of application: (value is in milliseconds)
    
    

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.