EHS Advanced Settings

Enterprise Home Screen 2.3

Overview

This guide assumes a basic knowledge of Enterprise Home Screen and its capabilities and essential workings. For those not familiar with Zebra's free security tool for its Android devices, please refer to the About and Setup pages before continuing with this guide. Refer to the Special Features Guide for information about Kiosk Mode, Secure Mode and other special EHS features.

The behavior of Enterprise Home Screen is controlled entirely through enterprisehomescreen.xml, an easy-to-read file that can be modified with any text editor. A default version of the file contains many common device security settings plus a few standard apps, and is part of every EHS installation. In many instances, all that's needed to begin using EHS is to add an organization's own applications and to apply its preferred security and display settings.

This guide describes the how to add apps and configure settings using the config file alone (if the setting also can be configured through the GUI, a screenshot is shown). It details the interaction between EHS and the config file, and provides instructions for accessing and customizing the file for a company's specific requirements, and for deploying the settings to device(s). A detailed analysis of the config file follows, with explanations of each of the parameters and examples of how to configure them.

Note: Many of the capabilities of EHS can be accomplished manually on the device, programmatically through EMDK or remotely using StageNow or a third-party mobile device management (MDM) system (if supported by that MDM system). EHS simply puts the capabilities into a single tool.

Working with the Config File

This section describes important interactions between EHS and the enterprisehomescreen.xml config file, and instructions for retrieving, modifying and deploying the file to devices.

Config File Location

  • The config file is stored in the /enterprise/usr directory on the device. (does not apply to Secure Mode)
  • This directory is invisible to most apps, including Windows Explorer and Android File Transfer (Mac).
  • The directory is visible to Android File Browser, which can be used to manage its contents.
  • The file is accessible via Android Debug Bridge (ADB) 'pull' and 'push' commands.

Note: Use caution when exposing File Browser to users; it can be used to manipulate the EHS config file and change security or other settings.

Config File Access

Using ADB

The Android Debug Bridge (ADB) is by far the most efficient way to work through the 'pull-edit-push-test' cycle for configuring and testing changes to EHS settings through the enterprisehomescreen.xml file. The process requires a Mac or Windows PC that's connected via USB to a device with EHS installed. For help with software setup, please refer to Setup Guide.

From a computer connected to a target device that has EHS installed:

1. Use ADB to pull the config file from its default location to the local PC:


adb pull /enterprise/usr/enterprisehomescreen.xml


2. Locate, open and edit the config file with a text editor, saving changes.

Important: Do NOT change the file name in any way.

3. Push the edited config file to the device:


adb push /enterprise/usr/enterprisehomescreen.xml


What happens now?
  • Pushing a new version of the config file overwrites the old one.
  • If EHS is running, the new settings will take effect immediately.
  • If EHS is in the background, the new settings take effect the next time EHS comes to the foreground.
Other Notes
  • Config file name must be 'enterprisehomescreen.xml' in lower-case letters.
  • A file with any other spelling or letter case will be ignored.
  • If the config file is deleted at any time, EHS will spawn a new config file with default settings.
  • If a mixed-case config file of the same name is deployed, it will overwrite a correctly cased file.
  • An incorrectly cased config file will be treated as missing file or cause unpredictable results.
  • Once configured, a config file is suitable for mass-deployment using an MDM with or without the EHS app.
Exporting the Config File

For device troubleshooting and certain other scenarios, it is sometimes useful to make the config file (enterprisehomescreen.xml) visible or to look inside the file and check its settings. The file can be made visible from Admin Mode by exporting it to a visible area of the file system. Alternatively, the config file can be viewed, copied, moved and shared via email or other means using the Android File Browser.

Note: An exported file might remain invisible to the PC until the device is rebooted.

1. In Admin Mode on the device, select Export Configuration File from the Tools menu:

2. Tap OK to confirm the action:

3. Note the location in the confirmation message:

4. Drag the config file (arrow) to a PC for editing using Windows Explorer, Android File Transfer (shown) or a similar means:
Note: An exported file might remain invisible to the PC until the device is rebooted.

Using File Browser

The Android File Browser offers a fast way to get a quick view inside the config file on a device. It also permits the file to be copied, moved or shared via email, Bluetooth or any means enabled on the device.

To look inside the config file on a device:

