Dedicated devices

As an IT admin, you can configure Android 6.0 Marshmallow and later devices as dedicated devices (previously called corporate-owned, single-use, or COSU devices). These are Android devices used for a single purpose, such as digital signage, ticket printing, point of sale, or inventory management. To use Android devices as dedicated devices, you need to develop Android apps that your customers can manage.

Your customers can configure dedicated devices:

To lock a single application to the screen, and hide the Home and Recents buttons to prevent users from escaping the app.
To allow multiple applications to appear on the screen, such as a library kiosk with a catalog app and web browser.

App pinning vs. lock task mode

Android 5.0 Lollipop introduced two new ways to configure Android devices for a single purpose:

With app pinning, the device user can temporarily pin specific apps to the screen.
With lock task mode, a user can’t escape the app and the Home and Recents buttons are hidden. Additionally, lock task mode gives the IT admin a more robust way to manage dedicated devices, as discussed below.

This graphic compares the features of app pinning and lock task mode:

Figure 1. Comparing the features of app pinning in Lollipop vs. Lock task mode in Marshmallow and later

In Lollipop, you can pin a single application to cover the full screen, but only apps whitelisted by the device policy controller (DPC) can be locked.

How to use LockTask mode

To use LockTask mode, and the APIs that manage dedicated devices, there must be a device owner application installed on the device. Device owners are a type of device policy controller (DPC) that manages the whole device. For more information about DPCs, see the EMM Developer’s Overview.

If you’re creating a new dedicated device app, we recommend you develop it for Marshmallow or later, which includes the following dedicated device features:

Controls system updates
Sets status and menu bar visibility
Disables screen lock and sleep functions
Permits switching between apps while staying in lock task mode
Prevents restarting in safe mode

Note: If you develop dedicated device features targeted for Marshmallow devices, your app can still be compatible with prior versions of Android.

Additional dedicated device management features launched with Marshmallow make it easier to develop and deploy Android devices as a single-use device. If you want to enforce server-side managed configurations or server-side profile policy controls, you need to use an EMM or make your application a DPC. Follow the instructions below as you create your application.

Manage dedicated devices

There are three different ways to manage dedicated devices:

Use a third-party enterprise mobility management (EMM) solution: Using an EMM, all you need to do is set up lock task mode. For instructions, skip to the next section, Solutions managed by a third-party EMM.
Use the Android Management API: Call this cloud API to apply device and app-level management policies, as well as lock down the usage of a device to a single app or small set of apps. For instructions, skip to Use the Android Management API.
Advanced setup—Create your own DPC app: This requires more work and is intended for an advanced developer audience. With this option, you’ll need to set up the device so that you can manage it, set up APIs, and set up a DPC app and test it. For instructions, skip to Create your own DPC app.

Solutions managed by a third-party EMM

In this section, you’ll need to do a small amount of development to have your device work with a third-party EMM.

Using startLockTask()

If you need to add dedicated device functionality to an existing app, make sure that the customer’s EMM supports lockTaskMode.

The device owner must include your app’s package(s) in setLockTaskPackages

Sets the packages that can enter into lock task mode
Needs to be set by the EMM
You can call isLockTaskPermitted to verify that your package has been whitelisted by setLockTaskPackages.

Your activity calls startLockTask()

Requests to lock the user into the current task
Prevents launching other apps, settings, and the Home button

To exit, your activity must call stopLockTask()

Can only be called on an activity that’s previously called startLockTask()
Should be called when the app is user-facing between onResume() and onPause()

Starting from Marshmallow, if your app is whitelisted by an EMM using setLockTaskPackages, your activities can automatically start lock task mode when the app is launched.

Set the lockTaskMode attribute

The lockTaskMode attribute allows you to define your app’s lock task mode behavior in the AndroidManifest.xml file:

If you set lockTaskMode to if_whitelisted, you don’t need to call startLockTask(), and the app automatically enters into lock task mode.
System apps and privileged apps can also set lockTaskMode to always. This setting causes tasks (rooted at your activity) to always launch into lock task mode. Non-privileged apps are treated as normal.
The default value of the lockTaskMode attribute is normal. When this attribute is set to normal, tasks don’t launch into lockTaskMode, unless startLockTask() is called. To call startLockTask(), applications still need to be whitelisted using setLockTaskPackages, otherwise, the user sees a dialog to approve entering pinned mode.

To have your activity automatically enter lockTaskMode, change the value of this attribute to if_whitelisted. Doing so causes your app to behave in this manner:

If your app isn’t whitelisted for lockTaskMode, it behaves as normal.
If your app is a system or privileged app, and it’s whitelisted, lockTaskMode automatically starts when the app is launched.

Example XML as follows:

<activity android:name=".MainActivity" android:lockTaskMode="if_whitelisted">

Given either of these options, you still need to create a mechanism for calling stopLockTask() so that users can exit lockTaskMode.

Use the Android Management API

After adding the dedicated device functionality to an existing app, use the cloud-based Android Management API to configure dedicated devices the app's installed on.

