Skip to main content
Version: 12 Dec 2024

Magic Leap Lock Task Service

If you need to enable a kiosk-style functionality on the Magic Leap 2 headset for displaying demos to multiple users, it's possible to do so via the Android Lock Task Mode. This mode allows you to pin or lock your application so that users cannot exit it by pressing the home button or launching other apps. This guide details how to interact with Magic Leap's built in Task Service using ADB (Android Debug Bridge) commands.

note

This service is intended to be used when the Magic Leap device is connected to a computer and configured via ADB commands executed through a command line interface (CLI) such as Terminal or Command Prompt.

Enabling Lock Task Service as Device Owner​

Before using the lock task features, you must designate the Lock Task Service as the device owner. This grants the service the necessary permissions to manage task-locking policies. Run the following ADB command in your CLI to set the service as the device owner:

adb shell dpm set-device-owner com.magicleap.locktaskservice/.LockTaskAdminReceiver

This command assigns the Lock Task Service administrative rights over the device, allowing it to enforce lock task policies.

Using Lock Task Service Intents​

The Lock Task Service supports various intents for enabling, managing, and debugging lock task mode. These intents allow you to add or remove applications from the whitelist, launch apps in lock task mode, and obtain state information for debugging. Use the following commands in your CLI to perform these tasks.

Whitelist and Launch Applications in Lock Task Mode​

Use com.magicleap.locktaskservice.EXTRA_ADD_AND_LAUNCH to add and launch a package or a component in lock task mode. This is the last extra that is checked by the service. The value of this extra should be either the package name or the component name of the app that you want to launch. A component name is composed of the package name and the class name of the activity, separated by a slash. Note that non-whitelisted activities cannot be started while lock task mode is enabled.

info

For example, to start a Unity application called com.magicleap.unity.examples and an activity called com.unity3d.player.UnityPlayerActivity in the same package, you would use:

com.magicleap.unity.examples/com.unity3d.player.UnityPlayerActivity

adb shell am start-service -n com.magicleap.locktaskservice/.LockTaskService -e "com.magicleap.locktaskservice.EXTRA_ADD_AND_LAUNCH" "your.package.name/yourActivityName"

Removing a Whitelisted Application​

To remove an application from lock task mode, use com.magicleap.locktaskservice.EXTRA_REMOVE_PACKAGE. The value of this extra should be the package name of the app that you want to remove. You cannot remove individual components of a package, only the entire package.

adb shell am start-service -n com.magicleap.locktaskservice/.LockTaskService -e "com.magicleap.locktaskservice.EXTRA_REMOVE_PACKAGE" "your.package.name"

Clearing All Locked Tasks​

To exit lock task mode for all applications, use com.magicleap.locktaskservice.EXTRA_REMOVE_ALL_PACKAGES. When this extra is detected, it takes priority over others, and no further extras are processed. The value of this extra is ignored.

adb shell am start-service -n com.magicleap.locktaskservice/.LockTaskService -e "com.magicleap.locktaskservice.EXTRA_REMOVE_ALL_PACKAGES" 0

Debugging State Information​

Use com.magicleap.locktaskservice.EXTRA_DUMP_STATE to retrieve additional information from the service. This extra is useful for debugging. It dumps state information to logcat, such as the current lock task mode, the whitelisted packages, and the active tasks.

adb shell am start-service -n com.magicleap.locktaskservice/.LockTaskService -e "com.magicleap.locktaskservice.EXTRA_DUMP_STATE" 0

Remove Lock Task Service as MDM provider​

If you need to enroll the device with a Mobile Device Management (MDM) provider, you must first remove the Lock Task Service as the device owner. Follow these steps to disable lock task mode and clear any configurations set by the service:

  1. Remove the service as the admin receiver:
adb shell dpm remove-active-admin com.magicleap.locktaskservice/.LockTaskAdminReceiver
  1. Perform a factory reset to ensure a clean state for MDM enrollment. This step will erase all user data and settings:
adb reboot bootloader && fastboot erase userdata && fastboot reboot