blob: 851674c0f78050cb779ab010cf4a753b22b3fbf4 [file] [log] [blame]
page.title=App Manifest
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<li><a href="#filestruct">Manifest file structure</a></li>
<li><a href="#filec">File conventions</a>
<li><a href="#filef">File features</a>
<li><a href="#ifs">Intent filters</a></li>
<li><a href="#iconlabel">Icons and labels</a></li>
<li><a href="#perms">Permissions</a></li>
<li><a href="#libs">Libraries</a></li>
Every application must have an {@code AndroidManifest.xml} file (with precisely that
name) in its root directory. <span itemprop="description">The manifest file
provides essential information about your app to the Android system, which
the system must have before it can run any of the app's
Among other things, the manifest file does the following:
<li>It names the Java package for the application.
The package name serves as a unique identifier for the application.</li>
<li>It describes the components of the application, which include the activities,
services, broadcast receivers, and content providers that compose the application.
It also names the classes that implement each of the components and
publishes their capabilities, such as the {@link android.content.Intent
Intent} messages that they can handle. These declarations inform the Android system
of the components and the conditions in which they can be launched.</li>
<li>It determines the processes that host the application components.</li>
<li>It declares the permissions that the application must have in order to
access protected parts of the API and interact with other applications. It also declares
the permissions that others are required to have in
order to interact with the application's components.</li>
<li>It lists the {@link} classes that provide
profiling and other information as the application runs. These declarations
are present in the manifest only while the application is being developed and
are removed before the application is published.</li>
<li>It declares the minimum level of the Android API that the application
<li>It lists the libraries that the application must be linked against.</li>
<p class="note"><strong>Note</strong>: As you prepare your Android app to run on Chromebooks,
there are some important hardware and software feature limitations that you should consider. See
the <a href="{@docRoot}topic/arc/manifest.html">
App Manifest Compatibility for Chromebooks</a> document for more information.
<h2 id="filestruct">Manifest file structure</h2>
The code snippet below shows the general structure of the manifest file and
every element that it can contain. Each element, along with all of its
attributes, is fully documented in a separate file.
<p class="note"><strong>Tip</strong>: To view detailed
information about any of the elements that are mentioned within the text of this document,
simply click the element name.
Here is an example of the manifest file:
&lt;?xml version="1.0" encoding="utf-8"?&gt;
<a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a>
<a href="{@docRoot}guide/topics/manifest/uses-permission-element.html">&lt;uses-permission /&gt;</a>
<a href="{@docRoot}guide/topics/manifest/permission-element.html">&lt;permission /&gt;</a>
<a href="{@docRoot}guide/topics/manifest/permission-tree-element.html">&lt;permission-tree /&gt;</a>
<a href="{@docRoot}guide/topics/manifest/permission-group-element.html">&lt;permission-group /&gt;</a>
<a href="{@docRoot}guide/topics/manifest/instrumentation-element.html">&lt;instrumentation /&gt;</a>
<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">&lt;uses-sdk /&gt;</a>
<a href="{@docRoot}guide/topics/manifest/uses-configuration-element.html">&lt;uses-configuration /&gt;</a> <!-- ##api level 3## -->
<a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">&lt;uses-feature /&gt;</a> <!-- ##api level 4## -->
<a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">&lt;supports-screens /&gt;</a> <!-- ##api level 4## -->
<a href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">&lt;compatible-screens /&gt;</a> <!-- ##api level 9## -->
<a href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html">&lt;supports-gl-texture /&gt;</a> <!-- ##api level 11## -->
<a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a>
<a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a>
<a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a>
<a href="{@docRoot}guide/topics/manifest/action-element.html">&lt;action /&gt;</a>
<a href="{@docRoot}guide/topics/manifest/category-element.html">&lt;category /&gt;</a>
<a href="{@docRoot}guide/topics/manifest/data-element.html">&lt;data /&gt;</a>
<a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;/intent-filter&gt;</a>
<a href="{@docRoot}guide/topics/manifest/meta-data-element.html">&lt;meta-data /&gt;</a>
<a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;/activity&gt;</a>
<a href="{@docRoot}guide/topics/manifest/activity-alias-element.html">&lt;activity-alias&gt;</a>
<a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a> . . . <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;/intent-filter&gt;</a>
<a href="{@docRoot}guide/topics/manifest/meta-data-element.html">&lt;meta-data /&gt;</a>
<a href="{@docRoot}guide/topics/manifest/activity-alias-element.html">&lt;/activity-alias&gt;</a>
<a href="{@docRoot}guide/topics/manifest/service-element.html">&lt;service&gt;</a>
<a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a> . . . <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;/intent-filter&gt;</a>
<a href="{@docRoot}guide/topics/manifest/meta-data-element.html">&lt;meta-data/&gt;</a>
<a href="{@docRoot}guide/topics/manifest/service-element.html">&lt;/service&gt;</a>
<a href="{@docRoot}guide/topics/manifest/receiver-element.html">&lt;receiver&gt;</a>
<a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a> . . . <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;/intent-filter&gt;</a>
<a href="{@docRoot}guide/topics/manifest/meta-data-element.html">&lt;meta-data /&gt;</a>
<a href="{@docRoot}guide/topics/manifest/receiver-element.html">&lt;/receiver&gt;</a>
<a href="{@docRoot}guide/topics/manifest/provider-element.html">&lt;provider&gt;</a>
<a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html">&lt;grant-uri-permission /&gt;</a>
<a href="{@docRoot}guide/topics/manifest/meta-data-element.html">&lt;meta-data /&gt;</a>
<a href="{@docRoot}guide/topics/manifest/path-permission-element.html">&lt;path-permission /&gt;</a>
<a href="{@docRoot}guide/topics/manifest/provider-element.html">&lt;/provider&gt;</a>
<a href="{@docRoot}guide/topics/manifest/uses-library-element.html">&lt;uses-library /&gt;</a>
<a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;/application&gt;</a>
<a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;/manifest&gt;</a>
The following list contains all of the elements that can appear in the manifest file,
in alphabetical order:
<li><code><a href="{@docRoot}guide/topics/manifest/action-element.html">&lt;action&gt;</a></code></li>
<li><code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code></li>
<li><code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html">&lt;activity-alias&gt;</a></code></li>
<li><code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code></li>
<li><code><a href="{@docRoot}guide/topics/manifest/category-element.html">&lt;category&gt;</a></code></li>
<li><code><a href="{@docRoot}guide/topics/manifest/data-element.html">&lt;data&gt;</a></code></li>
<li><code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html">&lt;grant-uri-permission&gt;</a></code></li>
<li><code><a href="{@docRoot}guide/topics/manifest/instrumentation-element.html">&lt;instrumentation&gt;</a></code></li>
<li><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code></li>
<li><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code></li>
<li><code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html">&lt;meta-data&gt;</a></code></li>
<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/permission-group-element.html">&lt;permission-group&gt;</a></code></li>
<li><code><a href="{@docRoot}guide/topics/manifest/permission-tree-element.html">&lt;permission-tree&gt;</a></code></li>
<li><code><a href="{@docRoot}guide/topics/manifest/provider-element.html">&lt;provider&gt;</a></code></li>
<li><code><a href="{@docRoot}guide/topics/manifest/receiver-element.html">&lt;receiver&gt;</a></code></li>
<li><code><a href="{@docRoot}guide/topics/manifest/service-element.html">&lt;service&gt;</a></code></li>
<li><code><a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">&lt;supports-screens&gt;</a></code> <!-- ##api level 4## --></li>
<li><code><a href="{@docRoot}guide/topics/manifest/uses-configuration-element.html">&lt;uses-configuration&gt;</a></code> <!-- ##api level 3## --></li>
<li><code><a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">&lt;uses-feature&gt;</a></code> <!-- ##api level 4## --></li>
<li><code><a href="{@docRoot}guide/topics/manifest/uses-library-element.html">&lt;uses-library&gt;</a></code></li>
<li><code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html">&lt;uses-permission&gt;</a></code></li>
<li><code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">&lt;uses-sdk&gt;</a></code></li>
<p class="note"><strong>Note</strong>: These are the only legal elements &ndash; you cannot
add your own elements or attributes.
<h2 id="filec">File conventions</h2>
This section describes the conventions and rules that apply generally to all of the elements and
attributes in the manifest file.
<dd>Only the
<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code> and
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
elements are required. They each must be present and can occur only once.
Most of the other elements can occur many times or not at all. However, at
least some of them must be present before the manifest file becomes useful.
If an element contains anything at all, it contains other elements.
All of the values are set through attributes, not as character data within an element.
Elements at the same level are generally not ordered. For example, the
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code>,
<code><a href="{@docRoot}guide/topics/manifest/provider-element.html">&lt;provider&gt;</a></code>, and
<code><a href="{@docRoot}guide/topics/manifest/service-element.html">&lt;service&gt;</a></code>
elements can be intermixed in any sequence. There are two key exceptions to this
An <code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html">&lt;activity-alias&gt;</a></code>
element must follow the
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code>
for which it is an alias.
The <code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
element must be the last element inside the
<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code>
element. In other words, the <code>&lt;/application&gt;</code> closing tag
must appear immediately before the <code>&lt;/manifest&gt;</code> closing
<dd>In a formal sense, all attributes are optional. However, there are some attributes
that must be specified so that an element can accomplish its purpose. Use the
documentation as a guide. For truly optional attributes, it mentions a default
value or states what happens in the absence of a specification.
<p>Except for some attributes of the root
<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code>
element, all attribute names begin with an {@code android:} prefix.
For example, {@code android:alwaysRetainTaskState}. Because the prefix is
universal, the documentation generally omits it when referring to attributes
by name.</p></dd>
<dt><b>Declaring class names</b></dt>
<dd>Many elements correspond to Java objects, including elements for the
application itself (the
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
element) and its principal components: activities
(<code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code>),
(<code><a href="{@docRoot}guide/topics/manifest/service-element.html">&lt;service&gt;</a></code>),
broadcast receivers
(<code><a href="{@docRoot}guide/topics/manifest/receiver-element.html">&lt;receiver&gt;</a></code>),
and content providers
(<code><a href="{@docRoot}guide/topics/manifest/provider-element.html">&lt;provider&gt;</a></code>).
If you define a subclass, as you almost always would for the component classes
({@link}, {@link},
{@link android.content.BroadcastReceiver}, and {@link android.content.ContentProvider}),
the subclass is declared through a {@code name} attribute. The name must include
the full package designation.
For example, a {@link} subclass might be declared as follows:
<pre>&lt;manifest . . . &gt;
&lt;application . . . &gt;
&lt;service android:name="com.example.project.SecretService" . . . &gt;
. . .
. . .
However, if the first character of the string is a period, the
application's package name (as specified by the
<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code>
<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html#package">package</a></code>
attribute) is appended to the string. The following assignment is the same as that shown above:
<pre>&lt;manifest package="com.example.project" . . . &gt;
&lt;application . . . &gt;
&lt;service android:name=".SecretService" . . . &gt;
. . .
. . .
When starting a component, the Android system creates an instance of the named subclass.
If a subclass isn't specified, it creates an instance of the base class.
<dt><b>Multiple values</b></dt>
<dd>If more than one value can be specified, the element is almost always
repeated, rather than multiple values being listed within a single element.
For example, an intent filter can list several actions:
<pre>&lt;intent-filter . . . &gt;
&lt;action android:name="android.intent.action.EDIT" /&gt;
&lt;action android:name="android.intent.action.INSERT" /&gt;
&lt;action android:name="android.intent.action.DELETE" /&gt;
. . .
<dt><b>Resource values</b></dt>
<dd>Some attributes have values that can be displayed to users, such as
a label and an icon for an activity. The values of these attributes
should be localized and set from a resource or theme. Resource
values are expressed in the following format:</p>
<p style="margin-left: 2em">{@code @[<i>package</i>:]<i>type</i>/<i>name</i>}</p>
You can ommit the <i>package</i> name if the resource is in the same package
as the application. The <i>type</i> is a type of resource, such as <em>string</em> or
<em>drawable</em>, and the <i>name</i> is the name that identifies the specific resource.
Here is an example:
<pre>&lt;activity android:icon="@drawable/smallPic" . . . &gt</pre>
The values from a theme are expressed similarly, but with an initial {@code ?}
instead of {@code @}:
<p style="margin-left: 2em">{@code ?[<i>package</i>:]<i>type</i>/<i>name</i>}
<dt><b>String values</b></dt>
<dd>Where an attribute value is a string, you must use double backslashes ({@code \\})
to escape characters, such as {@code \\n} for
a newline or {@code \\uxxxx} for a Unicode character.</dd>
<h2 id="filef">File features</h2>
The following sections describe the way that some Android features are reflected
in the manifest file.
<h3 id="ifs">Intent filters</h3>
The core components of an application, such as its activities, services, and broadcast
receivers, are activated by <i>intents</i>. An intent is a
bundle of information (an {@link android.content.Intent} object) describing a
desired action, including the data to be acted upon, the category of
component that should perform the action, and other pertinent instructions.
The Android system locates an appropriate component that can respond to the intent, launches
a new instance of the component if one is needed, and passes it the
{@link android.content.Intent} object.
The components advertise the types of intents that they can
respond to through <i>intent filters</i>. Since the Android system
must learn the intents that a component can handle before it launches the component,
intent filters are specified in the manifest as
<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code>
elements. A component can have any number of filters, each one describing
a different capability.
An intent that explicitly names a target component activates that component, so
the filter doesn't play a role. An intent that doesn't specify a target by
name can activate a component only if it can pass through one of the component's
For information about how {@link android.content.Intent} objects are tested against intent filters,
see the <a href="{@docRoot}guide/components/intents-filters.html">Intents
and Intent Filters</a> document.
<h3 id="iconlabel">Icons and labels</h3>
A number of elements have {@code icon} and {@code label} attributes for a
small icon and a text label that can be displayed to users. Some also have a
{@code description} attribute for longer, explanatory text that can also be
shown on-screen. For example, the
<code><a href="{@docRoot}guide/topics/manifest/permission-element.html">&lt;permission&gt;</a></code>
element has all three of these attributes so that when the user is asked whether
to grant the permission to an application that has requested it, an icon representing
the permission, the name of the permission, and a description of what it
entails are all presented to the user.
In every case, the icon and label that are set in a containing element become the default
{@code icon} and {@code label} settings for all of the container's subelements.
Thus, the icon and label that are set in the
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
element are the default icon and label for each of the application's components.
Similarly, the icon and label that are set for a component, such as an
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code>
element, are the default settings for each of the component's
<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code>
elements. If an
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
element sets a label, but an activity and its intent filter do not,
the application label is treated as the label for both the activity and
the intent filter.
The icon and label that are set for an intent filter represent a component
whenever the component is presented to the user and fulfills the function
that is advertised by the filter. For example, a filter with
{@code android.intent.action.MAIN} and
{@code android.intent.category.LAUNCHER} settings advertises an activity
as one that initiates an application. That is, as
one that should be displayed in the application launcher. The icon and label
that are set in the filter are displayed in the launcher.
<h3 id="perms">Permissions</h3>
A <i>permission</i> is a restriction that limits access to a part of the code
or to data on the device. The limitation is imposed to protect critical
data and code that could be misused to distort or damage the user experience.
Each permission is identified by a unique label. Often the label indicates
the action that's restricted. Here are some permissions that are defined
by Android:
<li>{@code android.permission.CALL_EMERGENCY_NUMBERS}</li>
<li>{@code android.permission.READ_OWNER_DATA}</li>
<li>{@code android.permission.SET_WALLPAPER}</li>
<li>{@code android.permission.DEVICE_POWER}</li>
A feature can be protected by only one permission.
If an application needs access to a feature that is protected by a permission,
it must declare that it requires the permission with a
<code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html">&lt;uses-permission&gt;</a></code>
element in the manifest. When the application is installed on
the device, the installer determines whether to grant the requested
permission by checking the authorities that signed the application's
certificates and, in some cases, asking the user.
If the permission is granted, the application is able to use the protected
features. If not, its attempts to access those features fail
without any notification to the user.
An application can also protect its own components with permissions. It can employ
any of the permissions that are defined by Android, as listed in
{@link android.Manifest.permission android.Manifest.permission}, or declared
by other applications. It can also define its own. A new permission is declared
with the
<code><a href="{@docRoot}guide/topics/manifest/permission-element.html">&lt;permission&gt;</a></code>
element. For example, an activity could be protected as follows:
&lt;manifest . . . &gt;
&lt;permission android:name="com.example.project.DEBIT_ACCT" . . . /&gt;
&lt;uses-permission android:name="com.example.project.DEBIT_ACCT" /&gt;
. . .
&lt;application . . .&gt;
&lt;activity android:name="com.example.project.FreneticActivity"
. . . &gt;
. . .
Note that, in this example, the {@code DEBIT_ACCT} permission is not only
declared with the
<code><a href="{@docRoot}guide/topics/manifest/permission-element.html">&lt;permission&gt;</a></code>
element, its use is also requested with the
<code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html">&lt;uses-permission&gt;</a></code>
element. You must request its use in order for other components of the
application to launch the protected activity, even though the protection
is imposed by the application itself.
If, in the same example shown above, the {@code permission} attribute was set to a
permission that is declared elsewhere,
such as {@code android.permission.CALL_EMERGENCY_NUMBERS}, it would not
be necessary to declare it again with a
<code><a href="{@docRoot}guide/topics/manifest/permission-element.html">&lt;permission&gt;</a></code>
element. However, it would still be necessary to request its use with
<code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html">&lt;uses-permission&gt;</a></code>.
<code><a href="{@docRoot}guide/topics/manifest/permission-tree-element.html">&lt;permission-tree&gt;</a></code>
element declares a namespace for a group of permissions that are defined in
code, and the
<code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html">&lt;permission-group&gt;</a></code>
defines a label for a set of permissions, both those declared in the manifest with
<code><a href="{@docRoot}guide/topics/manifest/permission-element.html">&lt;permission&gt;</a></code>
elements and those declared elsewhere. This affects only how the permissions are
grouped when presented to the user. The
<code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html">&lt;permission-group&gt;</a></code>
element does not specify the permissions that belong to the group, but
it gives the group a name. You can place a permission in the group
by assigning the group name to the
<code><a href="{@docRoot}guide/topics/manifest/permission-element.html">&lt;permission&gt;</a></code>
<code><a href="{@docRoot}guide/topics/manifest/permission-element.html#pgroup">permissionGroup</a></code>
<h3 id="libs">Libraries</h3>
Every application is linked against the default Android library, which
includes the basic packages for building applications (with common classes
such as Activity, Service, Intent, View, Button, Application, and ContentProvider).
However, some packages reside in their own libraries. If your application
uses code from any of these packages, it must explicitly ask to be linked
against them. The manifest must contain a separate
<code><a href="{@docRoot}guide/topics/manifest/uses-library-element.html">&lt;uses-library&gt;</a></code>
element to name each of the libraries. You can find the library name in the
documentation for the package.