Retail Demo Mode

Android 7.1.1 introduced system-level support for retail demo mode so that customers can examine the devices in action at retail stores. Devices are set up for retail demo using a device owner app to ensure that device usage is restricted to certain demo mode apps only. End users must not be able to add a personal account on a retail demo device. Android 8.1 revises this support to create demo users through the DevicePolicyManager createAndManageUser API. This allows much greater OEM customization to the standard retail mode in terms of user management and device policy management on the demo device.

While DevicePolicyManager APIs can be used on versions prior to Android 8.1, demo-type users (DevicePolicyManager.MAKE_USER_DEMO) cannot be created with the createAndManageUser API in versions 8.0 and earlier.

Implementation in Android 8.1 and later

This section highlights the platform enhancements and describes the retail demo app in Android 8.1 and later.

Platform changes

Set DEVICE_DEMO_MODE

Devices implementing a device owner based retail demo mode must set Settings.Global.DEVICE_DEMO_MODE to 1 prior to provisioning to indicate that the device is being provisioned for retail demo mode. SystemServer uses this flag to manage aspects of retail mode, such as power profile and SystemUI.

Note: Once a consumer setup (personal device setup) is complete, a device cannot be provisioned for retail demo.

Enable RetailDemoModeService

In devices implementing a retail demo mode, the setup wizard sets a global setting Global.DEVICE_DEMO_MODE to true to indicate that the device has entered retail mode. Upon seeing this setting, RetailDemoModeService creates a demo user and switches to it 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.

Set custom launcher or video player

Device manufacturers can specify a custom launcher by overriding the framework resource config_demoModeLauncherComponent specified in the config.xml file as follows.

<!-- 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 a device partition such as /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 causes the default system launcher to start 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.

The setup wizard also looks for the previously mentioned 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.

Customize preloaded apps for retail demo mode

Preloaded apps can customize their experience for retail demo mode by calling the UserManager.isDemoUser() API to see if the app is launched in a demo environment.

Certain restrictions are set in the demo user, similar to managed device or profile policies that prevent apps and users from performing certain operations. One of these restrictions is DISALLOW_MODIFY_ACCOUNTS. With this restriction, the AccountManager and Settings don't allow the addition of accounts. Some Google apps react to this restriction and show an error message, and others won't prompt for an account (such as YouTube and Photos). We recommend that OEM apps also check if DISALLOW_MODIFY_ACCOUNTS is set and handle the scenario accordingly.

System updates

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 user interaction.

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.

Retail demo app

Device owner based retail demo mode implementation requires a Device Policy Controller app to be set as the device owner. The AOSP contains a reference RetailDemo app implementation in /packages/apps/RetailDemo.

Device owner apps don't need elevated privileges or pre-installation on the system image and can be downloaded during the setup or provisioning process. 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 DevicePolicyManager 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 has a value of constant 0x4.

• Device ownership must be assigned only through the device management role holder or the ManagedProvisioning app.

APIs in DevicePolicyManager class enable Device Owner (DO) and Profile Owner (PO) to enforce various device policies. Some of the DevicePolicyManager functions applicable for retail demo mode are listed as follows.

• Create and manage users.

• Reboot the device.

• Set LockTask allowed packages.

• Install packages through PackageInstaller.

• Block packages from being uninstalled.

• Enable automatic system updates. Devices will automatically download and apply OTA updates.

• Disable the keyguard.

• Prevent setting passwords or fingerprints.

• Set an allowlisted set of Settings.Global, Settings.Secure, and Settings.System settings.

• Set the permission policy to PERMISSION_POLICY_AUTO_GRANT, which automatically grants all runtime permissions. Permissions can also be granted more narrowly: a single permission to a single app. This doesn't apply to app-ops permissions, which users must still grant on a per-user, per-app basis.

• Set user restrictions relevant to retail mode as defined in UserManager as follows.

  • DISALLOW_MODIFY_ACCOUNTS
  • DISALLOW_USB_FILE_TRANSFER
  • DISALLOW_DEBUGGING_FEATURES
  • DISALLOW_CONFIG_WIFI
  • DISALLOW_CONFIG_BLUETOOTH
  • DISALLOW_INSTALL_UNKNOWN_SOURCES
  • DISALLOW_CONFIG_MOBILE_NETWORKS

Update demo video using 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 in res/values-*/strings.xml. For example, if different videos need to be used in the United States and the Great Britain, then corresponding download URLs can be placed in res/values-en-rUS/strings.xml and res/values-en-rGB/strings.xml, respectively, shown as follows.

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

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

• In res/values-en-rGB/strings.xml:

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

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

If so, the RetailDemo app downloads and starts to play the video. Once the video is downloaded, it is used for playing in all demo sessions going forward. None of the checks happen again until after the next reboot.

Demo video guidelines

Demonstration videos must be in portrait layout or, if tablet, in the device's natural orientation, and can be any length greater than five seconds. Content must not result in burn-in, since it will be played constantly when on display.

See Android Developer definitions of users, profiles, and accounts, Device Policy Manager API documentation and Sample Device Owner app for more information.

Validation

CTS doesn't cover Retail Demo Mode because it is an optional feature. Testing must be conducted manually or with unit tests for the demo app.

Demo session

Setup of demo session

Retail demo devices may boot into retail demo mode if configured for demo mode from the factory. Alternatively, retail employees may enable retail mode directly from the setup wizard.

Note: Retail mode may no longer be available in a device that has completed consumer setup (personal account setup).

Figure 2. Retail demonstration mode

Display demo 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 as described in Implementation. By default, this custom launcher plays the demo video on repeat until the user touches the screen to begin a demo user 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.

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 the following.

• 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 the following:

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

If the user is idle for some period of time (90 seconds by default), retail mode shows 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 removes the current demo user, switches to a new demo user, and loops through the original video again. If the screen is turned off 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 the following:

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

Exit retail demo mode

In order to exit retail mode, retail employees must ensure that the demo device isn't enrolled under device management and factory reset the device from the boot loader.