DevAdmin Manager

Note: To display only the features present on a particular device, select one or more filters from the SmartDocs bar below.

EMDK For Xamarin - 3.0

Overview

The Device Administrator CSP (DevAdmin) controls which apps have administrative privileges, can access Android Device Admin APIs and how, when and whether the Screen-Lock is invoked.

Android defines some APIs as Device Administration APIs, as implemented within the DevicePolicyManager class. These APIs enable applications to perform tasks that can affect the security of the device. As such, they are restricted to specially approved "Device Administrator" applications. If an application is written to conform to the DeviceAdminReceiver model and is approved to become a Device Administrator, then it can use some or all of the Device Administration APIs.

In standard Android devices, an application that is written to conform to the DeviceAdminReceiver model must explicitly request the device user to approve it as a Device Administrator. This is based on the assumption that the device user is knowledgeable enough to make this determination. For a device that is owned and/or used by a single user, that assumption might be reasonable. For an Enterprise-owned device that might be shared among multiple device users, that assumption may be a poor one.

The DevAdmin provides direct access to certain device administration tasks and allows programmatic approval as a Device Administrator of applications written to conform to the DeviceAdminReceiver model without involving or notifying the device user. This allows an Enterprise to grant its own trusted applications access to the Device Administration APIs, thus enabling those applications to perform device administration tasks.

Main Functionality

  • Set Screen-Lock Timeout Interval
  • Set Screen Lock Type (or none)
  • Enable/Disable Installation of applications from Unknown sources
  • Enable/Disable Device Administrator approval for an application

Device Administration Action

Used to grant or deny approval as a Device Administrator from a qualifying application. To qualify, the app must be written to conform to the DeviceAdminReceiver model. All applications by default are initially denied approval as a Device Administrator and must be explicitly approved. Only an application that is currently installed and written to conform to the DeviceAdminReceiver model may be approved as a Device Administrator.

When an application is approved as a Device Administrator, it will be notified that it can begin using the Device Administration APIs. When Device Administrator approval is removed, the app is likewise notified that it must stop using the Device Administration APIs.

Note: The ability to grant or deny approval for an application using the DevAdmin does not prevent the device user from doing the same for an application using the System Settings panel. The effect of this parameter is the same as that of a device user going though System Settings. Access to the System Settings panel can be controlled with the UI Manager.

Parm Name: DevAdminAction

Option Name Description Note Requires
0 Do nothing This value (or the absence of this parm from the XML) will not make any change to whether any application is approved to be a Device Administrator; any previously selected setting will be retained.

OSX: 1.3+

MX: 4.3+

1 Turn On as Device Administrator Approves a specific application as a Device Administrator.

OSX: 1.3+

MX: 4.3+

2 Turn Off as Device Administrator Removes Device Administrator approval from a specific application.

OSX: 1.3+

MX: 4.3+

Device Admin Package Name

Used to specify the Package Name of an application to which to grant or deny Device Administrator privileges.

Note: The Package Name of the application must be known and specified. The Package Name can be acquired from the application developer, by looking up the Package Name on a device, or using developer tools to extract the Package Name from the APK file.

Parm value input rules:

  • String from 1 - 255 characters

Shown if: Device Administration Action is "Turn On as Device Administrator" or "Turn Off as Device Administrator"

Parm Name: DevAdminPkg

Requires:

  • OSX: 1.3+
  • MX: 4.3+

Device Admin Class Name

Used to specify the Class Name that will be added to or removed from the Device Admin list, which determines whether the application can access Android Device Admin APIs.

Note: The name of the class within the application that implements the DeviceAdminReceiver must be known and specified. This is not the same as the Activity class name required to launch the application and would likely need to be acquired from the application developer.

Parm value input rules:

  • String from 1 - 255 characters

Shown if: Device Administration Action is "Turn On as Device Administrator" or "Turn Off as Device Administrator"

Parm Name: DevAdminClass

Requires:

  • OSX: 1.3+
  • MX: 4.3+

Install App from Unknown Sources

Controls whether apps can be installed (on devices with or without GMS) from sources other than Google Play.

Android devices have a feature called the Unknown Sources Option that controls whether the device user is allowed to install applications (APK files) that originate from "unknown" sources, by which is meant "anywhere other than the Google Play Store." The primary purpose for this feature is to block "side loading" of APKs that may be risky since they did not go through the vetting process associated with posting applications on the Google Play Store.