Follow the instructions in the previous section, Solutions managed by a third-party EMM.
Read Quickstart to get started with the Android Management API.
Follow the Android Management API advice in Recommended app policy settings, for kiosk apps. Ensure that lockTaskAllowed for your app policy is set to true if your app supports lock task mode.

Advanced setup—create your own DPC app

To manage applications on a dedicated device, you need a DPC running as device owner to set several policies on the device.

Note: This setup is advanced, and requires a thorough understanding of the EMM concepts described in the EMM developer overview. For more information about building a DPC, see Provision Customer Devices.

To create a DPC app that can manage dedicated device configuration, the DPC needs to:

Provision the device into device owner mode. We recommend that you support provisioning with near field communication (NFC) bump. For more information, see Device Owner Provisioning via NFC.
Use the following APIs:
- Keep devices from locking with the keyguard using setKeyguardDisabled()
- Disable the status bar using setStatusBarDisabled()
- Keep a device’s screen on while plugged in via STAY_ON_WHILE_PLUGGED_IN
- Set default user restriction for managed configurations via addUserRestriction()
- Set system update policies using setSystemUpdatePolicy()
- Ensure your app is launched on reboot by setting it as the default launcher

Here’s an example of how to implement an activity that starts lock task mode and implements the relevant dedicated device management APIs:

Kotlin

private const val Battery_PLUGGED_ANY = (BatteryManager.BATTERY_PLUGGED_AC
        or BatteryManager.BATTERY_PLUGGED_USB
        or BatteryManager.BATTERY_PLUGGED_WIRELESS).toString()

private const val DONT_STAY_ON = "0"

class CosuActivity : Activity() {

    private lateinit var mAdminComponentName: ComponentName
    private lateinit var mDevicePolicyManager: DevicePolicyManager

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        mAdminComponentName = DeviceAdminReceiver().getWho(this)
        mDevicePolicyManager =
                getSystemService(Context.DEVICE_POLICY_SERVICE) as DevicePolicyManager
        setDefaultCosuPolicies(true)
    }

    override fun onStart() {
        super.onStart()

        // start lock task mode if it's not already active
        (getSystemService(Context.ACTIVITY_SERVICE) as ActivityManager).also { am ->
            // ActivityManager.getLockTaskModeState api is not available in pre-M.
            if (Build.VERSION.SDK_INT < Build.VERSION_CODES.M) {
                if (!am.isInLockTaskMode) {
                    startLockTask()
                }
            } else {
                if (am.lockTaskModeState == ActivityManager.LOCK_TASK_MODE_NONE) {
                    startLockTask()
                }
            }
        }
    }

    private fun setDefaultCosuPolicies(active: Boolean) {
        // set user restrictions
        setUserRestriction(UserManager.DISALLOW_SAFE_BOOT, active)
        setUserRestriction(UserManager.DISALLOW_FACTORY_RESET, active)
        setUserRestriction(UserManager.DISALLOW_ADD_USER, active)
        setUserRestriction(UserManager.DISALLOW_MOUNT_PHYSICAL_MEDIA, active)
        setUserRestriction(UserManager.DISALLOW_ADJUST_VOLUME, active)

        // disable keyguard and status bar
        mDevicePolicyManager.apply {
            setKeyguardDisabled(mAdminComponentName, active)
            setStatusBarDisabled(mAdminComponentName, active)
        }

        // enable STAY_ON_WHILE_PLUGGED_IN
        enableStayOnWhilePluggedIn(active)

        // set System Update policy

        if (active) {
            mDevicePolicyManager.setSystemUpdatePolicy(
                    mAdminComponentName,
                    SystemUpdatePolicy.createWindowedInstallPolicy(60, 120)
            )
        } else {
            mDevicePolicyManager.setSystemUpdatePolicy(mAdminComponentName, null)
        }

        // set this Activity as a lock task package

        mDevicePolicyManager.setLockTaskPackages(
                mAdminComponentName,
                if (active) arrayOf(packageName) else emptyArray()
        )

        val intentFilter = IntentFilter(Intent.ACTION_MAIN).apply {
            addCategory(Intent.CATEGORY_HOME)
            addCategory(Intent.CATEGORY_DEFAULT)
        }

        if (active) {
            // set Cosu activity as home intent receiver so that it is started
            // on reboot
            mDevicePolicyManager.addPersistentPreferredActivity(
                    mAdminComponentName,
                    intentFilter,
                    ComponentName(packageName, CosuActivity::class.java.name)
            )
        } else {
            mDevicePolicyManager.clearPackagePersistentPreferredActivities(
                    mAdminComponentName,
                    packageName
            )
        }
    }

    private fun setUserRestriction(restriction: String, disallow: Boolean) {
        if (disallow) {
            mDevicePolicyManager.addUserRestriction(mAdminComponentName, restriction)
        } else {
            mDevicePolicyManager.clearUserRestriction(mAdminComponentName, restriction)
        }
    }

    private fun enableStayOnWhilePluggedIn(enabled: Boolean) {
        if (enabled) {
            mDevicePolicyManager.setGlobalSetting(
                    mAdminComponentName,
                    Settings.Global.STAY_ON_WHILE_PLUGGED_IN,
                    Battery_PLUGGED_ANY
            )
        } else {
            mDevicePolicyManager.setGlobalSetting(
                    mAdminComponentName,
                    Settings.Global.STAY_ON_WHILE_PLUGGED_IN, DONT_STAY_ON
            )
        }
    }

    // TODO: Implement the rest of the Activity
}

