App Gallery Manager

EMDK for Xamarin - 2.5

Overview

AppMgr administers the user applications installed on the device. It can be used to programmatically Install, Uninstall, Upgrade and Turn On and 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 application to be the Default Launcher
  • Turn On and Off the ability of an application to Launch (Whitelisting and Blacklisting, respectively)
  • Clear the Recent Application List
  • Enable and Disable Access to Application Info

Action

Specify the application action to perform.

Parm Name: Action

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

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.

OSX: 1.0+

MX: 4.2+

2 Uninstall Causes a User application with the specified Package Name to be Uninstalled from the device. If for any reason the requested application cannot be uninstalled, 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 Uninstalled, data that is stored in sandbox areas owned by that application also will be removed. If the application requiring such data is later Installed again, the data will must be recreated.

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.

OSX: 1.0+

MX: 4.1+

4 Set as Default Launcher Sets the application with the specified Package Name as the new Default Launcher. The specified application 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.

OSX: 1.3+

MX: 4.1+

5 Enable Application Enables the System application with the specified Package Name, thereby allowing it to be launched. If no System application with the specified Package Name is built into the device, an error will be returned in the Result XML document.

MX: 4.2+

Android API Level: 1+

6 Disable Application Disables the System application with the specified Package Name, thereby preventing it from being launched. If no System application with the specified Package Name is built-into the device, an error will be returned in the Result XML document.

MX: 4.2+

Android API Level: 1+

7 Clear Recent Apps List Clears the Android Recent Applications List, which otherwise allows a user to see and launch recently used apps.

MX: 4.2+

Android API Level: 16+

8 Launch an Application Allows an application 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 using that icon or widget with its main activity. 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.

MX: 5.1+

Android API Level: 1+

Add Package Name(s)

Provide the path and name of the Android application APK file within the device file system that will be installed or upgraded.

Note: An APK file can be used only to Install a User application. Any application being installed from an APK file is not built into the device and is therefore by definition a User Application. However, an APK could be used to Upgrade either a System application or a User application. For an Upgrade, the APK file must be signed with the same developer certificate as the application it is trying to replace. If the APK file is not signed with the same developer certificate, an error will be returned in the Result XML document. This means that a System application can be replaced only using an APK file produced by the same developer that produced the built-in System application. If a System application is successfully Upgraded using an APK, the new version of the application is granted the same permissions as the version that was replaced. This allows the new version of the application to successfully perform the same operations as the original System application even though it is actually a User application. Since the new version is not built into the device, the device will revert to the old built-in version of the application whenever data is cleared.

Parm value input 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

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.

Provide the Package Name of the application for the application action.

Parm value input 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

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.

Provide the Name of the application for the application action.

Parm value input 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

The Protected List allows specified applications to be exempted from certain constraints imposed on applications when Multi-User Mode is enabled. Applications with Package Names on the Protected List will:

  • Be allowed to launch when no device user is logged in
  • Not be terminated when a device user logs out
  • Maintain a single copy of data for use by all users, even if Multi-User Data Separation is enabled

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.

Parm Name: ProtectedListAction

Option Name Description Requires
0 Do nothing This value (or the absence of this parm from the XML) will cause no changes to the Protected List.

OSX: 1.2+

MX: 4.2+

1 Add Application to Protected List Adds the Package Name of an application to the Protected List.

OSX: 1.2+

MX: 4.2+

2 Remove Application from Protected List Removes the Package Name of an application from the Protected List.

OSX: 1.2+

MX: 4.2+

3 Remove All Applications from Protected List Removes all Package Names from the Protected List.

OSX: 1.2+

MX: 4.2+

Protected List Package Name

Provide the Package Name of the application that should be Added to or Removed from the Protected List.

Parm value input 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 to App Info Action

The parm allows 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 or remove application data (Clear Data). A device user also might 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 parm is supported only on devices that are running the Kit Kat version of Android. This is because this parm depends on modifications made to the System Settings Menu application, and such modifications are found only on Kit Kat devices.

Parm Name: AccessAppInfoAction

Option Name Description 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 Enable Access to App Info for all applications Enables access to App Info of all applications on the device if access to the System Settings Menu application is enabled.

OSX: 4.2+

MX: 4.2+

2 Disable Access to App Info for all applications Disables access access to App Info for all application on the device.

OSX: 4.2+

MX: 4.2+

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>