For devices that have GMS (Google Mobile Services), the Android CDD (Compatibility Definition Document) requires that the Unknown Sources Option be turned off by default. That makes sense for such devices, since they have support for Google Play (which is part of GMS) and hence have a viable way for device users to load applications. Zebra Android devices that have GMS will all default the Unknown Sources Option off by default to comply with this requirement. The Unknown Sources Option can then be turned on to allow device users the option of side-loading applications as an alternative to using Google Play.

For devices that do not have GMS, turning off the Unknown Sources Option would prevent device users from loading applications at all, since they do not have support for Google Play. Zebra devices that do not have GMS will typically default the Unknown Sources Option on by default so device users will have at least some method to install applications. The Unknown Sources Option can then be turned off to disallow device users from loading applications at all.

Note: The Unknown Sources Option only affects whether device users are allowed to install applications. It does not have any effect on whether applications can be programmatically installed, such as using the AppMgr. The presumption is that any application that can be trusted to install other applications without involving or notifying the device user can be trusted to install only suitable applications and therefore whether those applications come from the Google Play Store or not is immaterial.

Parm Name: UnknownSourcesStatus

Option Name Description Note Requires
0 Do not change This value (or the absence of this parm from the XML) will not make any change to the Unknown Sources Option; any previously selected setting will be retained.

MX: 4.3+

Android API: 3+

1 Turn On Turns the Unknown Sources Option on, allowing the device user to install apps from sources other than Google Play.

MX: 4.3+

Android API: 3+

2 Turn Off Turns the Unknown Sources Option off, preventing the device user from installing apps from sources other than Google Play.

MX: 4.3+

Android API: 3+

Screen Lock Type

Controls whether a screen-lock will be invoked when the device powers up or user inactivity exceeds the Screen-Lock Timeout Interval parameter, and which Android lock screen will be displayed.

Note: On TC20/TC25 devices, available only when running Android 8.x Oreo and higher.

Parm Name: ScreenLockType

Option Name Description Note Requires
0 Do not change This value (or the absence of this parm from the XML) will cause no change to the Screen Lock Type; any previously selected setting will be retained.

OSX: 6.0+

MX: 6.0+

1 Swipe Causes the Swipe screen-lock to be displayed whenever the lock screen is invoked.

OSX: 6.0+

MX: 6.0+

2 Pattern Causes the Pattern screen-lock to be displayed whenever the lock screen is invoked.

OSX: 6.0+

MX: 6.0+

3 Pin Causes the numerical "Pin" screen-lock to be displayed whenever the lock screen is invoked.

OSX: 6.0+

MX: 6.0+

4 Password Causes the Password screen-lock to be displayed whenever the lock screen is invoked.

OSX: 6.0+

MX: 6.0+

5 None Prevents the display of any lock screen at any time.

OSX: 6.0+

MX: 6.0+

Screen-Lock Timeout Interval

Controls the length of time a device must remain inactive with the display screen off before a screen-lock is invoked.

Android supports two levels of inactivity, each controlled independently. The Display Screen Timeout, administered by the Display Manager, controls the length of time a device must remain inactive before the display screen is turned off. The Screen Lock Timeout interval (this parameter), controls how long the screen must remain off before a screen-lock will be invoked.

When the device screen is turned back on, manually by some sort of device user activity, or programmatically due to some device event, the result will depend on how long the device screen was off and the value set for the Screen Lock Timeout. If the display screen was off for less than the Screen Lock Timeout, then the screen will not be locked (and hence will not need to be unlocked by the device user). If the display screen was off for at least the Screen Lock Timeout, then the screen will be locked (and hence will need to be unlocked by the device user).

This behavior can be modified in two ways, based on other aspects of the device that may be configured. First, if no lock behavior is set for the device (e.g. no pin or password), then "unlocking" (if required) may require only a swipe, and not any actual data entry by the device user. Second, if the device is configured to lock automatically when the display screen is turned off by the power key, then a screen lock will always occur when the display screen is turned back on after being turned off via the power key, regardless of how much time the display screen was off.

Note: The Android display system supports a fixed set of interval values for the Screen-Lock Timeout as listed in the table below. This parameter is capable of configuring the timeout using only those supported values. Specifying a value that is less than the smallest value shown in the table or greater than the largest value will be ignored and generate an error in the Result XML document. However, specifying a value between two supported values will cause the closest value to the requested value to be selected, and generate no error in the Result XML document.