1. In File Browser, navigate to the /enterprise/usr directory:

2. Long-press the enterprisehomescreen.xml file to display the File Operations menu:

3. Select "Open as.." to select a viewer and hit Launch:
It may be necessary to also tap 'txt' to specify the extension type.

3. The config file will open in the Android HTML Viewer:

Default Config File

This section explains the enterprisehomescreen.xml config file, which controls all aspects of EHS behavior. The default version is shown below, followed by an explanation of the file's XML tags and the configuration options for each.

The EHS config file is broken into five sections:

  • Kiosk - Specifies a single application to run when the device is in Kiosk mode.
  • Applications - The apps to be displayed when the device is in User Mode.
  • Tools - The apps to be listed and launched from the User and Admin tools menus.
  • Passwords - Stores the encrypted password for logging into Admin Mode.
  • Preferences - Controls which features and settings the device will display.
Default enterprisehomescreen.xml file:

<?xml version="1.0" encoding="utf-8"?>
 <kiosk>
    <application label="Calculator" package="com.android.calculator2" activity=""/>
</kiosk>

<config>
<applications>
    <application label="Rapid Deployment" package="com.symbol.msp" activity="com.symbol.msp.client.RDMenu"/>
    <application label="Calculator" package="com.android.calculator2" activity="com.android.calculator2.Calculator"/>
    <application label="DWDemo" package="com.symbol.datawedge" activity="com.symbol.datawedge.DWDemoActivity"/>
    <link label="ET1 Video" url="http://www.youtube.com/watch?v=ERlIzLt-h6s"/>
</applications>

<tools>
    <application label="Calculator" package="com.android.calculator2" activity=""/>
    <application label="Rapid Deployment" package="com.symbol.msp" activity="com.symbol.msp.client.RDMenu"/>
</tools>

<passwords>
    <admin></admin>
</passwords>

<preferences>
    <title>Enterprise Home Screen</title>
    <icon_label_background_color>#AAFFFFFF</icon_label_background_color>
    <icon_label_text_color>#FF000000</icon_label_text_color>
    <orientation></orientation>
    <bypass_keyguard>1</bypass_keyguard>
    <auto_launch_enable>0</auto_launch_enable>
    <wallpaper></wallpaper>
    <kiosk_mode_enabled>0</kiosk_mode_enabled>
    <disable_status_bar_settings_icon>1</disable_status_bar_settings_icon>
    <disable_statusbar_pulldown>0</disable_statusbar_pulldown>
    <install_shortcuts>0</install_shortcuts>
    <exit_instead_of_reboot>0</exit_instead_of_reboot>
    <airplane_option_disabled>1</airplane_option_disabled>
    <keyguard_camera_disabled>1</keyguard_camera_disabled>
    <keyguard_search_disabled>1</keyguard_search_disabled>
    <usb_debugging_disabled>1</usb_debugging_disabled>
    <system_settings_restricted>1</system_settings_restricted>
</preferences>
</config>

Config Tags

This section describes all tags in the enterprisehomescreen.xml file and their possible values. They're shown below in the same order they appear in the default file, and are followed by optional tags. Tags can appear in any order, but must appear within the <config> </config> tag set.


Kiosk

Specifies the app to run when the device is in Kiosk Mode, an optional mode under which a single app fills the screen and the BACK and HOME keys cannot be used to exit the app. Kiosk Mode is activated using the <kiosk_mode_enabled> tag in the <Preferences> section.

Possible values

  • Label: string
  • Package: app package name
  • Activity (optional): name of the activity to be invoked when the app starts
Example
<kiosk>
        <application label="Calculator" package="com.android.calculator2" activity=""/>
</kiosk>

Applications

Specifies the applications and/or browser links to be displayed to users while EHS is in User Mode. An optional activity parameter permits an app activity to be invoked when the app starts up. Some apps require an activity to be specified in order to launch.

When specifying links, the package and activity parameters can be used to launch the URL with a specific app, such as Mozilla Mobile browser. If no activity is specified, EHS will launch the link using the default browser.

Note: Package names may vary from one Android version to another.

Possible values (apps)

  • Label: string
  • Package: app package name
  • Activity (optional): name of the activity to be invoked when the app starts

Example (app)

