readme.txt

v2.79 · 18 Aug 2026

*** DO NOT USE 'X' VERSIONS FOR GOOGLE PLAY OR YOUR ACCOUNT MAY BE TERMINATED! ***


The _x_ versions of DroidScript enable certain extra admin features which are banned 
for apps published to Google Play but are useful for private/commercial projects where 
APKs are expected to be 'side loaded'.  For example full COSU (kiosk mode) and SMS 
interception are enabled in the 'X' versions.


Enabling KIOSK (COSU) mode
==========================

In Kiosk mode users will not be able to get to the Android System menus or escape your app 
unless you let them.  This is ideal for information kiosks, machine controllers or POS 
systems.  It can be used on Android Tablets, Phones and TV boxes.

WARNINGS: 

- Once you have installed your app this way you will have to FACTORY RESET to remove the app.

- You can ONLY update your app if it has the same package name and is signed with the same key.

- You may not be able to access the top pull down menus on Android when you need them, so either
  make sure you have a home screen icon available to launch the Android settings before enabling 
  KIOSK mode, or add code to your app to access the settings via a secret click area or pin 
  dialog that calls this line of code - app.SendIntent(null, null, "android.settings.SETTINGS" )


PROCEDURE:

1. Add the following code to your OnStart function:

   app.SetKioskMode( "LockTask",true, "", app.GetPackageName() )

2. Build an APK using the '_x_' version of the ApkBuilder.

3. Connect to the device from a PC via ADB using a USB cable (or via ADB-WiFi).
   (See here for instructions: https://www.xda-developers.com/install-adb-windows-macos-linux/)

4. Check that the ADB drivers are installed properly by typing the following (you should see
   your device listed)
  
   adb devices
   
5. Run the following command (change 'com.mycompany.myapp' part to match your app package name)

   adb shell dpm set-device-owner com.mycompany.myapp/com.smartphoneremote.ioioscript.DeviceAdminReceiver

6. Run your App and accept all the permission requests. Your App is now a device Administrator 
   and cannot be escaped from or removed by the user without a factory reset! 
   
   
NOTES:

You can control what users are allowed to do when kiosk mode is enabled by using various options
when calling the app.SetKioskMode method. For example you can allow certain apps to be started by
including a comma separated list of their package names in the last parameter like this:

app.SetKioskMode( "LockTask",true,"", 
        app.GetPackageName()+",com.android.tv.settings,com.android.settings,com.android.bluetooth" )

In the above case, we want to allow users to interact with the bluetooth pairing dialogs when our
app initiates a pairing request.  Howeever they still cannot get to the Android settings menu by
swiping down from the top of the screen or pressing the back button to get to the home screen.

By default the device will by fully locked down, however you can allow certain actions by including
keywords in the 3rd parameter, for example to allow access to an external USB stick do the following:

app.SetKioskMode( "LockTask", true, "physicalmedia", app.GetPackageName() )

These are the keywords available in the 'options' parameter:

  boot - set this activity so that its always started on boot.
  allowupdates - allow the system to be updated (by Google).
  allowsleep - allow the screen to dim/sleep when plugged in.

  power - enable the power button long-press actions.
  home - enable the home button.
  notifications - enable notification to be shown.
  overview - enable the recent task list overview.
  info - enable the system info area in the status bar.
  keyguard - enable the keyguard.

  safeboot - enable safeboot mode.
  factoryreset - enable factory reset from settings.
  adduser - enable adding of a new user from settings.
  physicalmedia - enable use of external usb storage devices.

You can disable KioskMode using the following code, however the app will
exit immediately after the call.

app.SetKioskMode( "LockTask",false,"",app.GetPackageName() );

If you just call app.Exit() then some of the kiosk mode restrictions may stay in place, such 
as blocking of the status bar.  It's a good idea to provide a secret button or option for 
exiting your app, maybe protected with a pin-code, so that admins/engineers can exit the app 
when needed.

Without an exit feature, you may have difficulty stopping the app to configure Android during
development or maintainance, it may become neccesary to re-power the device to exit the app, but 
if you have enabled the 'boot' option, or call app.SetAutoBoot in your code, you could get into a 
situation where you can't get out of the app as it keep starting automatically!

However most operations can still be achieved via ADB, especially if the device is rooted (many 
industrial Android devices are rooted by default). For example you can get a super user shell, list
processes (to find the process id of your app) and kill the process using the following commands:

adb shell
su
ps -e
kill 12345

Many useful operations can be done via ADB with Android 'pm' package manager and 'am' commands too

  https://developer.android.com/tools/adb#pm
  https://developer.android.com/tools/adb#am

When setting up large numbers kiosk devices in a production scenario, it may be useful to create 
Linux shell scripts or Windows batch files that can fully configure a fresh device for you via a USB
cable.  This can be done using a sequence of the adb commands, such as the 'push' command to copy 
files to the device, the 'install' command to install your packages, as well as 'dpm', 'pm' commands 
to manage/remove/modify factory installed packages.
  
Finally, ChatGPT or Gemini can be very helpful with these types of operations too :)