Android lock task mode

Lock task mode

This developer’s guide explains how dedicated devices can be locked to a single app or a set of apps. If you’re an enterprise mobility management (EMM) developer or solutions integrator read this guide to add lock task mode to your solution.

Overview

Android can run tasks in an immersive, kiosk-like fashion called lock task mode. You might use lock task mode if you’re developing a kiosk application or a launcher to present a collection of apps. When the system runs in lock task mode, device users typically can’t see notifications, access non-allowlisted apps, or return to the home screen (unless the home screen is allowlisted).

Key Term: Lock task mode and screen pinning are sometimes used interchangeably. Screen pinning appears similar (and provides an immersive experience) but the person using the device can exit the mode whenever they want.

Only apps that have been allowlisted by a device policy controller (DPC) can run when the system is in lock task mode. Apps are allowlisted because the person using the device can’t always leave lock task mode.

How you combine the app allowlisted for lock task mode and the allowlisting DPC will depend on the problem you want to solve. Here are some examples:

• A single app package that combines a kiosk (to present content) and a mini DPC (to allowlist itself for lock task mode).
• A DPC that’s part of an enterprise mobility management solution, launching the customer’s mobile apps in lock task mode.

Availability

The system can run in lock task mode in Android 5.0 or later. Table 1 shows which versions of Android support allowlisting apps by user.

Table 1. Android version support for DPC admin modes

Android version	DPC administers	Notes
Android 5.0 (API level 21) or higher	Fully managed device
Android 8.0 (API level 26) or higher	Affiliated secondary user	The secondary user must be affiliated with the primary user. See affiliated users.
Android 9.0 (API level 28) or higher	Secondary user

In Android 9.0 or later a DPC can start any app’s activity into lock task mode. In earlier versions, the app must already support starting its own activity in lock task mode.

Allowlist apps

A DPC must allowlist apps before they can be used in lock task mode. Call DevicePolicyManager.setLockTaskPackages() to allowlist apps for lock task mode as shown in the following sample:

Kotlin

To find out the apps previously allowlisted for lock task mode, a DPC can call DevicePolicyManager.getLockTaskPackages() . Other apps can call DevicePolicyManager.isLockTaskPermitted() to confirm that an app package supports lock task mode.

Start lock task mode

In Android 9.0 (API level 28) or higher, you can start another app’s activity in lock task mode. If an activity is already running in the foreground or background, you need to relaunch the activity. Call ActivityOptions.setLockTaskEnabled() and supply these options when starting the activity. The following snippet shows one way you can do this:

Kotlin

In Android versions before 9.0, an app starts its own activities in lock task mode by calling Activity.startLockTask() . To call this method, the activity must be running in the foreground (see Activity-lifecycle concepts) so we suggest calling in the onResume() method of an Activity or Fragment . Here’s how you can call startLockTask() :

Kotlin

Don’t start lock task mode when the device is locked because the user might not be able to unlock the device. You can call KeyguardManager methods to find out if the device is locked and use an Activity lifecycle callback (such as onResume() that’s called after unlocking) to start lock task mode.

An app in lock task mode can start new activities as long as the activity doesn’t start a new task—except tasks that launch an allowlisted app. To understand how tasks relate to activities, read the guide Understand Tasks and Back Stack.

Alternatively, you can declare in your app manifest file how an activity should behave when the system is running in lock task mode. To have the system automatically run your activity in lock task mode, set the android:lockTaskMode attribute to if_whitelisted as shown in the following example:

You can learn more about declaring options in the app manifest file, by reading the lockTaskMode reference.

Stop lock task mode

A DPC can remotely stop lock task mode by removing the app package from the allowlist. Call DevicePolicyManager.setLockTaskPackages() , in Android 6.0 (API level 23) or later, and omit the package name from the allowlist array. When you update the allowlist, the app returns to the previous task in the stack.

If an activity previously called startLockTask() , then the activity can call Activity.stopLockTask() to stop lock task mode. This method only works for the activity that started lock task mode.

Lifecycle callbacks

Your DPC might find it useful to know when an app (running in the same user) enters and exits lock task mode. To receive callbacks, override the following callback methods in your DPC’s DeviceAdminReceiver subclass:

onLockTaskModeEntering() Called after an app enters lock task mode. You can get the package name of an app from the pkg argument. onLockTaskModeExiting() Called after an app exits lock task mode. This callback doesn’t receive information about the app.

If you launch another app into lock task mode, you need to track the running status in your own app. To check if the current app is running in lock task mode, use the methods on ActivityManager as shown in the following example:

Kotlin

Customize the UI

When an app runs in lock task mode, the system user interface (UI) changes in the following ways:

• The status bar is blank with notifications and system information hidden.
• The Home and Overview buttons are hidden.
• Other apps can’t launch new activities.
• The lock screen (if set) is disabled.

In Android 9.0 or higher when lock task mode is enabled, your DPC can enable certain system UI features on the device—useful to developers creating a custom launcher. Call DevicePolicyManager.setLockTaskFeatures() as shown in the following snippet:

Kotlin