<applications>
    ...
    <application label="Calculator" package="com.android.calculator2" activity="com.android.calculator2.Calculator"/>
    ...
</applications>

Possible values (URLs)

  • Label: string
  • Package: URL (http://, https:// or file://*.html only)

Example (URL)

<applications>
    ...
    <link label="Mozilla Mobile" url="http://www.mozilla.org/en-US/mobile/" package="org.mozilla.firefox" activity="org.mozilla.firefox.App" />
    ...
</applications>

In the example above, the package and activity attributes are used to launch the URL in the Mozilla Mobile browser. If the specified app (as defined in the package and activity parameters) is not present on the device, the URL will not be displayed. If no activity is specified, EHS will launch the link using the default browser.

Link Removal

To remove a web link from the User Mode screen:

  1. Delete the entire tag (which begins with "<link label=" and ends with "/>" as shown above) from the <applications> node of the enterprisehomescreen.xml file.
  2. Redeploy the modified enterprisehomescreen.xml file to the device.

Tools

Specifies the apps to be listed in the Tools menu of Admin and User Modes. Note: Package names may vary from one Android version to another.

Possible values

  • Label: string
  • Package: app package name
  • Activity (optional): name of the activity to be invoked when the app starts

Example

<tools>
    ...
    <application label="Calculator" package="com.android.calculator2" activity=""/>
    ...   
</tools>

Passwords

Stores the encrypted password for logging into Admin Mode (blank by default). Do not populate this tag manually in the config file. The administrator password will be stored here by EHS after being entered or changed through the Tools menu in EHS Admin Mode. EHS uses this tag to store the password as a 256-bit AES-encrypted hash. Once a password is created and stored in the config file, it can be mass-deployed along with all other settings.

The admin password must be entered and changed using the Admin Tools menu in the EHS GUI.

Possible values

  • (for EHS use only; direct user input is not supported for this tag)

Example

<passwords>
    <admin></admin>
</passwords>

Preferences

These tags control various aspects of EHS behavior, security and display settings. Tags can appear in any order between the <preferences> </preferences> tags.

Title

Specifies the title bar text for the EHS app. Default of 'Enterprise Home Screen' can be changed to any string of characters.

Possible values

  • character string

Example

<title>Enterprise Home Screen</title>

Icon Label Background

Specifies the background color of the icon label text of applications displayed in User Mode. This tag must be used for devices with screen resolution less than 480 pixels on any axis, for which the color picker in the Preferences UI is disabled. Default is #AAFFFFFF, white with an opacity value of AA (from a range of 00 to FF). Get help picking HTML color codes.

  • AA specifies the opacity
  • RR specifies the level of RED
  • GG specifies the level of GREEN
  • BB specifies the level of BLUE

Possible values

  • HTML hexadecimal color code values with or without opacity prefix (#RRGGBB or #AARRGGBB)
  • Color names: red, blue, green, black, white, gray, cyan, magenta, yellow, lightgray and darkgray.

Examples

<icon_label_background_color>#AAFFFFFF</icon_label_background_color>
<icon_label_background_color>#75A319</icon_label_background_color>
<icon_label_background_color>#80EF671B</icon_label_background_color>
<icon_label_background_color>magenta</icon_label_background_color>

Icon Label Text Color

Specifies the color of the icon label text of applications displayed in User Mode. This tag must be used for devices with screen resolution less than 480 pixels on any axis, for which the color picker in the Preferences UI is disabled. The EHS default is #FF000000, black with an opacity value of FF (from a range of 00 to FF). Get help picking HTML color codes.

  • AA specifies the opacity
  • RR specifies the level of RED
  • GG specifies the level of GREEN
  • BB specifies the level of BLUE

Possible values

  • HTML hexadecimal color code values with or without opacity prefix (#RRGGBB or #AARRGGBB)
  • Color names: red, blue, green, black, white, gray, cyan, magenta, yellow, lightgray and darkgray.

Examples

<icon_label_text_color>#AAFFFFFF</icon_label_text_color>
<icon_label_text_color>#75A319</icon_label_text_color>
<icon_label_text_color>#80EF671B</icon_label_text_color>
<icon_label_text_color>magenta</icon_label_text_color>

Orientation

Allows the screen orientation to be fixed in landscape or portrait mode. Omitting or leaving this setting blank (default) allows Android system settings to control screen orientation.

Possible values

  • landscape
  • portrait
  • <blank> (default)

Example

<orientation></orientation>

Auto Launch Enable

Enables one or more apps to be automatically launched after EHS starts up. Works with optional <auto_launch> section. When enabled, apps specified in the <auto_launch> section are launched after a specified delay. BACK and HOME keys can be used to exit the app. Refer to Optional Feature Tags section for more information. Disabled by default. See also: Kiosk Mode.

Possible values

  • 1
  • 0 (default)

Example

<auto_launch_enable>0</auto_launch_enable>

Wallpaper

Allows a background image to be specified for display in User Mode. If left unspecified, default image will be used. Supports only .PNG format files in the /enterprise/usr directory.

Possible values

  • fully qualified path to local (on-device) file

Example

<wallpaper>/enterprise/usr/mybackground.png</wallpaper>

Fullscreen

EHS can be made to run in fullscreen mode by setting the value of this tag to 1. Default is 0. Applies only to EHS; apps launched from within EHS will behave as individually designed. Will not prevent access to the Android Status/Notification Bar on some devices. See Disable Status Bar Settings to prevent user access to this feature in EHS.

Possible values

  • 1 (sets EHS to run in full screen mode)
  • 0 (default)

Example

<preferences>
    <fullscreen>1</fullscreen>
</preferences>

Kiosk Mode Enabled

Causes the app specified in the <kiosk> section to be launched in full screen mode after EHS starts up and disables BACK and HOME keys to prevent users from exiting the app. Disabled by default. See also: Auto-Launch.

Once enabled, Kiosk Mode can be disabled by pushing a new config file with its tag set to 0 if USB Debugging is enabled. Otherwise a factory reset is required.

Possible values

  • 1
  • 0 (default)

Example

<kiosk_mode_enabled>0</kiosk_mode_enabled>

Disable Status Bar Settings

Controls whether the Settings icon is displayed in the Android Status Bar, and therefore whether the Settings panel is accessible by users. Not supported on all devices. A setting of 0 in this tag will enable the Status Bar Settings icon.

Note: Changes to this setting will cause an automatic device reboot, a requirement for changes to take effect.

Possible values

  • 1 (default)
  • 0

Example

<disable_status_bar_settings_icon>1</disable_status_bar_settings_icon>

Disable Statusbar Pulldown

Controls whether the Android Status Bar can be pulled down to reveal controls and notifications. The Statusbar Pulldown is enabled by default. If this tag is omitted, contains a value of 0 or is left blank, the Statusbar Pulldown will be enabled. To disable, enter a value of 1.

Possible values

  • 1
  • 0 (default)

Example

<disable_statusbar_pulldown>0</disable_statusbar_pulldown>

Install Shortcuts

Controls whether shortcuts may be added to local or remote apps through Android Intents. Disabled by default.

Possible values

  • 1
  • 0 (default)

Example

<install_shortcuts>0</install_shortcuts>

Exit Instead of Reboot

Controls whether EHS will trigger an automatic device reboot when a setting that requires a reboot is changed. Permits Mobile Device Management (MDM) systems to maintain device control after making such changes. Note: The setting in this tag will be overridden if the <reboot_on_install_enabled> tag has a value of 1.

Possible values

  • 1
  • 0 (default)

Example

<exit_instead_of_reboot>0</exit_instead_of_reboot>

Reboot on Install Enabled

Controls whether the device will automatically reboot when EHS is launched for the first time after a successful installation, a requirement to activate EHS. Permits Mobile Device Management (MDM) systems to maintain device control following installation. Automatic device reboot is disabled by default. Note: When enabled, this tag will override any setting of the <exit_instead_of_reboot> tag.

Possible values

  • 1
  • 0 (default, do not reboot)

Example

<preferences>
    <reboot_on_install_enabled>0</reboot_on_install_enabled >
</preferences>

Airplane Option Disabled

Controls whether the device can be put into 'airplane mode' from the Power menu or Quick Settings bar. Depending on the device, airplane mode can disable Bluetooth, cellular, Wi-Fi and/or other wireless radios and features. EHS blocks airplane mode by default or if this tag is missing or left unspecified. Enter a value of 0 to permit the device to enter airplane mode. (Access to airplane mode from the Power menu might not be available on MC18, MC40 and MC92 devices running Android 4.4 KitKat).

Possible values

  • 1 (default)
  • 0

Example

<airplane_option_disabled>1</airplane_option_disabled>

Bypass Keyguard

Controls whether the Keyguard screen (also known as the 'Lock Screen') is displayed when the device is powered up. Keyguard is bypassed (not displayed) by default. A setting of 0 in this tag will enable the Keyguard.

Note: On devices that employ MX Multi-user features, a setting of 1 for this tag will prevent the multi-user login screen from being displayed. Please refer to important Security Notes involving interactions between EHS and MX Multi-user features.

The Android Keyguard (also known as the Lock Screen).


Possible values

  • 1 (default, Keyguard not displayed)
  • 0

Example

<bypass_keyguard>1</bypass_keyguard>

Keyguard Camera Disabled

Controls whether the device camera will be accessible from the Keyguard screen (also known as the 'Lock Screen'). Applies only if the Keyguard has not been bypassed using the <bypass_keyguard> tag; otherwise ignored. Camera access from the Keyguard screen is disabled if this tag has a value of 1 (default) or is left unspecified.

Possible values

  • 1 (default)
  • 0

Example

<keyguard_camera_disabled>1</keyguard_camera_disabled>

Keyguard Search Disabled

Controls whether the Search app will be accessible from the Keyguard screen (also known as the 'Lock Screen'). Applies only if the Keyguard has not been bypassed using the <bypass_keyguard> tag; otherwise ignored. Search access from the Keyguard screen is disabled if this tag has a value of 1 (default) or is left unspecified.

Possible values

  • 1 (default)
  • 0

Example

<keyguard_search_disabled>1</keyguard_search_disabled>

USB Debugging Disabled

Controls whether communication via USB is permitted between the device and a computer while the device is in User Mode. A setting of 1 (default) or if left unspecified will prevent user access to the file system and all ADB functionality on the device. This setting has no bearing on Admin Mode, in which USB communication is always enabled.

Possible values

  • 1 (default)
  • 0

Example

<usb_debugging_disabled>1</usb_debugging_disabled>

System Settings Restricted

Controls whether full or limited settings are available when the device is in User Mode. A setting of 1 (default) or if left unspecified will restrict user access to device settings. A setting of 0 will permit user access to all device settings.

Possible values

  • 1 (default)
  • 0

Example

<system_settings_restricted>1</system_settings_restricted>

Optional Feature Tags

This section covers optional features and tags not otherwise included in the default enterprisehomescreen.xml file but can be activated by adding their tags to it, if desired, or are activated by EHS as needed.


Auto Launch

This feature permits any number of apps to be launched when EHS starts up. Similar to Kiosk Mode, auto-launch apps are specified in a separate section, can be launched with a specific app activity (optional) and the feature is activated with a tag in the Preferences section. Note: Package names may vary from one Android version to another.

Auto-launch differs from Kiosk Mode in that BACK and HOME keys can be used and it allows apps to be set to launch after a specified delay to allow for SD card mounting. Works when the <auto_launch_enable> tag contains a value of 1; otherwise ignored. Auto-launch apps need not be listed in the <applications> section.

Possible values

  • Application delay: integer (milliseconds)
  • Package: app package name
  • Activity (optional): name of the activity to be invoked when the app starts

Example

<auto_launch>
    <application delay="8000" package="com.android.calculator2" activity=""/>
    <application delay="5000" package="com.rovio.angrybirds" activity=""/>
</auto_launch>

Disable/Enable Applications

Allows apps on a device to be explicitly disabled or enabled in Admin and User Modes. Use these tags to enable Settings and/or Search apps in User Mode. (Settings and Search apps are always enabled in Admin Mode, even if <apps_disabled> tag is applied). Applies to both Admin and User Modes for all other apps. Note: Package names may vary from one Android version to another.

Notes:

  • Settings defined by these tags override EHS defaults and settings applied with other tags.
  • If one of these tags is present without the other, Settings and Search apps will be disabled in User Mode.
  • If the same package name is present under both tags, that app will be disabled.
  • Uninstalling EHS will not re-enable apps disabled using the <apps_disabled> tag.
  • To re-enable an app that was disabled using the <apps_disabled> tag, the app must be explicitly enabled using the <apps_enabled> tag.
  • These tags cannot be used to disable DataWedge or other services.

Possible values

  • Package: app package name

Example

<preferences>
    ...
    <apps_disabled>
        <application package="com.android.settings"/>
        <application package="com.android.quicksearchbox"/>
    </apps_disabled>

    <apps_enabled>
        <application package="com.android.gallery3d"/>
    </apps_enabled>
    ...
</preferences>

Admin Max Attempts

The number of failed attempts to log into Admin Mode before EHS disables Admin Mode login. If this tag is not present or contains no value, the default of 10 will be used. Failed login attempts are added to the EHS log. The counter is cleared after a successful login.

Example

<preferences>
    ...
    <admin_max_attempts>10</admin_max_attempts>
    ...
</preferences>


EHS tracks the number of consecutive failed login attempts by adding the following attribute to the <passwords> tag when necessary:

<passwords>
    <admin attempts="10"></admin>
</passwords>

The counter clears after a successful login.


Admin Inactivity Timeout

Controls the time (in seconds) that a device will remain in Admin Mode without activity. Add this tag to the <Preferences> section to specify the timeout period. The default period is 60 seconds, which will be used if this tag is missing or left unspecified. Minimum period is 15 seconds (lower values will be ignored); zero or negative value disables timeout. The timeout counter runs only when EHS is in foreground, and resets when EHS returns to the foreground.

Possible values

  • integer (in seconds)

Notes:

  • 15 is the minimum value; lower values are ignored
  • 60 seconds is the default if tag is left blank or is not present
  • 0 or negative value will disable the timeout function

Example

<preferences>
    <admin_inactivity_timeout>600</admin_inactivity_timeout>
</preferences>

Adding Apps/Shortcuts With Intents

When shortcuts that link to local or remote applications are added using Android Intents, EHS will add a link tag to the config file with the attributes listed below. Disabled by default. Must be enabled using the Install Shortcuts tag. Note: Package names may vary from one Android version to another.

Label

Represents the shortcut name; equivalent to the Intent.EXTRA_SHORTCUT_NAME value.

URI

Represents the intent in text format; equivalent to the URI representation of the Intent.EXTRA_SHORTCUT_INTENT intent data.

Icon

Specifies the the path of the icon file stored in the device. If the extra data Intent.EXTRA_SHORTCUT_ICON is available in the received broadcast intent, the icon will be stored in the device as an image file.

icon_ref

Specifies the package name to retrieve the icon later. If the extra data Intent.EXTRA_SHORTCUT_ICON_RESOURCE is available in the received broadcast intent, the icon will be generated at runtime using the package name (and there is therefore no need to store the icon image in the device).

Example

A shortcut added to the remote application "Microsoft Excel" via Citrix Receiver would be represented by the following link node:

<link label="Microsoft Excel" icon="/enterprise/usr/ehs_data/images/MicrosoftExcel.png" uri="citrixreceiver://launchapp?pid=1&inname=citrixcloud%3AMicrosoft+Excel+MS&fname=Microsoft+Excel&shortcutCookie=681181718&mobile=0&unikey=0#Intent;action=android.intent.action.VIEW;launchFlags=0x14000000;end" />

EHS Notes:

  • When Install Shortcuts is enabled, EHS listens for the Android broadcast intent com.android.launcher.action.INSTALL_SHORTCUT.
  • When an intent is received, EHS creates the shortcut on the user screen using data carried within the intent.
  • The data also is saved in the <Applications> section of the enterprisehomescreen.xml file as indicated above.
  • To remove a shortcut from user screen, delete the corresponding "link" tag from the config file.
  • Adding duplicate shortcuts for the same local or remote application is allowed.
  • EHS does not check the validity of shortcuts; it's up to the admin to ensure that shortcuts are valid in all circumstances.

Android Notes:

  • The Android Launcher monitors the same broadcast intent as EHS, and therefore also receives shortcuts sent to EHS.
  • If the Android Home screen space limit is reached, Android Launcher displays an error message in EHS.
  • To elimiate the error message, temporarily enable the Android Launcher and delete the shortcuts.

Refer to the Special Features Guide for information about Kiosk Mode, Secure Mode, Lockdown State and other special EHS features and behaviors.