Retail Demo Mode

Android 7.1.1 and later offer system-level support for retail mode so users may readily examine the devices in action. Android 8.1 revises this support to create demo users via Device Policy Manager. This allows much greater OEM customization to the standard retail mode.

Android 8.1 and later

Through Device Policy Manager, Android 8.1 supports demonstrating device functionality to users in retail stores. While Device Policy Manager's APIs can be used on versions prior to 8.1, demo-type users cannot be created with createAndManageUser prior to 8.1.

Implementation

Provisioning

Set Settings.Global.DEVICE_DEMO_MODE to 1 prior to provisioning to indicate that the device should enter retail mode. System Server will use this flag to manage aspects of retail mode, such as power profile. In addition, retail employees must grant device ownership to the demo application. Once a consumer setup is complete, device owners cannot be set.

Creating the demo application

Device owner apps do not need elevated privileges or pre-installation on the system image. They are mostly implemented like traditional apps, with the following differences:

  • All device owner apps must extend the DeviceAdminReceiver component, which serves as the authorization token for all Device Policy Manager APIs. The component must hold the android.permission.BIND_DEVICE_ADMIN permission, include the requested special policies as metadata, and filter the android.app.action.PROFILE_PROVISIONING_COMPLETE and android.app.action.DEVICE_ADMIN_ENABLED intents.
  • The DevicePolicyManager#MAKE_USER_DEMO flag, which is set to create special demo-type users, is a hidden API. This flag is a constant 0x4.
  • Device ownership can be assigned only via Managed Provisioning.

Device Policy Manager

Device Policy Manager APIs grant all Device Owner (DO) and Profile Owner (PO) rights, except for installing packages, which is automatically allowed. A PO affiliated with a DO can use an AIDL interface to access rights that are only granted to the DO. Functionality available includes:

  • Create users. Users created through the DevicePolicyManager are automatically set as PO.
  • Switch users.
  • Set the permission policy to PERMISSION_POLICY_AUTO_GRANT which will automatically grant all runtime permissions. Permissions can also be granted more narrowly: a single permission to a single app. This does not apply to Appops permissions, which users must still grant on a per-user, per-app basis.
  • Add user restrictions. Restrictions relevant to retail mode may include, but are not limited to:
    • DISALLOW_MODIFY_ACCOUNTS
    • DISALLOW_USB_FILE_TRANSFER
    • DISALLOW_DEBUGGING_FEATURES
    • DISALLOW_CONFIG_WIFI
    • DISALLOW_CONFIG_BLUETOOTH
    • DISALLOW_INSTALL_UNKNOWN_SOURCES
    • DISALLOW_CONFIG_MOBILE_NETWORKS
  • Enable automatic system updates. Devices will automatically download and apply OTA updates.
  • Set LockTask allowed packages.
  • Factory reset the device.
  • Disable the keyguard.
  • Prevent setting passwords / fingerprints.
  • Control Wi-fi network changes. When used with the DISALLOW_CONFIG_WIFI user restriction, device owner apps can control access to the wifi network selection setting.
  • Reboot the device.
  • Install packages through PackageInstaller.
  • Set a whitelisted set of Settings.Global, Settings.Secure, and Settings.System settings.
  • Block packages from being uninstalled.

Examples and additional resources

Validation

CTS does not cover Retail Demo Mode because it is an optional feature. Testing should be conducted manually or with unit tests for the demo application.

Android 8.0 and earlier

Android 7.1.1 introduced retail demo mode and provided a simple API to play a demonstration video. This implementation was removed in Android 8.1.

Lifecycle

retail demo mode flow

Figure 1. Retail demonstration mode option in Language selection

Setup Wizard (SUW)

Retail employees can enable retail mode directly from the first screen of any setup wizard by selecting the language Retail demo at the bottom of the list. This option is available for new devices shipped fresh from the factory. Once a consumer setup has completed, retail mode may no longer be available. Once selected, the device finishes SUW with an abbreviated flow.

retail demo wizard use

Figure 2. Retail demonstration mode option in Language selection

Guest session

When the device enters retail mode, it switches to a new demo user and automatically starts the custom launcher specified in the overlay resource (described under Implementation). By default, this custom launcher plays the demo video on repeat until the user touches the screen to begin a guest session. At that time, the custom launcher starts the system launcher and then exits. OEMs can alter the custom launcher to additionally launch another service or activity on exit. See the Implementation section for details.

In order to maintain the integrity of retail mode, keyguard is disabled and certain actions from Quick Settings that could adversely affect retail mode are also disallowed, including:

  • Airplane mode toggle
  • Removing or modifying Wi-Fi access points (Settings)
  • Changing carrier (Settings)
  • Configuring hotspot (Settings)
  • User switching

Additionally, access is also blocked to some global settings that can affect retail mode by disabling:

  • Wi-Fi settings
  • Cellular network configuration options, particularly hotspots
  • Bluetooth configuration
  • Backup & Reset, Date & Time, and Mobile Networks (they do not show up at all)

If the user is idle for some period of time (90 seconds by default), retail mode will show a system dialog to prompt the user to either exit the session or continue. If the user chooses to exit or if there's no response for five seconds, retail mode kills/wipes the current demo user, switches to a new demo user, and loops through the original video again. If someone turns off the screen using the power button, it comes back on automatically after a few seconds.

