docs/html/training/articles/wear-permissions.jd

page.title=Requesting Permissions on Android Wear
page.tags="Permissions"

page.article=true
@jd:body

<div id="tb-wrapper">
<div id="tb">
<h2>In this document</h2>
<ol class="nolist">
  <li><a href="#scenarios">Permission Scenarios</a></li>
  <li><a href="#requesting">Requesting Permissions</a></li>
  <li><a href="#services">Permissions for Services</a></li>
  <li><a href="#settings">Settings</a></li>
</ol>
<!-- Required platform, tools, add-ons, devices, knowledge, etc. -->
<h2>Dependencies and prerequisites</h2>
<ul>
  <li><a href="{@docRoot}about/versions/marshmallow/index.html">Android 6.0</a>
  (API Level 23) or higher on the wearable and accompanying device</li>
  <li><a href="{@docRoot}google/play-services/index.html">Google Play
services</a> 8.3 or higher</li>
  <li>An <a href="{@docRoot}wear/index.html">Android Wear</a> device</li>
</ul>
<h2>See also</h2>
<ul>
  <li><a href="{@docRoot}guide/topics/security/permissions.html">System Permissions</a></li>
  <li><a href="{@docRoot}training/permissions/index.html">Working with System Permissions</a></li>
</ul>
</div></div>

<p><a href="{@docRoot}about/versions/marshmallow/index.html">Android 6.0</a> (API level 23)
introduces a new <a href="{@docRoot}training/permissions/requesting.html">permissions model</a>,
bringing some changes that are specific to Wear, and other changes that apply to all Android-powered
devices.</p>

<p>The user must now grant permissions to Wear apps separately from the handset versions of the
apps. Previously, when a user installed a Wear app, it automatically inherited the set of
permissions that the user had granted to the handset version of the app. However, from Android 6.0
(API level 23), the Wear app no longer inherits these permissions. Thus, for example,
a user might grant a handset app permission to use location data, and subsequently
have to grant the same permission to the Wear version of the app.</p>

<p>For both Wear and handset apps, the Android 6.0 (API level 23) permissions model also
streamlines app installation and upgrade by eliminating the requirement that the user grant upfront
every permission an app may ever need. Instead, the app does not request permissions until it
actually needs them.</p>

<p class="note"><strong>Note: </strong> For an app to use the new permissions model, it must
specify a value of {@code 23} for both
<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code uses-sdk-element}</a>
and <a href="{@docRoot}tools/building/configuring-gradle.html">{@code compileSdkVersion}</a>.</p>

<p>The rest of this document discusses how to use the Android 6.0 (API level 23) permissions model
when developing Android Wear apps.</p>

<h2 id="scenarios">Permission Scenarios</h2>

<p>Broadly speaking, there are four scenarios you may encounter when requesting
<a href="{@docRoot}guide/topics/security/permissions.html#normal-dangerous">dangerous permissions</a>
on Android Wear:</p>

<ul>
   <li>The <em>Wear app</em> requests permissions for an app running on the <em>wearable</em>
   device.</li>

   <li>The <em>Wear app</em> requests permissions for an app running on the <em>handset</em>.</li>

   <li>The <em>handset app</em> requests permissions for an app running on the
   <em>wearable</em> device.</li>

   <li>The wearable app uses a <em>different permission model</em> from its handset counterpart.
   </li>
</ul>

<p>The rest of this section explains each of these scenarios. For more detailed information
about requesting permissions, see <a href="#requesting">Requesting Permissions</a>.</p>

<h3 id="wear-app-wear-perm">Wear app requests permission for an app running on the wearable
device</h3>