Parm Name: ScreenLockTimeoutInterval

Option Name Description Note Requires
0 Do not change This value (or the absence of this parm from the XML) will cause no change to the Screen Lock Timeout; any previously selected setting will be retained.

OSX: 1.3+

MX: 4.3+

1 Immediately after Display Timeout Causes the screen to be locked when the display screen is turned back on, regardless of how long the display screen was off.

OSX: 1.3+

MX: 4.3+

5 5 seconds after Display Timeout Causes the screen to be locked when the display screen is turned back on if the screen was off for at least 5 seconds.

OSX: 1.3+

MX: 4.3+

15 15 seconds after Display Timeout Causes the screen to be locked when the display screen is turned back on if the screen was off for at least 15 seconds.

OSX: 1.3+

MX: 4.3+

30 30 seconds after Display Timeout Causes the screen to be locked when the display screen is turned back on if the screen was off for at least 30 seconds.

OSX: 1.3+

MX: 4.3+

60 1 minute after Display Timeout Causes the screen to be locked when the display screen is turned back on if the screen was off for at least 1 minute.

OSX: 1.3+

MX: 4.3+

120 2 minutes after Display Timeout Causes the screen to be locked when the display screen is turned back on if the screen was off for at least 2 minutes.

OSX: 1.3+

MX: 4.3+

300 5 minutes after Display Timeout Causes the screen to be locked when the display screen is turned back on if the screen was off for at least 5 minutes.

OSX: 1.3+

MX: 4.3+

600 10 minutes after Display Timeout Causes the screen to be locked when the display screen is turned back on if the screen was off for at least 10 minutes.

OSX: 1.3+

MX: 4.3+

1800 30 minutes after Display Timeout Causes the screen to be locked when the display screen is turned back on if the screen was off for at least 30 minutes.

OSX: 1.3+

MX: 4.3+

Examples

Set the Screen to Lock to 1 Minute After the Display Times Out


<wap-provisioningdoc>
    <characteristic type="DevAdmin" version="4.3" >
        <parm name="ScreenLockTimeoutInterval" value="60"/>
    </characteristic>
</wap-provisioningdoc>

Allow Application Installs from Unknown Sources


<wap-provisioningdoc>
    <characteristic type="DevAdmin" version="4.3" >
        <parm name="UnknownSourcesStatus" value="1"/>
    </characteristic>
</wap-provisioningdoc>

Queries

Get Apps that are Active Device Admins

Input


<wap-provisioningdoc>
    <characteristic type="DevAdmin" version="4.3" >
        <characteristic-query type="AppAsDevAdmin"/>
    </characteristic>
</wap-provisioningdoc>

Output


<wap-provisioningdoc>
    <characteristic type="DevAdmin" version="4.3" >
        <characteristic type="AppAsDevAdmin">
            <parm name="DevAdminAction" value="1"/>
            <characteristic type="DevAdminDetails">
                <parm name="DevAdminPkg" value="PackageName1"/>
                <parm name="DevAdminClass" value="ClassName1"/>
            </characteristic>
        </characteristic>
    </characteristic>
    <characteristic type="DevAdmin" version="4.3" >
        <characteristic type="AppAsDevAdmin">
            <parm name="DevAdminAction" value="1"/>
            <characteristic type="DevAdminDetails">
                <parm name="DevAdminPkg" value="PackageName2"/>
                <parm name="DevAdminClass" value="ClassName2"/>
            </characteristic>
        </characteristic>
    </characteristic>
</wap-provisioningdoc>

Get Screen Lock Timeout Interval

Input


<wap-provisioningdoc>
    <characteristic type="DevAdmin">
        <parm-query name="ScreenLockTimeoutInterval"/>
    </characteristic>
</wap-provisioningdoc>

Output


<wap-provisioningdoc>
    <characteristic type="DevAdmin" version="4.3">
        <parm name="ScreenLockTimeoutInterval" value="1"/>
    </characteristic>
</wap-provisioningdoc>

Get Install Apps from Unknown Sources Status

Input


<wap-provisioningdoc>
    <characteristic type="DevAdmin">
        <parm-query name="UnknownSourcesStatus"/>
    </characteristic>
</wap-provisioningdoc>

Output


<wap-provisioningdoc>
    <characteristic type="DevAdmin" version="4.3">
        <parm name="UnknownSourcesStatus" value="1"/>
    </characteristic>
</wap-provisioningdoc>