1page.title=App Manifest 2@jd:body 3 4<div id="qv-wrapper"> 5<div id="qv"> 6 7<h2>In this document</h2> 8<ol> 9<li><a href="#filestruct">Structure of the Manifest File</a></li> 10<li><a href="#filec">File Conventions</a> 11<li><a href="#filef">File Features</a> 12 <ol> 13 <li><a href="#ifs">Intent Filters</a></li> 14 <li><a href="#iconlabel">Icons and Labels</a></li> 15 <li><a href="#perms">Permissions</a></li> 16 <li><a href="#libs">Libraries</a></li> 17 </ol></li> 18</ol> 19</div> 20</div> 21 22<p> 23 Every application must have an AndroidManifest.xml file (with precisely that 24 name) in its root directory. <span itemprop="description">The manifest file 25 presents essential information about your app to the Android system, 26 information the system must have before it can run any of the app's 27 code.</span> Among other things, the manifest does the following: 28</p> 29 30<ul> 31<li>It names the Java package for the application. 32The package name serves as a unique identifier for the application.</li> 33 34<li>It describes the components of the application — the activities, 35services, broadcast receivers, and content providers that the application is 36composed of. It names the classes that implement each of the components and 37publishes their capabilities (for example, which {@link android.content.Intent 38Intent} messages they can handle). These declarations let the Android system 39know what the components are and under what conditions they can be launched.</li> 40 41<li>It determines which processes will host application components.</li> 42 43<li>It declares which permissions the application must have in order to 44access protected parts of the API and interact with other applications.</li> 45 46<li>It also declares the permissions that others are required to have in 47order to interact with the application's components.</li> 48 49<li>It lists the {@link android.app.Instrumentation} classes that provide 50profiling and other information as the application is running. These declarations 51are present in the manifest only while the application is being developed and 52tested; they're removed before the application is published.</li> 53 54<li>It declares the minimum level of the Android API that the application 55requires.</li> 56 57<li>It lists the libraries that the application must be linked against.</li> 58</ul> 59 60 61<h2 id="filestruct">Structure of the Manifest File</h2> 62 63<p> 64The diagram below shows the general structure of the manifest file and 65every element that it can contain. Each element, along with all of its 66attributes, is documented in full in a separate file. To view detailed 67information about any element, click on the element name in the diagram, 68in the alphabetical list of elements that follows the diagram, or on any 69other mention of the element name. 70</p> 71 72<pre> 73<?xml version="1.0" encoding="utf-8"?> 74 75<a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a> 76 77 <a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission /></a> 78 <a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission /></a> 79 <a href="{@docRoot}guide/topics/manifest/permission-tree-element.html"><permission-tree /></a> 80 <a href="{@docRoot}guide/topics/manifest/permission-group-element.html"><permission-group /></a> 81 <a href="{@docRoot}guide/topics/manifest/instrumentation-element.html"><instrumentation /></a> 82 <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk /></a> 83 <a href="{@docRoot}guide/topics/manifest/uses-configuration-element.html"><uses-configuration /></a> <!-- ##api level 3## --> 84 <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><uses-feature /></a> <!-- ##api level 4## --> 85 <a href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><supports-screens /></a> <!-- ##api level 4## --> 86 <a href="{@docRoot}guide/topics/manifest/compatible-screens-element.html"><compatible-screens /></a> <!-- ##api level 9## --> 87 <a href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html"><supports-gl-texture /></a> <!-- ##api level 11## --> 88 89 <a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a> 90 91 <a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a> 92 <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a> 93 <a href="{@docRoot}guide/topics/manifest/action-element.html"><action /></a> 94 <a href="{@docRoot}guide/topics/manifest/category-element.html"><category /></a> 95 <a href="{@docRoot}guide/topics/manifest/data-element.html"><data /></a> 96 <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"></intent-filter></a> 97 <a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data /></a> 98 <a href="{@docRoot}guide/topics/manifest/activity-element.html"></activity></a> 99 100 <a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a> 101 <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a> . . . <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"></intent-filter></a> 102 <a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data /></a> 103 <a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"></activity-alias></a> 104 105 <a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a> 106 <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a> . . . <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"></intent-filter></a> 107 <a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data/></a> 108 <a href="{@docRoot}guide/topics/manifest/service-element.html"></service></a> 109 110 <a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a> 111 <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a> . . . <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"></intent-filter></a> 112 <a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data /></a> 113 <a href="{@docRoot}guide/topics/manifest/receiver-element.html"></receiver></a> 114 115 <a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a> 116 <a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"><grant-uri-permission /></a> 117 <a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data /></a> 118 <a href="{@docRoot}guide/topics/manifest/path-permission-element.html"><path-permission /></a> 119 <a href="{@docRoot}guide/topics/manifest/provider-element.html"></provider></a> 120 121 <a href="{@docRoot}guide/topics/manifest/uses-library-element.html"><uses-library /></a> 122 123 <a href="{@docRoot}guide/topics/manifest/application-element.html"></application></a> 124 125<a href="{@docRoot}guide/topics/manifest/manifest-element.html"></manifest></a> 126</pre> 127 128<p> 129All the elements that can appear in the manifest file are listed below 130in alphabetical order. These are the only legal elements; you cannot 131add your own elements or attributes. 132</p> 133 134<p style="margin-left: 2em"> 135<code><a href="{@docRoot}guide/topics/manifest/action-element.html"><action></a></code> 136<br/><code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> 137<br/><code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a></code> 138<br/><code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 139<br/><code><a href="{@docRoot}guide/topics/manifest/category-element.html"><category></a></code> 140<br/><code><a href="{@docRoot}guide/topics/manifest/data-element.html"><data></a></code> 141<br/><code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"><grant-uri-permission></a></code> 142<br/><code><a href="{@docRoot}guide/topics/manifest/instrumentation-element.html"><instrumentation></a></code> 143<br/><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> 144<br/><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> 145<br/><code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data></a></code> 146<br/><code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> 147<br/><code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html"><permission-group></a></code> 148<br/><code><a href="{@docRoot}guide/topics/manifest/permission-tree-element.html"><permission-tree></a></code> 149<br/><code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> 150<br/><code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code> 151<br/><code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code> 152<br/><code><a href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><supports-screens></a></code> <!-- ##api level 4## --> 153<br/><code><a href="{@docRoot}guide/topics/manifest/uses-configuration-element.html"><uses-configuration></a></code> <!-- ##api level 3## --> 154<br/><code><a href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><uses-feature></a></code> <!-- ##api level 4## --> 155<br/><code><a href="{@docRoot}guide/topics/manifest/uses-library-element.html"><uses-library></a></code> 156<br/><code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code> 157<br/><code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a></code> 158</p> 159 160 161 162 163<h2 id="filec">File Conventions</h2> 164 165<p> 166Some conventions and rules apply generally to all elements and attributes 167in the manifest: 168</p> 169 170<dl> 171<dt><b>Elements</b></dt> 172<dd>Only the 173<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> and 174<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 175elements are required, they each must be present and can occur only once. 176Most of the others can occur many times or not at all — although at 177least some of them must be present for the manifest to accomplish anything 178meaningful. 179 180<p> 181If an element contains anything at all, it contains other elements. 182All values are set through attributes, not as character data within an element. 183</p> 184 185<p> 186Elements at the same level are generally not ordered. For example, 187<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>, 188<code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code>, and 189<code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code> 190elements can be intermixed in any sequence. There are two key exceptions to this 191rule, however: 192<ul> 193 <li> 194 An <code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a></code> 195 element must follow the 196 <code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> 197 it is an alias for. 198 </li> 199 <li> 200 The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 201 element must be the last element inside the 202 <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> 203 element. In other words, the <code></application></code> closing tag 204 must appear immediately before the <code></manifest></code> closing 205 tag. 206 </li> 207</p></dd> 208 209<dt><b>Attributes</b></dt> 210<dd>In a formal sense, all attributes are optional. However, there are some 211that must be specified for an element to accomplish its purpose. Use the 212documentation as a guide. For truly optional attributes, it mentions a default 213value or states what happens in the absence of a specification. 214 215<p>Except for some attributes of the root 216<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> 217element, all attribute names begin with an {@code android:} prefix — 218for example, {@code android:alwaysRetainTaskState}. Because the prefix is 219universal, the documentation generally omits it when referring to attributes 220by name.</p></dd> 221 222<dt><b>Declaring class names</b></dt> 223<dd>Many elements correspond to Java objects, including elements for the 224application itself (the 225<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 226element) and its principal components — activities 227(<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>), 228services 229(<code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code>), 230broadcast receivers 231(<code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code>), 232and content providers 233(<code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code>). 234 235<p> 236If you define a subclass, as you almost always would for the component classes 237({@link android.app.Activity}, {@link android.app.Service}, 238{@link android.content.BroadcastReceiver}, and {@link android.content.ContentProvider}), 239the subclass is declared through a {@code name} attribute. The name must include 240the full package designation. 241For example, an {@link android.app.Service} subclass might be declared as follows: 242</p> 243 244<pre><manifest . . . > 245 <application . . . > 246 <service android:name="com.example.project.SecretService" . . . > 247 . . . 248 </service> 249 . . . 250 </application> 251</manifest></pre> 252 253<p> 254However, as a shorthand, if the first character of the string is a period, the 255string is appended to the application's package name (as specified by the 256<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> 257element's 258<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html#package">package</a></code> 259attribute). The following assignment is the same as the one above: 260</p> 261 262<pre><manifest package="com.example.project" . . . > 263 <application . . . > 264 <service android:name=".SecretService" . . . > 265 . . . 266 </service> 267 . . . 268 </application> 269</manifest></pre> 270 271<p> 272When starting a component, Android creates an instance of the named subclass. 273If a subclass isn't specified, it creates an instance of the base class. 274</p></dd> 275 276<dt><b>Multiple values</b></dt> 277<dd>If more than one value can be specified, the element is almost always 278repeated, rather than listing multiple values within a single element. 279For example, an intent filter can list several actions: 280 281<pre><intent-filter . . . > 282 <action android:name="android.intent.action.EDIT" /> 283 <action android:name="android.intent.action.INSERT" /> 284 <action android:name="android.intent.action.DELETE" /> 285 . . . 286</intent-filter></pre></dd> 287 288<dt><b>Resource values</b></dt> 289<dd>Some attributes have values that can be displayed to users — for 290example, a label and an icon for an activity. The values of these attributes 291should be localized and therefore set from a resource or theme. Resource 292values are expressed in the following format,</p> 293 294<p style="margin-left: 2em">{@code @[<i>package</i>:]<i>type</i>/<i>name</i>}</p> 295 296<p> 297where the <i>package</i> name can be omitted if the resource is in the same package 298as the application, <i>type</i> is a type of resource — such as "string" or 299"drawable" — and <i>name</i> is the name that identifies the specific resource. 300For example: 301</p> 302 303<pre><activity android:icon="@drawable/smallPic" . . . ></pre> 304 305<p> 306Values from a theme are expressed in a similar manner, but with an initial '{@code ?}' 307rather than '{@code @}': 308</p> 309 310<p style="margin-left: 2em">{@code ?[<i>package</i>:]<i>type</i>/<i>name</i>} 311</p></dd> 312 313<dt><b>String values</b></dt> 314<dd>Where an attribute value is a string, double backslashes ('{@code \\}') 315must be used to escape characters — for example, '{@code \\n}' for 316a newline or '{@code \\uxxxx}' for a Unicode character.</dd> 317</dl> 318 319 320<h2 id="filef">File Features</h2> 321 322<p> 323The following sections describe how some Android features are reflected 324in the manifest file. 325</p> 326 327 328<h3 id="ifs">Intent Filters</h3> 329 330<p> 331The core components of an application (its activities, services, and broadcast 332receivers) are activated by <i>intents</i>. An intent is a 333bundle of information (an {@link android.content.Intent} object) describing a 334desired action — including the data to be acted upon, the category of 335component that should perform the action, and other pertinent instructions. 336Android locates an appropriate component to respond to the intent, launches 337a new instance of the component if one is needed, and passes it the 338Intent object. 339</p> 340 341<p> 342Components advertise their capabilities — the kinds of intents they can 343respond to — through <i>intent filters</i>. Since the Android system 344must learn which intents a component can handle before it launches the component, 345intent filters are specified in the manifest as 346<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> 347elements. A component may have any number of filters, each one describing 348a different capability. 349</p> 350 351<p> 352An intent that explicitly names a target component will activate that component; 353the filter doesn't play a role. But an intent that doesn't specify a target by 354name can activate a component only if it can pass through one of the component's 355filters. 356</p> 357 358<p> 359For information on how Intent objects are tested against intent filters, 360see a separate document, 361<a href="{@docRoot}guide/components/intents-filters.html">Intents 362and Intent Filters</a>. 363</p> 364 365 366<h3 id="iconlabel">Icons and Labels</h3> 367 368<p> 369A number of elements have {@code icon} and {@code label} attributes for a 370small icon and a text label that can be displayed to users. Some also have a 371{@code description} attribute for longer explanatory text that can also be 372shown on-screen. For example, the 373<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> 374element has all three of these attributes, so that when the user is asked whether 375to grant the permission to an application that has requested it, an icon representing 376the permission, the name of the permission, and a description of what it 377entails can all be presented to the user. 378</p> 379 380<p> 381In every case, the icon and label set in a containing element become the default 382{@code icon} and {@code label} settings for all of the container's subelements. 383Thus, the icon and label set in the 384<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 385element are the default icon and label for each of the application's components. 386Similarly, the icon and label set for a component — for example, an 387<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> 388element — are the default settings for each of the component's 389<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> 390elements. If an 391<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 392element sets a label, but an activity and its intent filter do not, 393the application label is treated as the label for both the activity and 394the intent filter. 395</p> 396 397<p> 398The icon and label set for an intent filter are used to represent a component 399whenever the component is presented to the user as fulfilling the function 400advertised by the filter. For example, a filter with 401"{@code android.intent.action.MAIN}" and 402"{@code android.intent.category.LAUNCHER}" settings advertises an activity 403as one that initiates an application — that is, as 404one that should be displayed in the application launcher. The icon and label 405set in the filter are therefore the ones displayed in the launcher. 406</p> 407 408 409<h3 id="perms">Permissions</h3> 410 411<p> 412A <i>permission</i> is a restriction limiting access to a part of the code 413or to data on the device. The limitation is imposed to protect critical 414data and code that could be misused to distort or damage the user experience. 415</p> 416 417<p> 418Each permission is identified by a unique label. Often the label indicates 419the action that's restricted. For example, here are some permissions defined 420by Android: 421</p> 422 423<p style="margin-left: 2em">{@code android.permission.CALL_EMERGENCY_NUMBERS} 424<br/>{@code android.permission.READ_OWNER_DATA} 425<br/>{@code android.permission.SET_WALLPAPER} 426<br/>{@code android.permission.DEVICE_POWER}</p> 427 428<p> 429A feature can be protected by at most one permission. 430</p> 431 432<p> 433If an application needs access to a feature protected by a permission, 434it must declare that it requires that permission with a 435<code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code> 436element in the manifest. Then, when the application is installed on 437the device, the installer determines whether or not to grant the requested 438permission by checking the authorities that signed the application's 439certificates and, in some cases, asking the user. 440If the permission is granted, the application is able to use the protected 441features. If not, its attempts to access those features will simply fail 442without any notification to the user. 443</p> 444 445<p> 446An application can also protect its own components (activities, services, 447broadcast receivers, and content providers) with permissions. It can employ 448any of the permissions defined by Android (listed in 449{@link android.Manifest.permission android.Manifest.permission}) or declared 450by other applications. Or it can define its own. A new permission is declared 451with the 452<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> 453element. For example, an activity could be protected as follows: 454</p> 455 456<pre> 457<manifest . . . > 458 <permission android:name="com.example.project.DEBIT_ACCT" . . . /> 459 <uses-permission android:name="com.example.project.DEBIT_ACCT" /> 460 . . . 461 <application . . .> 462 <activity android:name="com.example.project.FreneticActivity" 463 android:permission="com.example.project.DEBIT_ACCT" 464 . . . > 465 . . . 466 </activity> 467 </application> 468</manifest> 469</pre> 470 471<p> 472Note that, in this example, the {@code DEBIT_ACCT} permission is not only 473declared with the 474<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> 475element, its use is also requested with the 476<code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code> 477element. Its use must be requested in order for other components of the 478application to launch the protected activity, even though the protection 479is imposed by the application itself. 480</p> 481 482<p> 483If, in the same example, the {@code permission} attribute was set to a 484permission declared elsewhere 485(such as {@code android.permission.CALL_EMERGENCY_NUMBERS}, it would not 486have been necessary to declare it again with a 487<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> 488element. However, it would still have been necessary to request its use with 489<code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code>. 490</p> 491 492<p> 493The 494<code><a href="{@docRoot}guide/topics/manifest/permission-tree-element.html"><permission-tree></a></code> 495element declares a namespace for a group of permissions that will be defined in 496code. And 497<code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html"><permission-group></a></code> 498defines a label for a set of permissions (both those declared in the manifest with 499<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> 500elements and those declared elsewhere). It affects only how the permissions are 501grouped when presented to the user. The 502<code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html"><permission-group></a></code> 503element does not specify which permissions belong to the group; 504it just gives the group a name. A permission is placed in the group 505by assigning the group name to the 506<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> 507element's 508<code><a href="{@docRoot}guide/topics/manifest/permission-element.html#pgroup">permissionGroup</a></code> 509attribute. 510</p> 511 512 513<h3 id="libs">Libraries</h3> 514 515<p> 516Every application is linked against the default Android library, which 517includes the basic packages for building applications (with common classes 518such as Activity, Service, Intent, View, Button, Application, ContentProvider, 519and so on). 520</p> 521 522<p> 523However, some packages reside in their own libraries. If your application 524uses code from any of these packages, it must explicitly asked to be linked 525against them. The manifest must contain a separate 526<code><a href="{@docRoot}guide/topics/manifest/uses-library-element.html"><uses-library></a></code> 527element to name each of the libraries. (The library name can be found in the 528documentation for the package.) 529</p> 530