App Manager

Stagenow - 2.5

Overview

Application Manager (AppMgr) administers the user applications on the device. It can be used to programmatically install, uninstall, upgrade and turn on (or off) the ability to launch an application, all with no need for user interaction. AppMgr also can designate an application as the Default Launcher (invoked when pressing the HOME Key), and can perform other tasks related to the management of applications.

On consumer Android devices, application management generally requires a device user to interact with a management UI presented on the device. Scenarios in which a device is being managed by an MDM often require the MDM to tightly control which user applications are installed without user consent or approval. This enables an MDM to take full control of user applications installed on the device.

When considering the capabilities of AppMgr, it is important to understand that applications can be divided into two classes: System applications and User applications. System applications are built into the device and hence are always installed. User applications are not built in, and hence must be installed onto a device before they can be used. Some AppMgr functions apply only to System applications, some only to User applications, and some to both. Each function will identify the class of the application(s) to which it applies.

Main Functionality

Install, Uninstall and Upgrade User applications (with no device user involvement)
Set an app to be launched by the HOME key
Turn On and Off the ability of an application to Launch (Whitelisting and Blacklisting, respectively)
Clear the Recent Application List
Specify one or more apps for Battery Optimization
Enable and Disable Access to Application Info

Action

Used to specify the action to perform on an application or app-related setting. Actions can apply only to System apps, only to User apps, or to both (as noted below). Note: "Protected" Apps remain on the Recent Apps list after it has been cleared using the "ClearRecentApps" Action. See Protected List Action parameter for more information.

Parm Name: Action

Option	Name	Description	Device Group	Requires
0	Do nothing	This value (or the absence of this parm from the XML) will cause no change to applications on the device.	All	MX: 4.1+
1	Install	Causes a User application contained within an .apk file in the specified path on the device to be Installed on the device. If for any reason the requested application cannot be installed, an error will be returned in the Result XML document. Note- If an attempt is made to install an application with the same Package Name as an application that is already installed on the device, an error will be returned in the Result XML document. To replace an application that is already installed on the device with a different version with the same Package Name, use the value Upgrade instead.	All	OSX: 1.0+ MX: 4.2+
2	Uninstall	Causes a User application with the specified Package Name to be removed from the device. If for any reason the requested application cannot be removed, an error will be returned in the Result XML document. Note- If no User application with the specified Package Name is installed on the device, an error will be returned in the Result XML document. Note- When an application is removed, data that is stored in sandbox areas owned by that application also will be removed. If the application requiring such data is reinstalled, the data must be recreated.	All	OSX: 1.0+ MX: 4.1+
3	Upgrade	Causes a User application contained within an .apk file in the specified path on the device to Upgrade the application with the same Package Name that is already on the device. If for any reason the requested application cannot be upgraded, an error will be returned in the Result XML document. Note- If an attempt is made to upgrade an application with a Package Name that does not match any Package Names present on the device, an error will be returned in the Result XML document. To install an application that is not already installed on the device, use the value "Install" instead. Note- When an application is upgraded, the data for that application is maintained. This allows the new version of the application to access (and possibly convert) data created by the old version. Note- In devices running the Jelly Bean version of Android, an Upgrade can replace any version of an application with any other version of the same application. However, in devices running the KitKat or higher version of Android, an Upgrade can only replace an application with a higher (numerically greater) version of the same application. This change was made to reduce issues involving older versions of an application that were unable to understand data produced by a newer version.	All	OSX: 1.0+ MX: 4.1+
4	SetDefaultLauncher	Sets a System or User app with the specified Package Name as the new Default Launcher. The specified app must already be installed on the device and generally should be designed to be a Launcher according to the relevant Android specifications. If no application with the specified Package Name is installed on the device, an error will be returned in the Result XML document.	All	OSX: 1.3+ MX: 4.1+
5	EnableApplication	Enables the System app with the specified Package Name to be launched. If the Package Name does not exist on the device, an error will be returned in the Result XML document.	All	MX: 4.2+ Android API Level: 1+
6	DisableApplication	Prevents the System app with the specified Package Name from being launched. If Package Name does not exist on the device, an error will be returned in the Result XML document.	All	MX: 4.2+ Android API Level: 1+
7	ClearRecentApps	Clears the Android Recent Applications List, which otherwise would allow a user to see and launch recently used apps (Protected Apps excluded. See Note above).	All	MX: 4.2+ Android API Level: 16+
8	LaunchApplication	Allows a System or User app to be launched by its visible Name rather than by its package name. This refers to the app name as it appears in Launcher, App Drawer, Application Manager or app_name field of the strings.xml file (i.e. "Calculator"). To use this value, the app and its icon or widget must be visible in the Launcher screen and launchable with its main activity using that icon or widget. If the app is not present, does not have an icon or widget, cannot be launched using its main activity or contains only services and receivers, an error will be returned in the Result XML document. Not case sensitive.	A	MX: 5.1+ Android API Level: 1+
9	BatteryOptimization	Allows one or more apps to be designated for Battery Optimization.	A	MX: 7.0+ Android API Level: 23+

.apk Name