The system disables any features you don’t include in the flags argument. The enabled UI features persist between launches into lock task mode. If the device is already in lock task mode, any changes you make to the lock task features show immediately. Table 2 describes the UI features you can customize.

Table 2. Customizable system UI features in lock task mode

System UI feature	Description
LOCK_TASK_FEATURE_HOME	Shows the Home button. Enable for custom launchers—tapping an enabled Home button has no action unless you allowlist the default Android launcher.
LOCK_TASK_FEATURE_OVERVIEW	Shows the Overview button (tapping this button opens the Recents screen). If you enable this button, you must also enable the Home button.
LOCK_TASK_FEATURE_GLOBAL_ACTIONS	Enables the global actions dialog that shows when long-pressing the power button. The only feature that’s enabled when setLockTaskFeatures() hasn’t been called. A user typically can’t power off the device if you disable this dialog.
LOCK_TASK_FEATURE_NOTIFICATIONS	Enables notifications for all apps. This shows notification icons in the status bar, heads-up notifications, and the expandable notification shade. If you enable this button, you must also enable the Home button. Tapping notification actions and buttons that open new panels, doesn’t work in lock task mode.
LOCK_TASK_FEATURE_SYSTEM_INFO	Enables the status bar’s system info area that contains indicators such as connectivity, battery, and sound and vibrate options.
LOCK_TASK_FEATURE_KEYGUARD	Enables any lock screen that might be set on the device. Typically not suitable for devices with public users such as information kiosks or digital signage.
LOCK_TASK_FEATURE_NONE	Disables all the system UI features listed above.

A DPC can call DevicePolicyManager.getLockTaskFeatures() to get the list of features available on a device when lock task mode is enabled. When a device exits lock task mode, the user interface returns to the state mandated by existing device policies.

Block windows and overlays

When an app runs in lock task mode, other apps and background services can create new windows that Android displays in front of the app in lock task mode. Apps and services create these windows to show toasts, dialogs, and overlays to the person using the device. Your DPC can prevent these by adding the DISALLOW_CREATE_WINDOWS user restriction. The following example shows how you might do this in the onLockTaskModeEntering() callback:

Kotlin

Your DPC can remove the user restriction when the device exits lock task mode.

Additional resources

To learn more about dedicated devices, read the following documents:

• Dedicated devices cookbook with further examples to restrict the dedicated devices and enhance the user experience.
• Dedicated devices overview is an overview of dedicated devices.
• Manage multiple users explains how to share devices between users.

Content and code samples on this page are subject to the licenses described in the Content License. Java is a registered trademark of Oracle and/or its affiliates.

Источник

Gateworks Android Kiosk Mode — Digital Signage Software

Digital Signage has exploded over the last few years and is now utilized in businesses ranging from fast food restaurants for menu boards to factories for showing real time productivity analytics. The uses for digital signage is unlimited and the cost has come down to a price point that even small businesses can afford.

Gateworks has created a simple digital signage software interface using Android to be used on the ​ Gateworks Single Board Computers, specifically the Ventana Family. The signage solution can be connected to a large HDMI monitor or an LVDS LCD display.

The Gateworks Kiosk software uses the Android Operating System and Default Browser. Gateworks has modified the software so that the browser will launch automatically when the system is booted. The browser launches to a URL defined in the bootloader.

Kiosk mode has the following features:

• Browser launches to URL defined in the bootloader
• Failover URL to local storage is available when network connection is lost
• A refresh rate can be defined through a variable in the bootloader
• These features can be configured using the information: here

Gateworks has provided a pre-compiled binary for getting started quickly with the Kiosk Mode.

This pre-compiled binary features the following:

• Fits on 256MB Flash devices (rare for Android, this is a trimmed down optimized Android build)
• Boots to the URL defined in the bootloader as explained here: Bootloader Configuration

Please contact Gateworks support for a pre-compiled binary.

Getting Started with Pre-Built Binary

Gateworks provides pre-built Android images that you can evaluate without building the source if needed. You have the following options:

• download UBI image if you have a board with 1GB/2GB of NAND flash and want to boot Android from flash
• download tarball and image a removable block storage device (mSATA / USB / uSD)

• Android 5.1.1 (Lollipop) Kiosk:
  • Built on 2019-03-23 from Gateworks Android Kiosk BSP:
    • Source: ​ https://github.com/Gateworks/imx_android/tree/gateworks_l5.1.1_2.1.0-ga_kioskmode
    • Based on Freescale l5.1.1_2.1.0-ga source
  • ubi images:
    • ​ ventana-android-l5-1-1_2-1-0-ga_kioskmode-user-20190923-3_normal-ubi — UBI image for 2K page size ‘normal’ geometry FLASH (see here to determine your flash geometry)(sha256sum:447c9c09f0fa0e58dda38859ef857c6bb760ca9847658bfd1ca6708997dd8b1d)
    • ​ ventana-android-l5-1-1_2-1-0-ga_kioskmode-user-20190923-3_large-ubi — UBI image for 4K page size ‘large’ geometry FLASH (see here to determine your flash geometry)(sha256sum:447c9c09f0fa0e58dda38859ef857c6bb760ca9847658bfd1ca6708997dd8b1d)
    • see here for info about flashing UBI images
  • tarballs (for imaging onto removable block storage devices):
    • ​ ventana-android-l5-1-1_2-1-0-ga_kioskmode-user-20190923-3-ta.xz (sha256sum:1d60401c23e5531d9f5738a6c7640358e185b222f5074e92bd8ee4fcd474f0f4)

