Todo projeto de app precisa ter um arquivo AndroidManifest.xml
, com esse nome
exato,
na raiz do conjunto de origem do projeto.
O arquivo de manifesto descreve informações essenciais sobre o app
para as ferramentas de build do Android, para o sistema operacional Android e para o
Google Play.
Entre muitas outras coisas, o arquivo de manifesto precisa declarar os itens abaixo:
- Os componentes do app, incluindo todas as atividades, serviços, broadcast receivers e provedores de conteúdo. Cada componente precisa definir propriedades básicas como o nome da classe Kotlin ou Java. Além disso, é possível declarar recursos, como quais configurações de dispositivo podem ser processadas e os filtros de intents que descrevem a forma de inicialização do componente. Leia mais sobre os componentes do app em uma seção abaixo.
- As permissões que o app precisa ter para acessar partes protegidas do sistema ou de outros apps. Também declare todas as permissões que outros apps precisam ter para acessar conteúdo desse app. Leia mais sobre permissões em uma seção abaixo.
- Os recursos de hardware e software exigidos pelo app, que afetam quais dispositivos podem instalar o app pelo Google Play. Leia mais sobre a compatibilidade do dispositivo em uma seção abaixo.
Se você estiver usando o Android Studio para criar o app, o arquivo de manifesto vai ser criado para você, e a maioria dos elementos essenciais do manifesto vai ser adicionada durante a criação, principalmente ao usar modelos de código.
Recursos de arquivo
As seções abaixo descrevem como algumas das características mais importantes do app são refletidas no arquivo de manifesto.
Componentes do app
Para cada componente de app que é criado nele, declare um elemento XML correspondente no arquivo de manifesto:
<activity>
para cada subclasse deActivity
.<service>
para cada subclasse deService
.<receiver>
para cada subclasse deBroadcastReceiver
.<provider>
para cada subclasse deContentProvider
.
Se você subclassificar algum desses componentes sem declará-lo no arquivo de manifesto, o sistema não poderá iniciá-lo.
Especifique o nome da sua subclasse com o atributo
name
usando a designação completa do pacote. Por exemplo, uma subclasse
Activity
é declarada desta forma:
<manifest ... > <application ... > <activity android:name="com.example.myapp.MainActivity" ... > </activity> </application> </manifest>
No entanto, se o primeiro caractere no valor name
for um ponto,
o namespace do app, da propriedade namespace
do arquivo build.gradle
no nível do módulo,
será prefixado ao nome. Por exemplo, se o namespace for
"com.example.myapp"
, o nome da atividade abaixo será resolvido como
com.example.myapp.MainActivity
:
<manifest ... > <application ... > <activity android:name=".MainActivity" ... > ... </activity> </application> </manifest>
Para mais informações sobre a definição do nome do pacote ou namespace, consulte Definir o namespace.
Caso você tenha componentes de app que estejam localizados em subpacotes, como em
com.example.myapp.purchases
, o valor name
precisa adicionar os nomes
dos subpacotes que estão faltando, como ".purchases.PayActivity"
, ou usar o
nome do pacote totalmente qualificado.
Filtros de intent
As atividades do app, os serviços e os broadcast
receivers são ativados pelas intents. A intent é uma mensagem definida por
um objeto Intent
que descreve uma
ação a ser realizada, incluindo dados usados em ações, a categoria do
componente que vai executar a ação e outras instruções.
Quando um app envia uma intent ao sistema, ele localiza um componente do
app que pode processar a intent com base nas declarações do filtro de intents
do arquivo de manifesto do app. O sistema lança
uma instância do componente correspondente e transmite o objeto Intent
a esse componente. Caso mais de um app possa
processar a intent, o usuário poderá escolher qual usar.
Um componente do app pode ter vários filtros de intents (definidos com o
elemento
<intent-filter>
), cada um descrevendo um recurso diferente do componente.
Para saber mais, consulte o documento Intents e filtros de intents.
Ícones e rótulos
Diversos elementos do manifesto têm atributos icon
e label
para mostrar, respectivamente, um pequeno ícone e um rótulo de texto
aos usuários para o componente do app correspondente.
Em todos os casos, o ícone e o rótulo definidos em um elemento pai se tornam os valores
icon
e label
padrão para todos os elementos filhos.
Por exemplo, o ícone e o rótulo definidos no elemento
<application>
são o padrão para todos os componentes do app, como todas as atividades.
O ícone e o rótulo definidos no
<intent-filter>
do componente são mostrados ao usuário sempre que o componente é apresentado como opção
de preenchimento de uma intent. Por padrão, esse ícone é herdado de
qualquer ícone declarado para o componente pai, o elemento
<activity>
ou
<application>
.
É possível mudar o ícone de um filtro de intent se ele fornecer uma ação exclusiva que você queira indicar melhor na caixa de diálogo de escolha. Para mais informações, consulte Como permitir que outros apps iniciem sua atividade.
Permissões
Os apps Android precisam pedir acesso aos dados confidenciais do usuário, como contatos e SMS, ou determinados recursos do sistema, como a câmera e o acesso à Internet. Cada permissão é identificada por um rótulo exclusivo. Por exemplo, um app que precisa enviar mensagens SMS precisa ter esta linha no manifesto:
<manifest ... > <uses-permission android:name="android.permission.SEND_SMS"/> ... </manifest>
No
Android 6.0 (nível 23 da API) e versões mais recentes, o usuário pode aprovar ou rejeitar algumas permissões do app durante a execução. Mas,
seja qual for a versão do Android em que o app pode ser usado, é necessário declarar todas as solicitações de permissões com um elemento
<uses-permission>
no manifesto. Se a permissão for concedida, o app será capaz de usar os recursos
protegidos. Caso contrário, a tentativa de acessar esses recursos falhará.
Seu app também pode proteger os próprios componentes com permissões. Ele pode usar
qualquer uma das permissões definidas pelo Android, conforme listado em
android.Manifest.permission
, ou uma permissão
declarada em outro app. Seu app também pode definir as próprias permissões.
As novas permissões são declaradas com o
elemento
<permission>
.
Para mais informações, consulte Permissões no Android.
Compatibilidade do dispositivo
O arquivo de manifesto também é onde você pode declarar quais são os tipos de recursos de hardware ou software exigidos pelo app e, por extensão, com quais tipos de dispositivo ele é compatível. A Google Play Store não permite que os usuários instalem seu app em dispositivos que não oferecem os recursos ou a versão do sistema exigidos.
Há várias tags de manifesto que definem com quais dispositivos o app tem compatibilidade. Confira abaixo algumas das mais usadas.
<uses-feature>
O elemento
<uses-feature>
permite que você declare os recursos de hardware e
software de que o app precisa. Por exemplo, se o app não consegue realizar funcionalidades
básicas em um dispositivo que não tenha um sensor de bússola, é possível declarar o sensor
como obrigatório com esta tag de manifesto:
<manifest ... > <uses-feature android:name="android.hardware.sensor.compass" android:required="true" /> ... </manifest>
Observação: se você quiser disponibilizar o app em Chromebooks, há algumas limitações importantes de recursos de hardware e software que precisam ser consideradas. Para mais informações, consulte Compatibilidade do manifesto do app para Chromebooks.
<uses-sdk>
Cada nova versão da plataforma geralmente adiciona novas APIs que não
estavam disponíveis na versão anterior. Para indicar a versão mínima compatível com o app,
o manifesto precisa incluir a tag <uses-sdk>
e o atributo
minSdkVersion
.
No entanto, não se esqueça de que os atributos no elemento <uses-sdk>
são substituídos pelas propriedades correspondentes
no arquivo build.gradle
.
Se você estiver usando o Android Studio, especifique os valores minSdkVersion
e
targetSdkVersion
:
Groovy
android { defaultConfig { applicationId 'com.example.myapp' // Defines the minimum API level required to run the app. minSdkVersion 21 // Specifies the API level used to test the app. targetSdkVersion 33 ... } }
Kotlin
android { defaultConfig { applicationId = "com.example.myapp" // Defines the minimum API level required to run the app. minSdkVersion(21) // Specifies the API level used to test the app. targetSdkVersion(33) ... } }
Para mais informações sobre o arquivo build.gradle
, consulte como configurar seu build.
Para saber mais sobre como declarar o suporte do app para diferentes dispositivos, consulte a Visão geral da compatibilidade do dispositivo.
Convenções de arquivo
Esta seção descreve as convenções e regras que se aplicam geralmente a todos os elementos e atributos no arquivo de manifesto.
- Elementos
- Só são obrigatórios os elementos
<manifest>
e<application>
. Ambos devem ocorrer somente uma vez. A maioria dos outros elementos pode ocorrer zero ou mais vezes. No entanto, alguns deles precisam estar presentes para tornar o arquivo de manifesto útil.Todos os valores são definidos por atributos, e não como dados de caracteres dentro de um elemento.
Elementos de mesmo nível geralmente não são ordenados. Por exemplo, os elementos
<activity>
,<provider>
, e<service>
podem ser posicionados em qualquer ordem. Há duas exceções principais a essa regra:-
Um elemento
<activity-alias>
precisa seguir a<activity>
de quem ele é um alias. -
O elemento
<application>
precisa ser o último elemento dentro do elemento<manifest>
.
-
Um elemento
- Atributos
- Tecnicamente, os atributos são opcionais. No entanto, muitos deles
precisam ser especificados para que um elemento possa cumprir sua finalidade.
Para atributos realmente opcionais, consulte a documentação de referência
que indica os valores padrão.
Exceto por alguns atributos do elemento
<manifest>
raiz, todos os nomes de atributo começam com o prefixoandroid:
, comoandroid:alwaysRetainTaskState
. Como o prefixo é universal, a documentação geralmente o omite ao se referir a atributos pelo nome. - Vários valores
- Se mais de um valor for especificado, o elemento sempre será
repetido em vez de listar os vários valores dentro de um único elemento.
Por exemplo, um filtro de intents pode listar algumas ações:
<intent-filter ... > <action android:name="android.intent.action.EDIT" /> <action android:name="android.intent.action.INSERT" /> <action android:name="android.intent.action.DELETE" /> ... </intent-filter>
- Valores de recurso
- Alguns atributos têm valores que são exibidos aos usuários, como o
título de uma atividade ou o ícone do app. O valor desses atributos pode
divergir de acordo com o idioma do usuário ou outras configurações de dispositivos. Por exemplo, para
fornecer um tamanho de ícone diferente com base na densidade de pixel do dispositivo. Os
valores podem ser definidos com um recurso ou tema, em vez de serem codificados no
arquivo de manifesto. O valor real pode mudar com base nos recursos
alternativos fornecidos para diferentes configurações de dispositivos.
Os recursos são expressados como valores com o formato a seguir:
"@[package:]type/name"
É possível omitir o nome do package se o recurso for fornecido pelo app, inclusive se ele for fornecido por uma dependência de biblioteca, porque os recursos da biblioteca são mesclados aos seus. Quando você quiser usar um recurso do framework do Android, o único nome de pacote válido será
android
.O type é um tipo de recurso, como
string
oudrawable
, e name é o nome que identifica o recurso específico. Confira um exemplo:<activity android:icon="@drawable/smallPic" ... >
Para mais informações sobre como adicionar recursos ao projeto, leia Visão geral dos recursos de app.
Para aplicar um valor definido em um tema, o primeiro caractere precisa ser
?
em vez de@
:"?[package:]type/name"
- Valores de string
- Quando um valor do atributo é uma string, é preciso usar barras invertidas duplas
(
\\
) para caracteres de escape, como\\n
para uma nova linha ou\\uxxxx
para um caractere Unicode.
Referência de elementos do manifesto
A tabela abaixo fornece links para os documentos de referência para todos os elementos
válidos no arquivo AndroidManifest.xml
.
<action> |
Adiciona uma ação a um filtro de intents. |
<activity> |
Declara um componente da atividade. |
<activity-alias> |
Declara um alias para a atividade. |
<application> |
Declara o aplicativo. |
<category> |
Adiciona um nome de categoria a um filtro de intents. |
<compatible-screens> |
Especifica cada configuração de tela com que o aplicativo é compatível. |
<data> |
Adiciona uma especificação de dados a um filtro de intents. |
<grant-uri-permission> |
Especifica os subconjuntos de dados do app aos quais o provedor de conteúdo pai tem permissão de acesso. |
<instrumentation> |
Instrumentation Declara uma classe que permite
monitorar a interação de um aplicativo com o sistema. |
<intent-filter> |
Especifica os tipos de intents aos quais uma atividade, um serviço ou um broadcast receiver pode responder. |
<manifest> |
O elemento raiz do arquivo AndroidManifest.xml . |
<meta-data> |
Um par de nome-valor para um item de dados extra e arbitrários que pode ser fornecido ao componente pai. |
<path-permission> |
Define o caminho e as permissões necessárias para um subconjunto específico de dados em um provedor de conteúdo. |
<permission> |
Declara uma permissão de segurança que pode ser usada para limitar o acesso a componentes ou recursos específicos deste ou de outros aplicativos. |
<permission-group> |
Declara um nome para um agrupamento lógico de permissões relacionadas. |
<permission-tree> |
Declara o nome base de uma árvore de permissões. |
<provider> |
Declara o componente de um provedor de conteúdo. |
<queries> |
Declara o conjunto de outros apps que seu app pretende acessar. Saiba mais no guia sobre filtragem de visibilidade de pacotes. |
<receiver> |
Declara um componente do broadcast receiver. |
<service> |
Declara um componente de serviço. |
<supports-gl-texture>
| Declara um único formato de compactação de textura GL que pode ser usado com o app. |
<supports-screens> |
Declara os tamanhos de tela com suporte do app e ativa o modo de compatibilidade da tela para telas maiores do que as com suporte. |
<uses-configuration> |
Indica os recursos de entrada específicos exigidos pelo aplicativo. |
<uses-feature> |
Declara um único recurso de hardware ou software usado pelo aplicativo. |
<uses-library> |
Especifica uma biblioteca compartilhada que precisa ser vinculada ao aplicativo. |
<uses-native-library> |
Especifica uma biblioteca compartilhada nativa oferecida pelo fornecedor que precisa ser vinculada ao app. |
<uses-permission> |
Especifica uma permissão do sistema que precisa ser concedida pelo usuário para que o app funcione corretamente. |
<uses-permission-sdk-23> |
Especifica que um app quer uma permissão específica, mas somente se o app estiver instalado em um dispositivo com Android 6.0 (nível 23 da API) ou mais recente. |
<uses-sdk> |
Permite expressar a compatibilidade de um aplicativo com uma ou mais versões da plataforma Android usando um número inteiro de nível de API. |
Limites
As seguintes tags têm um limite para o número de ocorrências em um arquivo de manifesto:
Nome da tag | Limite |
---|---|
<package> |
1000 |
<meta-data> |
1000 |
<uses-library> |
1000 |
Os seguintes atributos têm um limite de comprimento máximo:
Atributo | Limite |
---|---|
name |
1024 |
versionName |
1024 |
host |
255 |
mimeType |
255 |
Exemplo de arquivo de manifesto
O XML abaixo é um exemplo simples de AndroidManifest.xml
que declara
duas atividades para o app.
<?xml version="1.0" encoding="utf-8"?>
<manifest
xmlns:android="http://schemas.android.com/apk/res/android"
android:versionCode="1"
android:versionName="1.0">
<!-- Beware that these values are overridden by the build.gradle file -->
<uses-sdk android:minSdkVersion="15" android:targetSdkVersion="26" />
<application
android:allowBackup="true"
android:icon="@mipmap/ic_launcher"
android:roundIcon="@mipmap/ic_launcher_round"
android:label="@string/app_name"
android:supportsRtl="true"
android:theme="@style/AppTheme">
<!-- This name is resolved to com.example.myapp.MainActivity
based on the namespace property in the build.gradle file -->
<activity android:name=".MainActivity">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
<activity
android:name=".DisplayMessageActivity"
android:parentActivityName=".MainActivity" />
</application>
</manifest>