1 page.title=Requesting Permissions on Android Wear 2 page.tags="Permissions" 3 4 page.article=true 5 @jd:body 6 7 <div id="tb-wrapper"> 8 <div id="tb"> 9 <h2>In this document</h2> 10 <ol class="nolist"> 11 <li><a href="#scenarios">Permission Scenarios</a></li> 12 <li><a href="#requesting">Requesting Permissions</a></li> 13 <li><a href="#services">Permissions for Services</a></li> 14 <li><a href="#settings">Settings</a></li> 15 </ol> 16 <!-- Required platform, tools, add-ons, devices, knowledge, etc. --> 17 <h2>Dependencies and prerequisites</h2> 18 <ul> 19 <li><a href="{@docRoot}about/versions/marshmallow/index.html">Android 6.0</a> 20 (API Level 23) or higher on the wearable and accompanying device</li> 21 <li><a href="{@docRoot}google/play-services/index.html">Google Play 22 services</a> 8.3 or higher</li> 23 <li>An <a href="{@docRoot}wear/index.html">Android Wear</a> device</li> 24 </ul> 25 <h2>See also</h2> 26 <ul> 27 <li><a href="{@docRoot}guide/topics/security/permissions.html">System Permissions</a></li> 28 <li><a href="{@docRoot}training/permissions/index.html">Working with System Permissions</a></li> 29 </ul> 30 </div></div> 31 32 <p><a href="{@docRoot}about/versions/marshmallow/index.html">Android 6.0</a> (API level 23) 33 introduces a new <a href="{@docRoot}training/permissions/requesting.html">permissions model</a>, 34 bringing some changes that are specific to Wear, and other changes that apply to all Android-powered 35 devices.</p> 36 37 <p>The user must now grant permissions to Wear apps separately from the handset versions of the 38 apps. Previously, when a user installed a Wear app, it automatically inherited the set of 39 permissions that the user had granted to the handset version of the app. However, from Android 6.0 40 (API level 23), the Wear app no longer inherits these permissions. Thus, for example, 41 a user might grant a handset app permission to use location data, and subsequently 42 have to grant the same permission to the Wear version of the app.</p> 43 44 <p>For both Wear and handset apps, the Android 6.0 (API level 23) permissions model also 45 streamlines app installation and upgrade by eliminating the requirement that the user grant upfront 46 every permission an app may ever need. Instead, the app does not request permissions until it 47 actually needs them.</p> 48 49 <p class="note"><strong>Note: </strong> For an app to use the new permissions model, it must 50 specify a value of {@code 23} for both 51 <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code uses-sdk-element}</a> 52 and <a href="{@docRoot}tools/building/configuring-gradle.html">{@code compileSdkVersion}</a>.</p> 53 54 <p>The rest of this document discusses how to use the Android 6.0 (API level 23) permissions model 55 when developing Android Wear apps.</p> 56 57 <h2 id="scenarios">Permission Scenarios</h2> 58 59 <p>Broadly speaking, there are four scenarios you may encounter when requesting 60 <a href="{@docRoot}guide/topics/security/permissions.html#normal-dangerous">dangerous permissions</a> 61 on Android Wear:</p> 62 63 <ul> 64 <li>The <em>Wear app</em> requests permissions for an app running on the <em>wearable</em> 65 device.</li> 66 67 <li>The <em>Wear app</em> requests permissions for an app running on the <em>handset</em>.</li> 68 69 <li>The <em>handset app</em> requests permissions for an app running on the 70 <em>wearable</em> device.</li> 71 72 <li>The wearable app uses a <em>different permission model</em> from its handset counterpart. 73 </li> 74 </ul> 75 76 <p>The rest of this section explains each of these scenarios. For more detailed information 77 about requesting permissions, see <a href="#requesting">Requesting Permissions</a>.</p> 78 79 <h3 id="wear-app-wear-perm">Wear app requests permission for an app running on the wearable 80 device</h3> 81 82 <p>When the Wear app requests a permission for an app running on the wearable device, the system 83 displays a dialog to prompt the user for that permission. An app or service can only call the 84 {@link android.support.v4.app.ActivityCompat#requestPermissions requestPermissions()} 85 method from an activity. If the user interacts with your app 86 <a href="#services">via a service</a>, such as 87 a watch face, the service must open an activity before requesting the permission.</p> 88 89 <p>Your app requests permissions in context when its clear why the 90 permissions are needed to perform a given operation. If it's obvious that your app requires 91 certain permissions, your app can prompt for them on launch. If it may not be so obvious, 92 you may choose to provide additional education before prompting for a permission.</p> 93 94 <p>If an app or watch face requires more than one permission at a time, 95 permission requests appear one after the other.</p> 96 97 <img src="{@docRoot}images/training/wear/multiple_permissions.png" 98 srcset="{@docRoot}images/training/wear/multiple_permissions.png 1x, 99 {@docRoot}images/training/wear/multiple_permissions_2x.png 2x" 100 alt="Multiple permission screens, one after another." width="700" height="" id="permission-flow" /> 101 <p class="img-caption"> 102 <strong>Figure 1.</strong> Permission screens appearing in succession. 103 </p> 104 105 <p class="note"><strong>Note:</strong> From Android 6.0 (API level 23), Android Wear 106 automatically syncs Calendar, Contact, and Location data to the Wear device. As a result, this 107 scenario is the applicable one when Wear requests this data.</p> 108 109 <h3>Wear app requests handset permission</h3> 110 111 <p>When the Wear app requests a handset permission, the 112 Wear app must send the user to the handset to accept the permission. There, the handset app can 113 provide additional education to the user via an activity. The activity should include two buttons: 114 one for granting, and one for denying, the permission.</p> 115 116 <img src="{@docRoot}images/training/wear/open_on_phone.png" 117 srcset="{@docRoot}images/training/wear/open_on_phone.png 1x, 118 {@docRoot}images/training/wear/open_on_phone_2x.png 2x" 119 alt="The Wear app sends the user to the handset to grant permission." width="700" 120 height="" id="permission-flow" /> 121 <p class="img-caption"> 122 <strong>Figure 2.</strong> Sending the user to the handset to grant permission. 123 </p> 124 <h3>Handset app requests wearable permission</h3> 125 126 <p>When the user is in a handset app and the app requires a wearable permission, the 127 handset app must send the user to the wearable to accept the permission. 128 The handset app uses the 129 {@link android.support.v4.app.ActivityCompat#requestPermissions requestPermissions()} 130 method on the wearable to trigger the system permissions dialog.</p> 131 132 <img src="{@docRoot}images/training/wear/phone_requests_wear.png" 133 srcset="{@docRoot}images/training/wear/phone_requests_wear.png 1x, 134 {@docRoot}images/training/wear/phone_requests_wear_2x.png 2x" 135 alt="The handset app sends the user to the wearable to grant permission." 136 width="700" height="" id="permission-flow" /> 137 <p class="img-caption"> 138 <strong>Figure 3.</strong> Sending the user to the wearable to grant permission. 139 </p> 140 141 <h3>Mismatching permission models between wearable and handset app</h3> 142 143 <p>If your handset app begins using the Android 6.0 (API level 23) model but your 144 wearable app does not, the system downloads the Wear app, but does not install it. 145 The first time the user launches the app, the system prompts them to grant all pending permissions. 146 Once they do so, it installs the app. 147 If your app, for example a watch face, does not have a launcher, the system displays a 148 stream notification asking the user to grant the permissions the app needs. 149 </p> 150 151 <h2 id="requesting">Permission-Request Patterns</h2> 152 153 <p>There are different patterns for requesting permission from users. In order of 154 priority, they are:</p> 155 156 <ul> 157 <li><a href="#aic">Ask in context</a> when the permission is obviously necessary for a specific 158 functionality, but is not necessary for the app to run at all.</li> 159 160 <li><a href="#eic">Educate in context</a> when the reason for requesting the permission is 161 not obvious, and the permission is not necessary for the app to run at all.</li> 162 163 <li><a href="#auf">Ask up front</a> when the need for the permission is obvious, and the 164 permission is required in order for the app to run at all.</li> 165 166 <li><a href="#euf">Educate up front</a> when the need for the permission is not obvious, but 167 the permission is required in order for the app to run at all.</li> 168 </ul> 169 170 <h3 id="aic">Ask in context</h3> 171 172 <p>Your app should request permissions when its clear why they are needed in order to perform a 173 given operation. Users are more likely to grant a permission when they understand its connection to 174 the feature they want to use.</p> 175 176 <p>For example, an app may require a users location in order to show nearby 177 places of interest. When the user taps to search for nearby places, the app can 178 immediately request the location permission, because there is a clear 179 relationship between searching for nearby places and the need for the location 180 permission. The obviousness of this relationship makes it unnecessary for the app to display 181 additional education screens.</p> 182 183 <img src="{@docRoot}images/training/wear/ask_in_context.png" 184 srcset="{@docRoot}images/training/wear/ask_in_context.png 1x, 185 {@docRoot}images/training/wear/ask_in_context_2x.png 2x" 186 alt="The app requests permission when it's obviously necessary." 187 width="700" height="" id="permission-flow" /> 188 <p class="img-caption"> 189 <strong>Figure 4.</strong> Asking in context. 190 191 <h3 id="eic">Educate in context</h3> 192 193 <p>If necessary, you may choose to provide additional education before prompting 194 for a permission. Again, your app should do this in context of a specific 195 action, if its unclear why your app needs access to the requested permission 196 in order to complete that action.</p> 197 198 <p>Figure 5 shows an example of in-context education. The app does not require permissions 199 in order to start the timer, but an inline educational cue shows that part of the 200 activity (location detection) is locked. When the user taps the cue, a permission-request screen 201 appears, allowing the user to unlock location-detection.</p> 202 203 <p>You can use the {@link 204 android.support.v4.app.ActivityCompat#shouldShowRequestPermissionRationale 205 shouldShowRequestPermissionRationale()} method to help your app decide whether to provide more 206 information. For additional details, see <a 207 href="{@docRoot}training/permissions/requesting.html#explain">Requesting Permissions 208 at Run Time</a>.</p> 209 210 211 <img src="{@docRoot}images/training/wear/educate_in_context.png" 212 srcset="{@docRoot}images/training/wear/educate_in_context.png 1x, 213 {@docRoot}images/training/wear/educate_in_context_2x.png 2x" 214 alt="When the need for the permission arises, the app explains why the permission is necessary." 215 width="700" height="" id="permission-flow" /> 216 <p class="img-caption"> 217 <strong>Figure 5.</strong> Educating in context. 218 219 <h3 id="auf">Ask up front</h3> 220 221 <p>If your app clearly requires a permission in order to work at all, you can prompt for that 222 permission when the user launches the app. For example, a maps app clearly requires access 223 to the devices location to run its expected activities. No further education 224 is necessary for this permission.</p> 225 226 <img src="{@docRoot}images/training/wear/ask_up_front.png" 227 srcset="{@docRoot}images/training/wear/ask_up_front.png 1x, 228 {@docRoot}images/training/wear/ask_up_front_2x.png 2x" 229 alt="If the app obviously needs a permission to run at all, it can ask for it immediately on 230 launch." 231 width="700" height="" id="permission-flow" /> 232 <p class="img-caption"> 233 <strong>Figure 6.</strong> Asking up front. 234 235 236 <h3 id="euf">Educate up front</h3> 237 238 <p>In some cases, the app requires a permission for basic functionality, but the need for that 239 permission is not obvious. In these cases, when the user first 240 starts the app or sets a watch face, the app or watch face may choose to educate the user and 241 ask for the permission.</p> 242 243 <img src="{@docRoot}images/training/wear/educate_up_front.png" 244 srcset="{@docRoot}images/training/wear/educate_up_front.png 1x, 245 {@docRoot}images/training/wear/educate_up_front_2x.png 2x" 246 alt="When requesting a permission on launch, the app can explain why it needs the permission." 247 width="700" height="" id="permission-flow" /> 248 <p class="img-caption"> 249 <strong>Figure 7.</strong> Educating up front. 250 251 <h3 id="nope">Handling Rejection</h3> 252 253 <p>If a user denies a requested permission that is not critical to an intended 254 activity, do not block them from continuing the activity. If certain parts of 255 the activity are disabled by the denied permission, provide visual, actionable 256 feedback. Figure 8 shows the use of a lock icon to indicate that a feature is 257 locked because the user did not grant permission to use it.</p> 258 259 <img src="{@docRoot}images/training/wear/deny.png" 260 srcset="{@docRoot}images/training/wear/deny.png 1x, 261 {@docRoot}images/training/wear/deny_2x.png 2x" 262 alt="When the user denies permission, a lock icon is shown alongside the associated feature." 263 width="700" height="" id="permission-flow" /> 264 <p class="img-caption"> 265 <strong>Figure 8.</strong> Lock icon, showing a feature is locked because of denied permission. 266 </p> 267 <p>When a previously denied wearable permission dialog appears a second 268 time, it includes a <strong>Deny, don't show again</strong> option. If the user 269 chooses this option, then the only way for them to allow this permission in the 270 future is to go into the wearable's Settings app.</p> 271 272 <img src="{@docRoot}images/training/wear/ask_again.png" 273 srcset="{@docRoot}images/training/wear/ask_again.png 1x, 274 {@docRoot}images/training/wear/ask_again_2x.png 2x" 275 alt="The system offers to stop requesting permission." 276 width="700" height="" id="permission-flow" /> 277 <p class="img-caption"> 278 <strong>Figure 9.</strong> Offering not to show the permission-request screen anymore. 279 280 <h2 id="services">Permissions for Services</h2> 281 282 <p>As mentioned above, only an activity can call the 283 {@link android.support.v4.app.ActivityCompat#requestPermissions requestPermissions()} 284 method, so if the user interacts with your app via a service, 285 for example a watch face, the service must open a background activity before requesting 286 the permission. This activity could provide additional education, or it could simply 287 be an invisible activity that brings up the system dialog.</p> 288 289 <p>If your wearable app runs a service that is not a watch face, and the user does not launch 290 an app in which it might make sense to request a permission, 291 you can post an educational notification on the wearable. The notification can 292 provide an action to open an activity that then triggers the system permissions 293 dialog.</p> 294 295 <p class="note"><strong>Note:</strong> This is the only acceptable use of a stream notification 296 for permissions requests.</p> 297 298 <img src="{@docRoot}images/training/wear/for_services.png" 299 srcset="{@docRoot}images/training/wear/for_services.png 1x, 300 {@docRoot}images/training/wear/for_services_2x.png 2x" 301 alt="The user may need to grant a permission when indirectly interacting with an app, via a 302 service." 303 width="700" height="" id="permission-flow" /> 304 <p class="img-caption"> 305 <strong>Figure 10.</strong> A service requesting permission. 306 307 <h2 id="settings">Settings</h2> 308 309 <p>As with the handset, the user can change a Wear apps permissions in Settings at any time. 310 Therefore, when the user tries to do something that requires a 311 permission, the app should always first call the 312 {@link android.support.v4.content.ContextCompat#checkSelfPermission(android.content.Context,java.lang.String) checkSelfPermission()} 313 method to see if the app currently has permission to perform this operation. The app should perform 314 this check even if it knows the user has previously granted that permission, since the 315 user might have subsequently revoked that permission.</p> 316 317 <img src="{@docRoot}images/training/wear/for_settings.png" 318 srcset="{@docRoot}images/training/wear/for_settings.png 1x, 319 {@docRoot}images/training/wear/for_settings_2x.png 2x" 320 alt="The user can change permissions through the Settings app." 321 width="700" height="" id="permission-flow" /> 322 <p class="img-caption"> 323 <strong>Figure 11.</strong> Changing settings via the Settings app. 324