Used to specify the path and file name of the Android .apk file within the device file system from which to perform an app installation or upgrade.

Important:
An .apk file can be used to Install or Update a User app or to Update a System app. Any application being installed from an .apk file is by definition a User Application because it was not built into the device. For an Upgrade, the .apk file must be signed with the same developer certificate as the application it is intended to upgrade. If it's not, an error will be returned in the Result XML document.

A System application can be upgraded using only an .apk file produced by the same developer that produced the built-in System application. An System application that has been updated is considered a User app, but will have the same permissions as the version it replaced. This allows the new version to perform the same operations as the original System app. If data is cleared and updates are removed from such an app, it reverts to its original built-in version and is once again considered a System app.

Input value rules:

String containing the full path and name of device-resident .apk. For example: /storage/sdcard1/Herald.apk
The minimum length is 1 character; the maximum length is 255 characters

Shown if: The Action is "Install" or "Upgrade"

Parm Name: APK

Requires:

OSX: 1.0+

MX: 4.2+

Package Name

Used to specify the Package Name of the application for the selected Action.

Note: To perform the above listed Actions on an application, the Package Name of that 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.

Input value rules:

String containing the valid name of the package. For example: com.mycompany.mypackage
String containing the Name of the application as it appears in the Launcher, App Drawer, Application Manager or app_name field of the strings.xml file (i.e. "Calculator")
The minimum length is 1 character; the maximum length is 255 characters
Package Names must be separated by commas

Shown if: The Action is "Uninstall" or "Set as Default Launcher" or "Enable Application" or "Disable Application"

Parm Name: Package

Requires:

OSX: 1.0,1.3+

MX: 4.2+

Android API Level: 1+

Application Name

Used to specify the Name of the application for the selected Action.

Note: To perform the above listed Actions on an application, the Name of that application can be specified instead of the Package Name. The Name is defined as the name that accompanies the application icon in the Android Launcher, App Drawer or Application Manager. This name also is specified in the app_name field of the strings.xml file.

Input value rules:

String containing the Name of the application as it appears in the Launcher, App Drawer, Application Manager or app_name field of the strings.xml file (i.e. "Calculator")
The minimum length is 1 character and the maximum length is 255 characters
The application names are not case sensitive

Shown if: The Action is "Launch an application"

Parm Name: ApplicationName

Requires:

MX: 5.1+

Protected List Action

Used to add or remove apps from the Protected List, which allows apps to be exempted from certain constraints imposed when Multi-User Mode is enabled.

Note: Protected apps remain on the Recent Apps list after it has been cleared using the "ClearRecentApps" Action.

Applications with Package Names on the Protected List are allowed to:

Launch when no device user is logged in
Remain running when a device user logs out
Maintain a single copy of data accessible by all users, even if Multi-User Data Separation is enabled
Remain on the Recent Apps list after it has been cleared

Note: Multi-User Mode is supported on all Zebra Android devices that support Zebra MX functionality, but the AccessMgr cannot currently enable it. Enabling Multi-User Mode currently is done using unsupported tools or mechanisms that might not scale to large deployments. For this reason, the ability to use the AppMgr to manage the Protected List provides limited benefit.

Shown if: The Action is NOT "Battery Optimization"

Parm Name: ProtectedListAction

Option	Name	Description	Device Group	Requires
0	Do nothing	This value (or the absence of this parm from the XML) will cause no change to the Protected List.	A	OSX: 1.2+ MX: 4.2+
1	AddAppToProtectedList	Adds the specified app package name to the Protected List.	A	OSX: 1.2+ MX: 4.2+
2	RemoveAppFromProtectedList	Removes the specified app package name from the Protected List.	A	OSX: 1.2+ MX: 4.2+
3	ClearProtectedList	Removes all app package names from the Protected List.	A	OSX: 1.2+ MX: 4.2+

Protected List Package Name

Used to specify the Package Name of the application to add or remove from the Protected List.

Input value rules:

String containing the valid name of the package. For example: com.mycompany.mypackage
The minimum length is 1 character; the maximum length is 255 characters
Package names must be separated by commas

Shown if: The Protected List Action is "Add Application to Protected List" or "Remove Application from Protected List"

Parm Name: ProtectedListPackage

Requires:

OSX: 1.2+

MX: 4.2+

Access App Info

Used to allow blocking of access to App Info for all applications without blocking access to other parts of the System Settings Menu. By disabling App Info, the user can be prevented from using App Info to interfere with the configured set of installed applications.

Since the AppMgr can control which applications are installed, it may be of concern that a device user can use the App Info section of the in-device System Settings Menu to impact an installed application. For example, a device user might terminate (Force Stop) an application, remove application data (Clear Data), or eveb Uninstall the application completely. If an MDM is being used to control the set of installed applications on a device, such activities by a device user might be undesirable.

Compounding the issue, the App Info can be reached from several places in the device UI other than the System Settings Menu. For example, App Info can be reached from the Android Recent Applications List or from a notification related to the application in the Android Notification Area.

To prevent device users from using App Info to alter the configured set of installed applications, it may be desirable to prevent the device user from accessing App Info altogether. Of course, AppMgr can be used to disable launching of the System Settings Menu application, which would prevent access to App Info. But that also would prevent access to all other aspects of the System Settings Menu. A more targeted approach would be to block only App Info.

