Build multiuser-aware apps

When a device supports multiple users, its apps must be made aware of these distinct users.

Certain apps need to have some components run as singletons and can accept requests from any user. Only system apps can currently use this feature.

This facility:

  • Conserves resources
  • Arbitrates one or more shared resources across users
  • Reduces network overhead by using a single server connection

See the diagram below for a depiction of permissions flow with multiple users.

Multiple users permissions flow

Figure 1. Multiple users permissions

Enable a singleton component

To identify an app as a singleton, add android:singleUser="true" to your service, receiver, or provider in the Android manifest.

The system instantiates that component in the process running as user 0 only. Any requests to connect to that provider or service, or to broadcast to that receiver, from any user is routed to the process in user 0. If this is the only component in your app, only one instance of your app runs.

Activities in your package are still launched in a separate process for each user, with the UID being in the UID range for that user (such as 1010034).

Interact with users

Set permissions

These permissions are required:

INTERACT_ACROSS_USERS (signature|system)
INTERACT_ACROSS_USERS_FULL (signature)

Employ APIs

Use the following APIs to make apps aware of multiple users.

  1. Extract the user handle from incoming Binder calls:
    • int userHandle = UserHandle.getCallingUserId()
  2. Use new, protected APIs to start services, activities, broadcasts on a specific user:
    • Context.startActivityAsUser(Intent, UserHandle)
    • Context.bindServiceAsUser(Intent, …, UserHandle)
    • Context.sendBroadcastAsUser(Intent, … , UserHandle)
    • Context.startServiceAsUser(Intent, …, UserHandle)
    UserHandle can be an explicit user or one of the special handles: UserHandle.CURRENT or UserHandle.ALL. CURRENT indicates the user that is currently in the foreground. Use ALL when you want to send a broadcast to all users.
  3. Communicate with components in your own app: (INTERACT_ACROSS_USERS) Or with components in other apps: (INTERACT_ACROSS_USERS_FULL)
  4. You might need to create proxy components that run in the user's process that then access the singleUser component in user 0.
  5. Query users and their handles with the new UserManager system service:
    • UserManager.getUsers()
    • UserManager.getUserInfo()
    • UserManager.supportsMultipleUsers()
    • UserManager.getUserSerialNumber(int userHandle) - a nonrecycled number that corresponds to a user handle.
    • UserManager.getUserHandle(int serialNumber)
    • UserManager.getUserProfiles() - returns the collection of self and managed profiles, if any.
  6. Register to listen to specific or all users and the callbacks with new APIs on ContentObserver, PackageMonitor, BroadcastReceiver that provide additional information about which user has caused the callback.

Services in multiple users or profiles

Not all services need to run an instance in another user or work profile. If your system service only needs to run as user 0, disable the service's components when running under other users to help preserve resources. The following example shows how you might do this at your service's entry points:

// Add on all entry points such as boot_completed or other manifest-listed receivers and providers
if (!UserManager.isSystemUser()) {
    // Disable the service
    ComponentName targetServiceName = new ComponentName(this, TargetService.class);
    context.getPackageManager().setComponentEnabledSetting(
        targetServiceName, COMPONENT_ENABLED_STATE_DISABLED, 0);
}

The example could also use PackageManager.setApplicationEnabledSetting() to disable the entire app.