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](../../../../../res/xml/roles.xml) and
35associated [`RoleBehavior`](model/RoleBehavior.java) classes.
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`](model/RoleBehavior.java) 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.
59- `fallBackToDefaultHolder`: Whether the role should fall back to the default holder. This attribute
60is optional and defaults to `false`.
61- `label`: The string resource for the label of the role, e.g. `@string/role_sms_label`, which says
62"Default SMS app". For default apps, this string will appear in the default app detail page as the
63title. This attribute is required if the role is `visible`.
64- `maxSdkVersion`: The maximum SDK version for the role to be available (inclusive), e.g. `31` for
65Android S. This attribute is optional and defaults to `Build.VERSION_CODES.CUR_DEVELOPMENT`.
66- `minSdkVersion`: The minimum SDK version for the role to be available (inclusive), e.g. `31` for
67Android S. This attribute is optional and defaults to `Build.VERSION_CODES.BASE`.
68- `onlyGrantWhenAdded`: Whether the role should only grant privileges when a role holder is actively
69added. This attribute is optional and defaults to `false`.
70- `overrideUserWhenGranting`: Whether the role should override user's choice about privileges when
71granting. This attribute is optional and defaults to `false`.
72- `requestDescription`: The string resource for the description in the request role dialog, e.g.
73`@string/role_sms_request_description`, which says "Gets access to contacts, SMS, phone". This
74description should describe to the user the privileges that are going to be granted, and should not
75be too long. This attribute is required if the role is both `visible` and `requestable`.
76- `requestTitle`: The string resource for the title of the request role dialog, e.g.
77`@string/role_sms_request_title`, which says "Set %1$s as your default SMS app?". This attribute is
78required if the role is both `visible` and `requestable`.
79- `requestable`: Whether the role will be requestable by apps. If a role isn't requestable but is
80still visible, apps cannot show the request role dialog to user, but user can still manage the role
81in Settings page. This attribute is optional and defaults to the value of `visible`.
82- `searchKeywords`: Optional string resource for additional search keywords for the role, e.g.
83`@string/role_sms_search_keywords` which says "text message, texting, messages, messaging". The role
84label is always implicitly included in search keywords.
85- `shortLabel`: The string resource for the short label of the role, e.g.
86`@string/role_sms_short_label`, which says "SMS app". For default apps, this string will appear in
87the default app list page as the title for the default app item. This attribute is required if the
88role is `visible`.
89- `showNone`: Whether this role will show a "None" option. This allows user to explicitly select
90none of the apps for a role. This attribute is optional, only applies to `exclusive` roles and
91defaults to `false`.
92- `static`: Whether this role is static, i.e. the role will always be assigned to its default
93holders. This attribute is optional and defaults to `false`.
94- `systemOnly`: Whether this role only allows system apps to hold it. This attribute is optional and
95defaults to `false`.
96- `visible`: Whether this role is visible to users. If a role is invisible (a.k.a. hidden) to users,
97users won't be able to find it in Settings, and apps won't be able to request it. The role can still
98be managed by system APIs and shell command.
99- `uiBehavior`: Optional name of a [`RoleUiBehavior`](ui/behavior/RoleUiBehavior.java) class to
100control certain role UI behavior in Java code, e.g. `DialerRoleUiBehavior`. This can be useful
101when the XML syntax cannot express certain UI behavior specific to the role.
102
103The following tags can be specified inside a `<role>` tag:
104
105- `<required-components>`: Child tags like `<activity>`, `<service>`, `<provider>`, `<receiver>` and
106`<meta-data>` can be used to specified the app manifest requirements of the role, and an app is only
107qualified when it declares all these components. They follow a similar syntax as in typical
108`AndroidManifest.xml`.
109- `<permissions>`: Child tags like `<permission-set>` and `<permission>` can be used to specify the
110permissions that should be granted to the app when it has the role. Several `<permission-set>` are
111defined at the beginning of `roles.xml`.
112- `<app-op-permissions>`: The child tag `<app-op-permission>` can be used to specify the app op
113permissions whose app op should be granted to the app when it has the role.
114- `<app-ops>`: The child tag `<app-op>` can be used to specify the app ops that should be granted to
115the app when it has the role.
116- `<preferred-activities>`: The child tag `<preferred-activity>` can be used to specify the
117preferred activities that should be configured for the app when it gets the role. The first
118`<activity>` tag inside `<preferred-activity>` will identify the activity component inside the app,
119and the other `<intent-filter>` tags inside `<preferred-activity>` can be used to specify for which
120intent filters the identified activity component should be configured as preferred, i.e. the default
121handler for those intents.
122
123## Requesting a role
124
125Before requesting a role, an app should check whether it already has the role with
126`RoleManager.isRoleHeld()`. If it doesn't have the role, it should then check for the availability
127of the role with `RoleManager.isRoleAvailable()`.
128
129An app can request for a role by launching the intent returned by
130`RoleManager.createRequestRoleIntent()`. If the role is unavailable or the app isn't qualified for
131the role, the request role dialog won't show up and will return `RESULT_CANCELED` immediately. If
132the role is granted to the app, it will return `RESULT_OK`.
133
134The following is an example about how to request the SMS role:
135
136```kotlin
137val roleManager = getSystemService(RoleManager::class.java)
138if (roleManager.isRoleHeld(RoleManager.ROLE_SMS)) {
139    // We already have the role.
140} else if (roleManager.isRoleAvailable(RoleManager.ROLE_SMS)) {
141    startActivityForResult(roleManager.createRequestRoleIntent(RoleManager.ROLE_SMS), REQUEST_CODE)
142    // Check the result later in onActivityResult().
143} else {
144    // Role is unavailable.
145}
146```
147
148## Checking a role
149
150Role is not a replacement for permission, and if one needs to check a certain privilege for an
151action, they should typically check a permission instead, and introduce a new permission if there
152isn't an existing one.
153
154`RoleManager.isRoleHeld()` can be used to check whether an app itself has a role. For checking
155whether an arbitrary app has a certain role, `RoleManager.getRoleHoldersAsUser()` can be used to
156retrieve the list of role holders and check if the app is within the list. This is a system API and
157requires the `MANAGE_ROLE_HOLDERS` permission.
158
159## Managing a role
160
161Generally roles are managed by the role implementation and the user, so it's less likely one should
162manage them manually.
163
164In case the system does need to manage the holders of a role, `RoleManager.addRoleHolderAsUser()`,
165`RoleManager.removeRoleHolderAsUser()` and `RoleManager.clearRoleHoldersAsUser()` may be used. These
166are system APIs and require the `MANAGE_ROLE_HOLDERS` permission. These requests are asynchronous
167and the role might not be modified until the `callback` is notified. The role requirements and
168behavior will still apply even if managed via these APIs, so the request might fail and one need to
169check the result in `callback`. In the event that the role controller hanged or crashed, the
170`callback` will return with failure after a certain timeout.
171
172## Shell command
173
174The current list of roles and their holders can be checked with the following shell command on
175device:
176
177```bash
178dumpsys role
179```
180
181You can also manage the role holders with `cmd role`:
182
183```bash
184cmd role get-role-holders [--user USER_ID] ROLE
185cmd role add-role-holder [--user USER_ID] ROLE PACKAGE [FLAGS]
186cmd role remove-role-holder [--user USER_ID] ROLE PACKAGE [FLAGS]
187cmd role clear-role-holders [--user USER_ID] ROLE [FLAGS]
188cmd role set-bypassing-role-qualification true|false
189```
190
191The command outputs nothing and exits with `0` on success. If there was an error, the error will be
192printed and the command will terminate with a non-zero exit code.
193