Note: This feature is supported only on devices running Android Kit Kat.

Shown if: The Action is NOT "Battery Optimization"

Parm Name: AccessAppInfoAction

Option	Name	Description	Device Group	Requires
0	Do nothing	This value (or the absence of this parm from the XML) will cause no changes to be made.	A	OSX: 4.2+ MX: 4.2+
1	EnableAccessAllInfo	Enables access to App Info for all applications on the device if access to the System Settings Menu application is enabled.	A	OSX: 4.2+ MX: 4.2+
2	DisableAccessAllInfo	Disables access access to App Info for all application on the device.	A	OSX: 4.2+ MX: 4.2+

Option

Name

Description

Device Group

Requires

Do nothing

This value (or the absence of this parm from the XML) will cause no changes to be made.

OSX: 4.2+

MX: 4.2+

EnableAccessAllInfo

Enables access to App Info for all applications on the device if access to the System Settings Menu application is enabled.

OSX: 4.2+

MX: 4.2+

DisableAccessAllInfo

Disables access access to App Info for all application on the device.

OSX: 4.2+

MX: 4.2+

Battery Optimization Add Apps

Used to specify one or more Package Names of apps on which to apply Battery Optimization.

Input value rules:

String containing one or more Package Names
Multiple names must be separated by commas

Shown if: The Action is "Battery Optimization"

Parm Name: AddPackageNames

Requires:

MX: 7.0+

Battery Optimization Remove Apps

Used to specify one or more Package Names of apps from which to remove Battery Optimization.

Input value rules:

String containing one or more Package Names
Multiple names must be separated by commas

Shown if: The Action is "Battery Optimization"

Parm Name: RemovePackageNames

Requires:

MX: 7.0+

Examples

Install An Application


<!-- Silently install Clock.apk from the /enterprise/usr/persist folder -->
<wap-provisioningdoc>
    <characteristic version="4.2" type="AppMgr">
        <parm name="Action" value="Install" />
        <parm name="APK" value="/enterprise/usr/persist/Clock.apk" />
    </characteristic>
</wap-provisioningdoc>

Upgrade An Application


<!-- Silently upgrade Clock.apk from the /enterprise/usr/persist folder -->
<wap-provisioningdoc>
    <characteristic type="AppMgr" version="4.2" >
        <parm name="Action" value="Upgrade"/>
        <parm name="APK" value="/enterprise/usr/persist/Clock.apk"/>
    </characteristic>
</wap-provisioningdoc>

Disable An Application


<wap-provisioningdoc>
    <characteristic version="4.2" type="AppMgr">
        <parm name="Action" value="DisableApplication" />
        <parm name="Package" value="com.mypackagename" />
    </characteristic>
</wap-provisioningdoc>

Uninstall An Application


<wap-provisioningdoc>
    <characteristic version="4.2" type="AppMgr">
        <parm name="Action" value="Uninstall" />
        <parm name="Package" value="com.packagename" />
    </characteristic>
</wap-provisioningdoc>

Start An Application After Installing it


<wap-provisioningdoc>
    <characteristic version="4.2" type="AppMgr">
        <parm name="Action" value="Install" />
        <parm name="APK" value="/sdcard/myapp.apk" />
    </characteristic>
    <characteristic version="4.3" type="Intent">
        <parm name="Action" value="StartActivity" />
        <parm name="ActionName" value="android.intent.action.MAIN" />
        <parm name="Package" value="com.mypackage" />
        <parm name="Class" value="com.mypackage.myactivity" />
    </characteristic>
</wap-provisioningdoc>

Add apps to Battery Optimization list

    
    <wap-provisioningdoc>
    <characteristic type="AppMgr" version="7.0" >
        <parm name="Action" value="BatteryOptimization"/>
        <parm name="AddPackageNames" value="com.example.android.deviceowner, com.symbol.software.filexpa"/>
    </characteristic>
    </wap-provisioningdoc>

    // Response from AppMgr CSP on success: 

    <wap-provisioningdoc>
    <characteristic type="AppMgr" version="7.0" >
        <parm name="Action" value="BatteryOptimization"/>
        <parm name="AddPackageNames" value="com.example.android.deviceowner, com.symbol.software.filexpa"/>
    </characteristic>
    </wap-provisioningdoc>

Remove apps from Battery Optimization list

    
    <wap-provisioningdoc>
    <characteristic type="AppMgr" version="7.0" >
        <parm name="Action" value="BatteryOptimization"/>
        <parm name="RemovePackageNames" value="com.example.android.deviceowner, com.symbol.software.filexpa"/>
    </characteristic>
    </wap-provisioningdoc>

    // Response from AppMgr CSP on success: 

    <wap-provisioningdoc>
    <characteristic type="AppMgr" version="7.0" >
        <parm name="Action" value="BatteryOptimization"/>
        <parm name="RemovePackageNames" value="com.example.android.deviceowner, com.symbol.software.filexpa"/>
    </characteristic>
    </wap-provisioningdoc>