1. Download Pre-Built binary
2. Install Pre-Built Android Kiosk binary to the board, Instructions Here
3. Boot board and enter into bootloader command prompt
4. Set bootloader variables as described here: Bootloader Configuration
5. Ensure board has proper internet connection
6. Boot board and enjoy the signage!

Kiosk Mode Development

The goal of this page is to outline the process of modifying the stock browser app on Android systems to simulate a «Kiosk» mode. It also details modifications to the AOSP source that will supplement this function. This could potentially be used for demonstration purposes, digital signage, or for unsupervised public access applications. A self-service configuration such as this empowers multiple users to complete tasks or view information at their convenience and at their own pace while retaining the security of your device and any potentially sensitive data it may contain.

This particular implementation effects a system that immediately after booting opens the stock AOSP browser app and displays a web page that the user can navigate within. The opened browser app can not be closed or otherwise switched out of nor can they enter in their own URL. The kiosk mode browser will check for particular bootloader arguments at runtime that allow for a configurable target URL to be set. Keyboard, mouse, or touch-screen are supported but certain functions that would allow the user to break out of the browser or access the URL/address-bar are disabled. No attempt is made to secure the device by disabling serial console or adb, however one could easily add that if desired.

This process description assumes a basic understanding of both Android development and using the Android OS in general. It specifically pertains to modifying the com.android.browser application included in AOSP 5.1 (Lollipop) but can be used as a reference for modifying other applications and/or versions.

Building Kiosk Mode from Source

Before continuing, follow the steps at Android/Building if you have not already set up a working AOSP directory.

Once you reach the Fetching Source section of the build page, be sure to use gateworks_l5.1.1_2.1.0-ga_kioskmode as your target of the ./repo init command. This will apply all of the necessary target changes and modifications necessary for producing a 256M Kiosk image by following the rest of the build steps.

Design Theory

The following modifications create a kiosk mode environment for the stock Android Browser application. It is recommended to at least implement the following sections in order to implement a relatively secure Kiosk version of the browser app that still maintains proper functionality:

The decision ultimately falls on the developer to choose which Kiosk features they wish to implement. Pick whatever combination of modifications necessary to achieve the desired functionality of your kiosk/single use application.

Create a Boot Receiver

This section details the steps necessary for an app to receive the BOOT_COMPLETED intent action which will cause your application to begin immediately after system start up in place of the default launcher application.

This step is not specific to the stock Android browser or kiosk mode and can be done to any app that you wish to launch on the completion of Android’s boot-up.

Add the following 2 sections to the top level ./AndroidManifest.xml :

Suppress Back Navigation Button

This section details the process for consuming and ignoring a back navigation button press in your main activity. This disables the normal function of exiting your app once in the main activity.

This step is specific to the Android app you are working with.

Due to the nature of the stock Android browser app with its use of WebView elements in a single Activity, the back press is handled in the ./src/com/android/browser/Controller.java class. In order to override closing your app when the back key is pressed (and to avoid potential bugs when using Lock Task Mode), make the following edits to the goBackOnePageOrQuit() method of the aforementioned Controller.java class.

If not using the stock Android browser app, you need to edit your main activity class and override the onBackPressed() method. The main activity can be found by looking in your top level ./AndroidManifest.xml for android.intent.action.MAIN and seeing which activity contains it.

Disabling the Power Button

This section details how to disable the power button (a physical button tied to the Android POWER key event). This can be done one of two ways. The short and simple method is to disable the POWER key mapping in your AOSP’s key layout file.

Key layout files are searched for in the following order:

• /system/usr/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl
• /system/usr/keylayout/Vendor_XXXX_Product_XXXX.kl
• /system/usr/keylayout/DEVICE_NAME.kl
• /data/system/devices/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl
• /data/system/devices/keylayout/Vendor_XXXX_Product_XXXX.kl
• /data/system/devices/keylayout/DEVICE_NAME.kl
• /system/usr/keylayout/Generic.kl
• /data/system/devices/keylayout/Generic.kl

If you are using an external input device such as a keyboard and are unsure about which key layout file applies to your input device, perform a adb shell cat /proc/bus/input/devices . This will list the currently connected devices. The vendor, product, and version information is found in the first line of each section in the following format:

The second method for ignoring power events while in your application is substantially more complex, but can be preferred if you wish to keep any code changes contained to just the application source. Note that although this is done using a similar intent/receiver method used for creating a boot receiver, you can not declare the receivers in the top level AndroidManifest.xml when handling power button related intents. Therefore the receivers must be registered programmatically.

Disable Short Button Press

Disabling short power button presses is done by handling the ACTION_SCREEN_OFF intent and kicking the screen back to life by acquiring a wake lock:

Источник