<p>When the Wear app requests a permission for an app running on the wearable device, the system
displays a dialog to prompt the user for that permission. An app or service can only call the
{@link android.support.v4.app.ActivityCompat#requestPermissions requestPermissions()}
method from an activity. If the user interacts with your app
<a href="#services">via a service</a>, such as
a watch face, the service must open an activity before requesting the permission.</p>

<p>Your app requests permissions in context when it’s clear why the
permissions are needed to perform a given operation. If it's obvious that your app requires
certain permissions, your app can prompt for them on launch. If it may not be so obvious,
you may choose to provide additional education before prompting for a permission.</p>

<p>If an app or watch face requires more than one permission at a time,
permission requests appear one after the other.</p>

<img src="{@docRoot}images/training/wear/multiple_permissions.png"
srcset="{@docRoot}images/training/wear/multiple_permissions.png 1x,
{@docRoot}images/training/wear/multiple_permissions_2x.png 2x"
alt="Multiple permission screens, one after another." width="700" height="" id="permission-flow" />
<p class="img-caption">
  <strong>Figure 1.</strong> Permission screens appearing in succession.
</p>

<p class="note"><strong>Note:</strong> From Android 6.0 (API level 23), Android Wear
automatically syncs Calendar, Contact, and Location data to the Wear device. As a result, this
scenario is the applicable one when Wear requests this data.</p>

<h3>Wear app requests handset permission</h3>

<p>When the Wear app requests a handset permission, the
Wear app must send the user to the handset to accept the permission. There, the handset app can
provide additional education to the user via an activity. The activity should include two buttons:
one for granting, and one for denying, the permission.</p>

<img src="{@docRoot}images/training/wear/open_on_phone.png"
srcset="{@docRoot}images/training/wear/open_on_phone.png 1x,
{@docRoot}images/training/wear/open_on_phone_2x.png 2x"
alt="The Wear app sends the user to the handset to grant permission." width="700"
height="" id="permission-flow" />
<p class="img-caption">
  <strong>Figure 2.</strong> Sending the user to the handset to grant permission.
</p>
<h3>Handset app requests wearable permission</h3>

<p>When the user is in a handset app and the app requires a wearable permission, the
handset app must send the user to the wearable to accept the permission.
The handset app uses the
{@link android.support.v4.app.ActivityCompat#requestPermissions requestPermissions()}
method on the wearable to trigger the system permissions dialog.</p>

<img src="{@docRoot}images/training/wear/phone_requests_wear.png"
srcset="{@docRoot}images/training/wear/phone_requests_wear.png 1x,
{@docRoot}images/training/wear/phone_requests_wear_2x.png 2x"
alt="The handset app sends the user to the wearable to grant permission."
width="700" height="" id="permission-flow" />
<p class="img-caption">
  <strong>Figure 3.</strong> Sending the user to the wearable to grant permission.
</p>

<h3>Mismatching permission models between wearable and handset app</h3>

<p>If your handset app begins using the Android 6.0 (API level 23) model but your
wearable app does not, the system downloads the Wear app, but does not install it.
The first time the user launches the app, the system prompts them to grant all pending permissions.
Once they do so, it installs the app.
If your app, for example a watch face, does not have a launcher, the system displays a
stream notification asking the user to grant the permissions the app needs.
</p>

<h2 id="requesting">Permission-Request Patterns</h2>

<p>There are different patterns for requesting permission from users. In order of
priority, they are:</p>

<ul>
   <li><a href="#aic">Ask in context</a> when the permission is obviously necessary for a specific
   functionality, but is not necessary for the app to run at all.</li>

   <li><a href="#eic">Educate in context</a> when the reason for requesting the permission is
   not obvious, and the permission is not necessary for the app to run at all.</li>

   <li><a href="#auf">Ask up front</a> when the need for the permission is obvious, and the
   permission is required in order for the app to run at all.</li>

   <li><a href="#euf">Educate up front</a> when the need for the permission is not obvious, but
   the permission is required in order for the app to run at all.</li>
</ul>

<h3 id="aic">Ask in context</h3>

<p>Your app should request permissions when it’s clear why they are needed in order to perform a
given operation. Users are more likely to grant a permission when they understand its connection to
the feature they want to use.</p>

<p>For example, an app may require a user’s location in order to show nearby
places of interest. When the user taps to search for nearby places, the app can
immediately request the location permission, because there is a clear
relationship between searching for nearby places and the need for the location
permission. The obviousness of this relationship makes it unnecessary for the app to display
additional education screens.</p>

<img src="{@docRoot}images/training/wear/ask_in_context.png"
srcset="{@docRoot}images/training/wear/ask_in_context.png 1x,
{@docRoot}images/training/wear/ask_in_context_2x.png 2x"
alt="The app requests permission when it's obviously necessary."
width="700" height="" id="permission-flow" />
<p class="img-caption">
  <strong>Figure 4.</strong> Asking in context.

<h3 id="eic">Educate in context</h3>

<p>If necessary, you may choose to provide additional education before prompting
for a permission. Again, your app should do this in context of a specific
action, if it’s unclear why your app needs access to the requested permission
in order to complete that action.</p>

<p>Figure 5 shows an example of in-context education. The app does not require permissions
in order to start the timer, but an inline educational cue shows that part of the
activity (location detection) is locked. When the user taps the cue, a permission-request screen
appears, allowing the user to unlock location-detection.</p>

<p>You can use the {@link
  android.support.v4.app.ActivityCompat#shouldShowRequestPermissionRationale
  shouldShowRequestPermissionRationale()} method to help your app decide whether to provide more
  information. For additional details, see <a
  href="{@docRoot}training/permissions/requesting.html#explain">Requesting Permissions
  at Run Time</a>.</p>


<img src="{@docRoot}images/training/wear/educate_in_context.png"
srcset="{@docRoot}images/training/wear/educate_in_context.png 1x,
{@docRoot}images/training/wear/educate_in_context_2x.png 2x"
alt="When the need for the permission arises, the app explains why the permission is necessary."
width="700" height="" id="permission-flow" />
<p class="img-caption">
  <strong>Figure 5.</strong> Educating in context.

<h3 id="auf">Ask up front</h3>

<p>If your app clearly requires a permission in order to work at all, you can prompt for that
permission when the user launches the app. For example, a maps app clearly requires access
to the device’s location to run its expected activities. No further education
is necessary for this permission.</p>

<img src="{@docRoot}images/training/wear/ask_up_front.png"
srcset="{@docRoot}images/training/wear/ask_up_front.png 1x,
{@docRoot}images/training/wear/ask_up_front_2x.png 2x"
alt="If the app obviously needs a permission to run at all, it can ask for it immediately on
launch."
width="700" height="" id="permission-flow" />
<p class="img-caption">
  <strong>Figure 6.</strong> Asking up front.


<h3 id="euf">Educate up front</h3>

<p>In some cases, the app requires a permission for basic functionality, but the need for that
permission is not obvious. In these cases, when the user first
starts the app or sets a watch face, the app or watch face may choose to educate the user and
ask for the permission.</p>

<img src="{@docRoot}images/training/wear/educate_up_front.png"
srcset="{@docRoot}images/training/wear/educate_up_front.png 1x,
{@docRoot}images/training/wear/educate_up_front_2x.png 2x"
alt="When requesting a permission on launch, the app can explain why it needs the permission."
width="700" height="" id="permission-flow" />
<p class="img-caption">
  <strong>Figure 7.</strong> Educating up front.

<h3 id="nope">Handling Rejection</h3>

<p>If a user denies a requested permission that is not critical to an intended
activity, do not block them from continuing the activity.  If certain parts of
the activity are disabled by the denied permission, provide visual, actionable
feedback. Figure 8 shows the use of a lock icon to indicate that a feature is
locked because the user did not grant permission to use it.</p>

<img src="{@docRoot}images/training/wear/deny.png"
srcset="{@docRoot}images/training/wear/deny.png 1x,
{@docRoot}images/training/wear/deny_2x.png 2x"
alt="When the user denies permission, a lock icon is shown alongside the associated feature."
width="700" height="" id="permission-flow" />
<p class="img-caption">
  <strong>Figure 8.</strong> Lock icon, showing a feature is locked because of denied permission.
</p>
<p>When a previously denied wearable permission dialog appears a second
time, it includes a <strong>Deny, don't show again</strong> option. If the user
chooses this option, then the only way for them to allow this permission in the
future is to go into the wearable's Settings app.</p>

<img src="{@docRoot}images/training/wear/ask_again.png"
srcset="{@docRoot}images/training/wear/ask_again.png 1x,
{@docRoot}images/training/wear/ask_again_2x.png 2x"
alt="The system offers to stop requesting permission."
width="700" height="" id="permission-flow" />
<p class="img-caption">
  <strong>Figure 9.</strong> Offering not to show the permission-request screen anymore.

<h2 id="services">Permissions for Services</h2>

<p>As mentioned above, only an activity can call the
{@link android.support.v4.app.ActivityCompat#requestPermissions requestPermissions()}
method, so if the user interacts with your app via a service,
for example a watch face, the service must open a background activity before requesting
the permission. This activity could provide additional education, or it could simply
be an invisible activity that brings up the system dialog.</p>

<p>If your wearable app runs a service that is not a watch face, and the user does not launch
an app in which it might make sense to request a permission,
you can post an educational notification on the wearable. The notification can
provide an action to open an activity that then triggers the system permissions
dialog.</p>

<p class="note"><strong>Note:</strong> This is the only acceptable use of a stream notification
for permissions requests.</p>

<img src="{@docRoot}images/training/wear/for_services.png"
srcset="{@docRoot}images/training/wear/for_services.png 1x,
{@docRoot}images/training/wear/for_services_2x.png 2x"
alt="The user may need to grant a permission when indirectly interacting with an app, via a
service."
width="700" height="" id="permission-flow" />
<p class="img-caption">
  <strong>Figure 10.</strong> A service requesting permission.

<h2 id="settings">Settings</h2>

<p>As with the handset, the user can change a Wear app’s permissions in Settings at any time.
Therefore, when the user tries to do something that requires a
permission, the app should always first call the
{@link android.support.v4.content.ContextCompat#checkSelfPermission(android.content.Context,java.lang.String) checkSelfPermission()}
method to see if the app currently has permission to perform this operation. The app should perform
this check even if it knows the user has previously granted that permission, since the
user might have subsequently revoked that permission.</p>

<img src="{@docRoot}images/training/wear/for_settings.png"
srcset="{@docRoot}images/training/wear/for_settings.png 1x,
{@docRoot}images/training/wear/for_settings_2x.png 2x"
alt="The user can change permissions through the Settings app."
width="700" height="" id="permission-flow" />
<p class="img-caption">
  <strong>Figure 11.</strong> Changing settings via the Settings app.