After exiting a demo session, devices mute themselves and reset some global settings, including:

  • Brightness
  • Auto-rotation
  • Flashlight
  • Language
  • Accessibility

Exiting retail mode

In order to exit retail mode, retail employees must factory reset the device from the boot loader.

Examples and source

Find the custom launcher that plays a video in a loop within:

/packages/apps/RetailDemo

Implementation

Enabling RetailDemoModeService

Setup wizard sets a Global setting Global.DEVICE_DEMO_MODE=true to indicate that the device has entered retail mode. Upon seeing this setting, RetailDemoModeService creates and switches to demo user when user 0 is started, enables the custom launcher specified in an overlay resource, and disables SUW. System Server and SystemUI also use this flag to manage aspects of retail mode.

Setting custom launcher or video player

An OEM specifies a custom launcher by overriding the framework resource config_demoModeLauncherComponent specified in: /frameworks/base/core/res/res/config.xml

For example, with: 

<!-- Component that is the default launcher when Retail Mode is enabled. -->
<string name="config_demoModeLauncherComponent">com.android.retaildemo/.DemoPlayer</string>

The retail demo DemoPlayer app located at /packages/apps/RetailDemo is the default custom launcher in the Android Open Source Project (AOSP). The app looks for a video in /data/preloads/demo/retail_demo.mp4 and plays it in a loop. When the user touches the screen, the custom launcher disables its activity component, which results in the default system launcher starting up.

The custom launcher must have its custom component marked as disabled by default so that it doesn't show up in non-demo scenarios. In the demo scenario, System Server enables the specified config_demoModeLauncherComponent when starting a new demo session.

Setup wizard also looks for the above video to provide an affordance to enter retail mode. SUW can be modified to look for some other OEM-specific sign that retail mode is supported if the video is not a part of the demo.

If there are system A/B partitions, the system B partition must contain the demo video at /preloads/demo. This gets copied to /data/preloads/demo on first boot.

To set retail mode-specific settings, use: Settings.Global.retail_demo_mode_constants. E.g.: user_inactivity_timeout_ms=90000,warning_dialog_timeout_ms=10000

Note: 90000 milliseconds is the current timeout default but is configurable.

Finding sample images

This feature places sample photos in a special folder that is visible to any gallery app. The photos are available only in demo mode and cannot be modified by the demo user as they are in a protected directory.

Preventing Google accounts

Certain restrictions are set in the guest user, similar to managed device/profile policies that prevent apps and users from performing certain operations. One of these restrictions is DISALLOW_MODIFY_ACCOUNTS. With this restriction, AccountManager and Settings do not allow the addition of accounts. Some Google apps react to this restriction and show an error message, and others will not prompt for an account (such as YouTube and Photos).

OEM apps should also check if DISALLOW_MODIFY_ACCOUNTS is set. But this is a general problem not unique to retail mode. It is likely already solved for enterprise use cases.

Customizing the system launcher

OEMs are free to choose their layout but should include apps that function well on the home screen and hotseat.

Customizing built-in apps for retail demo mode

Built-in apps may have their experience for retail demo mode customized by calling the API UserManager.isDemoUser() to see if the app is launched in a demo environment.

Following demo video guidelines

Demonstration videos should be in portrait layout (or natural orientation of the device, if tablet) and can be any length greater than five seconds. Content should not result in burn-in, since it will be played 24/7 when on display.

Maintenance

Bringing the device out of retail mode

This can be done only by factory resetting from the boot loader.

Auto-OTA of system software

By default, when retail mode is enabled, device policy is set to over-the-air (OTA) update automatically. Retail devices will download, reboot, and install the update (respecting battery thresholds) without confirmation even if it is marked as optional.

Caution: If using System A/B partitions for OTA, once an OTA is received, the device cannot find original retail mode resources in the System B partition. So any subsequent factory reset will result in an inability to go back into retail mode.

Updating demo video via the web

The RetailDemo app in /packages/apps/RetailDemo has the ability to update the demo video if there is network connectivity. The URL to download the video from can be configured by overriding the following string value in the RetailDemo app: 

<!-- URL where the retail demo video can be downloaded from. -->
<string name="retail_demo_video_download_url"></string>

If different videos need to be used in different regions, then different download URLs can be configured by using locale-specific string resources res/values-*/strings.xml. For example, if different videos need to be used in the U.S. and the U.K., then corresponding download URLs can be placed in res/values-en-rUS/strings.xml and res/values-en-rGB/strings.xml, respectively.

In res/values-en-rUS/strings.xml: 

<string name="retail_demo_video_download_url">download URL for US video goes here</string>

And similarly in res/values-en-rGB/strings.xml: 

<string name="retail_demo_video_download_url">download URL for UK video goes here</string>

This video will be downloaded at most once per every device reboot. When the video on the device is being played, RetailDemo app will check in the background if the download URL is provided and the video at the URL is newer than the one being played.

If so, RetailDemo app will download this video and start playing it. Once this video is downloaded, the downloaded video will be used for playing in the demo sessions going forward. None of the checks happen again until after next reboot.