1<!-- 2 Copyright (C) 2020 The Android Open Source Project 3 4 Licensed under the Apache License, Version 2.0 (the "License"); 5 you may not use this file except in compliance with the License. 6 You may obtain a copy of the License at 7 8 http://www.apache.org/licenses/LICENSE-2.0 9 10 Unless required by applicable law or agreed to in writing, software 11 distributed under the License is distributed on an "AS IS" BASIS, 12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 See the License for the specific language governing permissions and 14 limitations under the License 15 --> 16 17# Android Role for system developers 18 19This document targets system developers. App developers should refer to the [RoleManager 20documentation](https://developer.android.com/reference/android/app/role/RoleManager) and AndroidX 21[core-role](https://developer.android.com/reference/androidx/core/role/package-summary) library. 22 23## Definition 24 25A role is a unique name within the system for a purpose, associated with certain requirements and 26privileges if granted. For example, the SMS role requires the app to have certain declarations in 27its manifest that are central to SMS functionality, and grants the app privileges like reading and 28writing user's SMS. 29 30The list of available roles and their behavior can be updated via PermissionController upgrade, out 31of the platform release cycle. Since Android Q, all the default apps (e.g. default SMS app) are 32backed by a corresponding role implementation. 33 34The definition for all the roles can be found in [roles.xml][roles-xml] and 35associated [`RoleBehavior`][role-behavior] [classes][role-behavior-implementations]. 36 37## Defining a role 38 39A role is defined by a `<role>` tag in `roles.xml`. 40 41The following attributes are available for role: 42 43- `name`: The unique name to identify the role, e.g. `android.app.role.SMS`. 44- `behavior`: Optional name of a [`RoleBehavior`][role-behavior] class to control certain 45role behavior in Java code, e.g. `SmsRoleBehavior`. This can be useful when the XML syntax cannot 46express certain behavior specific to the role. 47- `defaultHolders`: Optional name of a system config resource that designates the default holders of 48the role, e.g. `config_defaultSms`. If the role is not exclusive, multiple package names can be 49specified by separating them with a semicolon (`;`). Each package name can also be optionally 50followed by a SHA-256 digest of the expected signing certificate to allow specifying non-system 51apps, separated by a colon (`:`) with the package name, for instance 52`com.example.normalapp:sha256;com.example.systemapp`. 53- `description`: The string resource for the description of the role, e.g. 54`@string/role_sms_description`, which says "Apps that allow you to use your phone number to send and 55receive short text messages, photos, videos, and more". For default apps, this string will appear in 56the default app detail page as a footer. This attribute is required if the role is `visible`. 57- `exclusive`: Whether the role is exclusive. If a role is exclusive, at most one application is 58allowed to be its holder. This attribute is being deprecated and `exclusivity` should be used. 59- `exclusivity`: Whether the role is exclusive and what type of exclusivity behavior it has. A role 60can have exclusivity of `none`, `user`, or `profileGroup`. 61 - `none`: Role allows multiple holders 62 - `user`: Role allows at most one holder within each user 63 - `profileGroup`: (SDK 36+ only, falls back to `user` on lower SDK) Role allows at most one holder 64within a profile group (e.g. full user and work profile) 65- `fallBackToDefaultHolder`: Whether the role should fall back to the default holder. This attribute 66is optional and defaults to `false`. 67- `featureFlag`: Optional feature flag for the role be available, as the fully qualified name of 68the Java method on the `Flags` class which will be invoked via reflection. Note that any new 69aconfig library dependency will need corresponding jarjar rules for PermissionController and the 70system service JAR. 71- `ignoreDisabledSystemPackageWhenGranting`: Whether the role should ignore the requested 72permissions of the disabled system package (if any) when granting permissions. If `false`, the 73permission will need to be requested by the disabled system package as well, if there is one. This 74attribute is optional and defaults to the opposite of `systemOnly` on Android S+, or `true` below 75Android S. **Note:** Extra care should be taken when adding a runtime permission to a role with 76this attribute explicitly set to `true`, because that may allow apps to update and silently obtain 77a new runtime permission. 78- `label`: The string resource for the label of the role, e.g. `@string/role_sms_label`, which says 79"Default SMS app". For default apps, this string will appear in the default app detail page as the 80title. This attribute is required if the role is `visible`. 81- `maxSdkVersion`: The maximum SDK version for the role to be available (inclusive), e.g. `31` for 82Android S. This attribute is optional and defaults to `Build.VERSION_CODES.CUR_DEVELOPMENT`. 83- `minSdkVersion`: The minimum SDK version for the role to be available (inclusive), e.g. `31` for 84Android S. This attribute is optional and defaults to `Build.VERSION_CODES.BASE`. 85- `onlyGrantWhenAdded`: Whether the role should only grant privileges when a role holder is actively 86added. This attribute is optional and defaults to `false`. 87- `overrideUserWhenGranting`: Whether the role should override user's choice about privileges when 88granting. This attribute is optional and defaults to `false`. 89- `requestDescription`: The string resource for the description in the request role dialog, e.g. 90`@string/role_sms_request_description`, which says "Gets access to contacts, SMS, phone". This 91description should describe to the user the privileges that are going to be granted, and should not 92be too long. This attribute is required if the role is both `visible` and `requestable`. 93- `requestTitle`: The string resource for the title of the request role dialog, e.g. 94`@string/role_sms_request_title`, which says "Set %1$s as your default SMS app?". This attribute is 95required if the role is both `visible` and `requestable`. 96- `requestable`: Whether the role will be requestable by apps. If a role isn't requestable but is 97still visible, apps cannot show the request role dialog to user, but user can still manage the role 98in Settings page. This attribute is optional and defaults to the value of `visible`. 99- `searchKeywords`: Optional string resource for additional search keywords for the role, e.g. 100`@string/role_sms_search_keywords` which says "text message, texting, messages, messaging". The role 101label is always implicitly included in search keywords. 102- `shortLabel`: The string resource for the short label of the role, e.g. 103`@string/role_sms_short_label`, which says "SMS app". For default apps, this string will appear in 104the default app list page as the title for the default app item. This attribute is required if the 105role is `visible`. 106- `showNone`: Whether this role will show a "None" option. This allows user to explicitly select 107none of the apps for a role. This attribute is optional, only applies to `exclusive` roles and 108defaults to `false`. 109- `static`: Whether this role is static, i.e. the role will always be assigned to its default 110holders. This attribute is optional and defaults to `false`. 111- `systemOnly`: Whether this role only allows system apps to hold it. This attribute is optional and 112defaults to `false`. 113- `visible`: Whether this role is visible to users. If a role is invisible (a.k.a. hidden) to users, 114users won't be able to find it in Settings, and apps won't be able to request it. The role can still 115be managed by system APIs and shell command. 116- `uiBehavior`: Optional name of a [`RoleUiBehavior`](ui/behavior/RoleUiBehavior.java) class to 117control certain role UI behavior in Java code, e.g. `DialerRoleUiBehavior`. This can be useful 118when the XML syntax cannot express certain UI behavior specific to the role. 119 120The following tags can be specified inside a `<role>` tag: 121 122- `<required-components>`: Child tags like `<activity>`, `<service>`, `<provider>`, `<receiver>` and 123`<meta-data>` can be used to specified the app manifest requirements of the role, and an app is only 124qualified when it declares all these components. They follow a similar syntax as in typical 125`AndroidManifest.xml`. 126- `<permissions>`: Child tags like `<permission-set>` and `<permission>` can be used to specify the 127permissions that should be granted to the app when it has the role. Several `<permission-set>` are 128defined at the beginning of `roles.xml`. 129- `<app-op-permissions>`: The child tag `<app-op-permission>` can be used to specify the app op 130permissions whose app op should be granted to the app when it has the role. 131- `<app-ops>`: The child tag `<app-op>` can be used to specify the app ops that should be granted to 132the app when it has the role. 133- `<preferred-activities>`: The child tag `<preferred-activity>` can be used to specify the 134preferred activities that should be configured for the app when it gets the role. The first 135`<activity>` tag inside `<preferred-activity>` will identify the activity component inside the app, 136and the other `<intent-filter>` tags inside `<preferred-activity>` can be used to specify for which 137intent filters the identified activity component should be configured as preferred, i.e. the default 138handler for those intents. 139 140## Requesting a role 141 142Before requesting a role, an app should check whether it already has the role with 143`RoleManager.isRoleHeld()`. If it doesn't have the role, it should then check for the availability 144of the role with `RoleManager.isRoleAvailable()`. 145 146An app can request for a role by launching the intent returned by 147`RoleManager.createRequestRoleIntent()`. If the role is unavailable or the app isn't qualified for 148the role, the request role dialog won't show up and will return `RESULT_CANCELED` immediately. If 149the role is granted to the app, it will return `RESULT_OK`. 150 151The following is an example about how to request the SMS role: 152 153```kotlin 154val roleManager = getSystemService(RoleManager::class.java) 155if (roleManager.isRoleHeld(RoleManager.ROLE_SMS)) { 156 // We already have the role. 157} else if (roleManager.isRoleAvailable(RoleManager.ROLE_SMS)) { 158 startActivityForResult(roleManager.createRequestRoleIntent(RoleManager.ROLE_SMS), REQUEST_CODE) 159 // Check the result later in onActivityResult(). 160} else { 161 // Role is unavailable. 162} 163``` 164 165## Checking a role 166 167Role is not a replacement for permission, and if one needs to check a certain privilege for an 168action, they should typically check a permission instead, and introduce a new permission if there 169isn't an existing one. 170 171`RoleManager.isRoleHeld()` can be used to check whether an app itself has a role. For checking 172whether an arbitrary app has a certain role, `RoleManager.getRoleHoldersAsUser()` can be used to 173retrieve the list of role holders and check if the app is within the list. This is a system API and 174requires the `MANAGE_ROLE_HOLDERS` permission. 175 176## Managing a role 177 178Generally roles are managed by the role implementation and the user, so it's less likely one should 179manage them manually. 180 181In case the system does need to manage the holders of a role, `RoleManager.addRoleHolderAsUser()`, 182`RoleManager.removeRoleHolderAsUser()` and `RoleManager.clearRoleHoldersAsUser()` may be used. These 183are system APIs and require the `MANAGE_ROLE_HOLDERS` permission. These requests are asynchronous 184and the role might not be modified until the `callback` is notified. The role requirements and 185behavior will still apply even if managed via these APIs, so the request might fail and one need to 186check the result in `callback`. In the event that the role controller hanged or crashed, the 187`callback` will return with failure after a certain timeout. 188 189## Shell command 190 191The current list of roles and their holders can be checked with the following shell command on 192device: 193 194```bash 195dumpsys role 196``` 197 198You can also manage the role holders with `cmd role`: 199 200```bash 201cmd role get-role-holders [--user USER_ID] ROLE 202cmd role add-role-holder [--user USER_ID] ROLE PACKAGE [FLAGS] 203cmd role remove-role-holder [--user USER_ID] ROLE PACKAGE [FLAGS] 204cmd role clear-role-holders [--user USER_ID] ROLE [FLAGS] 205cmd role set-bypassing-role-qualification true|false 206``` 207 208The command outputs nothing and exits with `0` on success. If there was an error, the error will be 209printed and the command will terminate with a non-zero exit code. 210 211[role-behavior]: ../../../../../role-controller/java/com/android/role/controller/model/RoleBehavior.java 212[role-behavior-implementations]: ../../../../../role-controller/java/com/android/role/controller/behavior/ 213[roles-xml]: ../../../../../res/xml/roles.xml 214