summaryrefslogtreecommitdiffstats
path: root/docs/html/guide/topics/manifest/uses-permission-element.jd
blob: 939411406e36962cca9ecc22b35d91e886de283a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
page.title=<uses-permission>
parent.title=The AndroidManifest.xml File
parent.link=manifest-intro.html
@jd:body

<dl class="xml">

<div class="sidebox-wrapper"> 
<div class="sidebox">
<img src="{@docRoot}assets/images/icon_play.png" style="float:left;margin:0;padding:0;"> 
<p style="color:#669999;padding-top:1em;">Google Play Filtering</p> 

<p style="clear:left;">In some cases, the permissions that you request
through <code>&lt;uses-permission&gt;</code> can affect how
your application is filtered by Google Play.</p>

<p>If you request a hardware-related permission &mdash;
<code>CAMERA</code>, for example &mdash; Google Play assumes that your
application requires the underlying hardware feature and filters the application
from devices that do not offer it.</p>

<p>To control filtering, always explicitly declare
hardware features in <code>&lt;uses-feature&gt;</code> elements, rather than
relying on Google Play to "discover" the requirements in
<code>&lt;uses-permission&gt;</code> elements. Then, if you want to disable
filtering for a particular feature, you can add a
<code>android:required="false"</code> attribute to the
<code>&lt;uses-feature&gt;</code> declaration.</p>

<p>For a list of permissions that imply
hardware features, see the documentation for the <a
href="{@docRoot}guide/topics/manifest/uses-feature-element.html#permissions-features">
<code>&lt;uses-feature&gt;</code></a> element.</p>
</div>
</div>

<dt>syntax:</dt>
<dd><pre class="stx">&lt;uses-permission android:<a href="#nm">name</a>="<i>string</i>"
        android:<a href="#maxSdk">maxSdkVersion</a>="<i>integer</i>" /&gt;</pre></dd>

<dt>contained in:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code></dd>

<dt>description:</dt>
<dd itemprop="description">Requests a permission that the application must be granted in
order for it to operate correctly.  Permissions are granted by the user when the 
application is installed, not while it's running.

<p>
For more information on permissions, see the 
<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#perms">Permissions</a></code> 
section in the introduction and the separate 
<a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a> document.  
A list of permissions defined by the base platform can be found at 
{@link android.Manifest.permission android.Manifest.permission}.

<dt>attributes:</dt>
<dd><dl class="attr">
<dt><a name="nm"></a>{@code android:name}</dt>
<dd>The name of the permission.  It can be a permission defined by the 
application with the <code><a href="{@docRoot}guide/topics/manifest/permission-element.html">&lt;permission&gt;</a></code> 
element, a permission defined by another application, or one of the 
standard system permissions, such as "{@code android.permission.CAMERA}" 
or "{@code android.permission.READ_CONTACTS}".  As these examples show, 
a permission name typically includes the package name as a prefix.</dd>

<dt><a name="maxSdk"></a>{@code android:maxSdkVersion}</dt>
<dd>The highest API level at which this permission should be granted to your app.
Setting this attribute is useful if the permission your app requires is no longer needed beginning
at a certain API level.
<p>For example, beginning with Android 4.4 (API level 19), it's no longer necessary for your app
to request the {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} permission when your
app wants to write to its own application-specific directories on external storage (the directories
provided by {@link android.content.Context#getExternalFilesDir getExternalFilesDir()}). However,
the permission <em>is required</em> for API level 18 and lower. So you can declare that this
permission is needed only up to API level 18 with a declaration such as this:
<pre>
&lt;uses-permission
     android:name="android.permission.WRITE_EXTERNAL_STORAGE"
     android:maxSdkVersion="18" />
</pre>
<p>This way, beginning with API level 19, the system will no longer grant your app the
{@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} permission.</p>
</dd>

</dl></dd>

<!-- ##api level indication## -->
<dt>introduced in:</dt>
<dd>API Level 1</dd>

<dt>see also:</dt>
<dd>
<ul>
  <li><code><a href="{@docRoot}guide/topics/manifest/permission-element.html">&lt;permission&gt;</a></code></li>
  <li><code><a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">&lt;uses-feature&gt;</a></code></li>
</ul>
</dd>

</dl>