App Manager

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

StageNow - 2.10

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, app management generally requires the user to interact with a management UI presented on the device. For corporate scenarios involving management by an Enterprise Mobility Management (EMM) system (sometimes referred to as mobile device management, or MDM), user consent or approval might nto be desired as they potentially limit a company's ability to fully control the user apps installed on a device. AppMgr provides such control.

When considering the capabilities of AppMgr, it is important to understand the difference between System apps and User apps. System applications are built into the device and always by default. User applications are not built in, and must be installed before use. Some AppMgr functions apply only to System apps, some only to User apps, and some to both. Each function identifies the class of the app(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 pressing the HOME key
  • Turn On/Off the ability of an application to Launch (Whitelisting and Blacklisting)
  • Clear the Recent Application List
  • Clear an application's cache (which stores the app's temporary files)
  • Add/remove apps from Battery Optimization exemption list (see below)
  • Enable all GMS apps
  • Disable all GMS apps that are safe to disable
  • Enable/Disable access to application info

Battery Optimization

The App Manager allows one or more apps to be added to the Battery Optimization "exemption whitelist." While running, apps on this list prevent the device from entering Doze and App Standby power saving modes, thereby preserving their ability to continue functioning and/or providing services. Doze mode saves battery power by deferring background CPU and network activities when the device is idle. App Standby defers background network activity for apps with which the user has not recently interacted. By default, all non-system apps are subject to Doze and App Standby modes unless added to the whitelist.

For more information, refer to the Android Developer site.

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 in the table below).

Notes:

  • "Protected" Apps remain on the "Recent Apps" list after the list has been cleared using the "ClearRecentApps" Action.
    See Protected List Action parameter for more information.
  • Persistence of the DisableGMSApps Action MUST be accompanied by a bypass of the Android Setup Wizard to prevent unpredictable behavior.
    See Power Manager for more information.
  • Enable/Disable GMS Apps Action supported on SDM660-platform devices only.

Parm Name: Action

Option Name Description Note Requires
0 Do nothing This value (or the absence of this parm from the XML) will cause no change to applications on the device.

MX: 4.1+

1 Install Installs the user app contained within an .apk file in the specified path on the device. If the requested app cannot be installed, an error is returned in the Result XML document. Note- Attempts to install an app with the same Package Name as one already installed on the device, an error is returned in the Result XML. To replace an app already installed on the device with a different version with the same Package Name, use the Upgrade action (option 3).

OSX: 1.0+

MX: 4.2+

2 Uninstall Removes the User app with the specified Package Name from the device. If the requested app cannot be found or removed, an error is returned in the Result XML document. Note- When an app is removed, data stored in sandbox areas owned by that app also are removed. If the app requiring such data is reinstalled, the data must be recreated.

OSX: 1.0+

MX: 4.1+

3 Upgrade Upgrades the User app contained within an .apk file in the specified path with the same Package Name on the device. If the requested app cannot be found or upgraded, an error is returned in the Result XML document. To install an application that is not already installed on the device, use the "Install" action (option 1). Note- When an application is upgraded, the data for that application is maintained. Note- In devices running Android Jelly Bean, an Upgrade can replace any version of an app with any other version of the same app. In devices running Android KitKat or higher, an Upgrade can replace only apps with a numerically greater version number.

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 Android Launcher according to Android specifications. If no app with the specified Package Name is installed on the device, an error is returned in the Result XML document.

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 is returned in the Result XML document.

MX: 4.2+

Android API: 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 is returned in the Result XML document.

MX: 4.2+

Android API: 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).

MX: 4.2+

Android API: 16+

8 LaunchApplication Allows a System or User app to be launched by its visible Name rather than by its package name (not case-sensitive). 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 is returned in the Result XML document.

MX: 5.1+

Android API: 1+

9 BatteryOptimization Allows one or more apps to be added to or removed from the "Doze Mode exemption" list, which determines whether the device is allowed to enter a power saving mode while the app is running.

MX: 7.0+

Android API: 23+

10 ClearApplicationCache Erases the application cache, which stores an app's temporary files. This is the functional equivalent of pressing the "Clear Cache" button in the Android App Manager, accessed through the Settings panel.