Java

public class CosuActivity extends Activity {

    private ComponentName mAdminComponentName;
    private DevicePolicyManager mDevicePolicyManager;
    private PackageManager mPackageManager;
    private static final String Battery_PLUGGED_ANY = Integer.toString(
            BatteryManager.BATTERY_PLUGGED_AC |
            BatteryManager.BATTERY_PLUGGED_USB |
            BatteryManager.BATTERY_PLUGGED_WIRELESS);

    private static final String DONT_STAY_ON = "0";

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        mAdminComponentName = DeviceAdminReceiver().getWho(this);
        mDevicePolicyManager = (DevicePolicyManager) getSystemService(
                Context.DEVICE_POLICY_SERVICE);
        mPackageManager = getPackageManager();
        setDefaultCosuPolicies(true);
    }

    @Override
    protected void onStart() {
        super.onStart();

        // start lock task mode if it's not already active
        ActivityManager am = (ActivityManager) getSystemService(
                Context.ACTIVITY_SERVICE);
        // ActivityManager.getLockTaskModeState api is not available in pre-M.
        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.M) {
            if (!am.isInLockTaskMode()) {
                startLockTask();
            }
        } else {
            if (am.getLockTaskModeState() ==
                    ActivityManager.LOCK_TASK_MODE_NONE) {
                startLockTask();
            }
        }
    }

    private void setDefaultCosuPolicies(boolean active) {
        // set user restrictions
        setUserRestriction(UserManager.DISALLOW_SAFE_BOOT, active);
        setUserRestriction(UserManager.DISALLOW_FACTORY_RESET, active);
        setUserRestriction(UserManager.DISALLOW_ADD_USER, active);
        setUserRestriction(UserManager.DISALLOW_MOUNT_PHYSICAL_MEDIA, active);
        setUserRestriction(UserManager.DISALLOW_ADJUST_VOLUME, active);

        // disable keyguard and status bar
        mDevicePolicyManager.setKeyguardDisabled(mAdminComponentName, active);
        mDevicePolicyManager.setStatusBarDisabled(mAdminComponentName, active);

        // enable STAY_ON_WHILE_PLUGGED_IN
        enableStayOnWhilePluggedIn(active);

        // set System Update policy

        if (active){
            mDevicePolicyManager.setSystemUpdatePolicy(mAdminComponentName,
                    SystemUpdatePolicy.createWindowedInstallPolicy(60,120));
        } else {
            DevicePolicyManager.setSystemUpdatePolicy(mAdminComponentName, null);
        }

        // set this Activity as a lock task package

        mDevicePolicyManager.setLockTaskPackages(mAdminComponentName,
                active ? new String[]{getPackageName()} : new String[]{});

        IntentFilter intentFilter = new IntentFilter(Intent.ACTION_MAIN);
        intentFilter.addCategory(Intent.CATEGORY_HOME);
        intentFilter.addCategory(Intent.CATEGORY_DEFAULT);

        if (active) {
            // set dedicated device activity as home intent receiver so that it is started
            // on reboot
            mDevicePolicyManager.addPersistentPreferredActivity(
                    mAdminComponentName, intentFilter, new ComponentName(
                            getPackageName(), dedicated deviceActivity.class.getName()));
        } else {
            mDevicePolicyManager.clearPackagePersistentPreferredActivities(
                    mAdminComponentName, getPackageName());
        }
    }

    private void setUserRestriction(String restriction, boolean disallow) {
        if (disallow) {
            mDevicePolicyManager.addUserRestriction(mAdminComponentName,
                    restriction);
        } else {
            mDevicePolicyManager.clearUserRestriction(mAdminComponentName,
                    restriction);
        }
    }

    private void enableStayOnWhilePluggedIn(boolean enabled) {
        if (enabled) {
            mDevicePolicyManager.setGlobalSetting(
                    mAdminComponentName,
                    Settings.Global.STAY_ON_WHILE_PLUGGED_IN,
                    Battery_PLUGGED_ANY);
        } else {
            mDevicePolicyManager.setGlobalSetting(
                    mAdminComponentName,
                    Settings.Global.STAY_ON_WHILE_PLUGGED_IN, DONT_STAY_ON);
        }
    }

    // TODO: Implement the rest of the Activity
}

Develop a test plan for dedicated device

If you’re planning to support a third-party EMM, develop an end-to-end testing plan utilizing the EMM’s app. We also provide testing resources, which you can use to create your own Test Device Policy Client (Test DPC):

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.

Last updated September 27, 2018.