MX: 8.0+

Android API: 24+

11 EnableGMSApps Enables all GMS applications and services on the device, reversing any prior Action(s) to disable them. Subsequent DisableApplication Actions are effective.

OSX: 8.1+

MX: 8.0+

Android API: 24+

12 DisableGMSApps Disables all GMS applications and services on the device (that are safe to disable) and removes their icons from the Android Launcher. Subsequent EnableApplication Actions are effective. See IMPORTANT notes, above.

OSX: 8.1+

MX: 8.0+

Android API: 24+

.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 only to Install or Upgrade a User app or to Upgrade a System app. Any application being installed from an .apk file is by definition a User Application since 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 or 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. A System application that has been upgraded is considered a User app, but will have the same permissions as the version it replaced, allowing the new version to perform the same operations as the original System app. If data is cleared and upgrades are removed from such an app, the app reverts to its original built-in version and is once again considered a System app.

Input value rules:

  • String from 1-255 characters containing the full path and name of device-resident .apk file. For example: /storage/sdcard1/Herald.apk

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(s) of one or more applications for the selected Action. Separate multiple Package Names using commas. Package Name(s) must be specified exactly, and can be acquired from the application developer, by extracting the Package Name from the .apk file or by finding it in the device.

Important: If a Package Name is specified incorrectly in a list, all names following that name are ignored.

Input value rules:

  • String from 1-255 characters containing a valid Package Name. For example: com.mycompany.mypackage.
  • Use commas to seperate multiple names

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: 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 from 1-255 characters
  • 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")
  • 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 Note Requires
0 Do nothing This value (or the absence of this parm from the XML) will cause no change to the Protected List.

OSX: 1.2+

MX: 4.2+

1 AddAppToProtectedList Adds the specified app package name to the Protected List.

OSX: 1.2+

MX: 4.2+

2 RemoveAppFromProtectedList Removes the specified app package name from the Protected List.

OSX: 1.2+

MX: 4.2+

3 ClearProtectedList Removes all app package names from the Protected List.

OSX: 1.2+

MX: 4.2+

Protected List Package Name

Used to specify the Package Name(s) of the application to add or remove from the Protected List. Separate multiple names using commas. Name(s) must be specified exactly, and can be acquired from the application developer, by extracting the Package Name from the .apk file or by finding it in the device.

Important: If a Package Name is specified incorrectly in a list, all names following that name are ignored.

Input value rules:

  • String from 1-255 characters containing a valid Package Name. For example: com.mycompany.mypackage.
  • Use commas to seperate multiple names

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 Note Requires
0 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+

1 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+

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

OSX: 4.2+

MX: 4.2+

Prevent Doze Mode

Used to specify one or more apps (by Package Name) to be added to the Doze Mode "exemption whitelist." While running, apps on this list prevent the device from entering power saving modes. To specify multiple Package Names, separate with commas. Package Name(s) must be specified exactly, and can be acquired from the application developer, by extracting the Package Name from the .apk file or by identifying it in the device. Doze Mode is controlled using the Power Manager CSP.

Important: If a name is specified incorrectly in a list, all names following that name are ignored.

Input value rules:

  • String containing one or more Package Names. For example: com.mycompany.mypackage.
  • Separate multiple names with commas

Shown if: The Action is "Battery Optimization"

Parm Name: AddPackageNames

Requires:

  • MX: 7.0+

Allow Doze Mode

Used to specify one or more apps (by Package Name) to be removed from the Doze Mode "exemption whitelist." Apps not on list do not prevent the device from entering power saving modes. To specify multiple Package Names, separate with commas. Package Name(s) must be specified exactly, and can be acquired from the application developer, by extracting the Package Name from the .apk file or by identifying it in the device.

Input value rules:

  • String containing one or more Package Names
  • Separate multiple names with 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>

Clear Application Cache

    
    <wap-provisioningdoc>
    <characteristic type="AppMgr" version="8.0" >
        <parm name="Action" value="ClearApplicationCache"/>
        <parm name="Package" value="com.symbol.tool.stagenow"/>
    </characteristic>
    </wap-provisioningdoc>