Visão geral do manifesto do aplicativo

Todo projeto de aplicativo precisa ter um arquivo AndroidManifest.xml (com esse exato nome) na raiz do conjunto de origem do projeto. O arquivo de manifesto descreve informações essenciais sobre o aplicativo para as ferramentas de compilação do Android, para o sistema operacional Android e para o Google Play.

Entre muitas outras coisas, o arquivo de manifesto precisa declarar os itens a seguir:

O nome do pacote do aplicativo, que normalmente corresponde ao namespace do seu código. Quando o projeto é criado, as ferramentas de compilação do Android usam esse dado para determinar o local das entidades do código. Ao empacotar o aplicativo, as ferramentas de compilação substituem esse valor pelo ID do aplicativo a partir dos arquivos de compilação do Gradle. Esse código é usado como o identificador exclusivo do aplicativo no sistema e no Google Play. Leia mais sobre o nome do pacote e o ID do aplicativo.
Os componentes do aplicativo, que incluem todos os serviços, broadcast receivers, provedores de conteúdo e atividades. Cada componente precisa definir propriedades básicas como o nome do Kotlin ou da classe do Java. Além disso, pode 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 aplicativo.
As permissões que o aplicativo precisa ter para acessar partes protegidas do sistema ou de outros aplicativos. Também declara todas as permissões que outros aplicativos precisam ter para acessar conteúdo desse aplicativo. Leia mais sobre permissões.
Os recursos de hardware e software exigidos pelo aplicativo, que afetam quais dispositivos podem instalar o aplicativo a partir do Google Play. Leia mais sobre a compatibilidade do dispositivo.

Se você estiver usando o Android Studio para criar o aplicativo, o arquivo de manifesto é criado para você, e a maioria dos elementos essenciais do manifesto é adicionada durante essa criação, principalmente ao usar modelos de código.

Recursos de arquivo

As seções a seguir descrevem como algumas das características mais importantes do aplicativo são refletidas no arquivo de manifesto.

Nome do pacote e ID do aplicativo

O elemento raiz do arquivo de manifesto exige um atributo para o nome do pacote do aplicativo (que normalmente corresponde à estrutura de diretório do projeto, o namespace do Java).

Por exemplo, o snippet a seguir mostra o elemento <manifest> raiz com o nome do pacote "com.example.myapp":

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.myapp"
    android:versionCode="1"
    android:versionName="1.0" >
    ...
</manifest>

Ao criar seu aplicativo no pacote de aplicativo (APK) final, as ferramentas de compilação do Android usam o atributo package para duas coisas:

Esse nome é aplicado como o namespace da classe R.java gerada do aplicativo, que é usado para acessar seus recursos de aplicativo.
Exemplo: com o manifesto acima, a classe R é criada em com.example.myapp.R.
Esse nome é usado para resolver todos os nomes de classes relativas declaradas no arquivo de manifesto.
Exemplo: com o manifesto acima, uma atividade declarada como <activity android:name=".MainActivity"> é resolvida como sendo com.example.myapp.MainActivity.

Assim, o nome no atributo package do manifesto precisa sempre corresponder ao nome do pacote básico do projeto em que você mantém as atividades e o restante do código do aplicativo. É claro que você pode ter outros subpacotes no projeto, mas esses arquivos precisam importar a classe R.java usando o namespace do atributo package.

No entanto, após a compilação do APK, o atributo package também representará o ID do aplicativo universalmente exclusivo do seu aplicativo. Após as tarefas acima serem realizadas pelas ferramentas de compilação com base no nome do package, o valor do package é substituído pelo valor determinado na property applicationId no arquivo build.gradle do seu projeto (usado nos projetos do Android Studio). Esse valor final do atributo package precisa ser universalmente exclusivo porque essa é a única forma garantida de identificar o aplicativo no Google Play e no sistema.

A diferença entre o nome do package no manifesto e o applicationId no arquivo build.gradle pode ser um tanto confusa. Mas, se você mantiver o mesmo nome, não há com o que se preocupar.

No entanto, se você quiser que o namespace do seu código (e, portanto, o nome do package no manifesto) seja diferente do applicationId do arquivo de compilação, verifique se entendeu completamente as implicações da configuração do ID do aplicativo. Essa página explica como ajustar o nome do package do manifesto de forma segura, independentemente da versão do applicationId do arquivo, e mudar o ID do aplicativo para outras configurações de compilação.

Componentes de aplicativo

Para cada componente de aplicativo que é criado no seu aplicativo, você precisa declarar um elemento XML correspondente no arquivo de manifesto:

<activity> para cada subclasse de Activity.
<service> para cada subclasse de Service.
<receiver> para cada subclasse de BroadcastReceiver.
<provider> para cada subclasse de ContentProvider.

Se você subclassificar algum desses componentes sem declarar no arquivo de manifesto, o sistema não poderá iniciá-lo.

O nome da sua subclasse precisa ser especificado com o atributo name, usando toda a designação do pacote. Por exemplo, uma subclasse Activity pode ser declarada assim:

<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 nome do pacote do aplicativo (a partir do atributo package do elemento <manifest>) será prefixado ao nome. Por exemplo, o nome da atividade a seguir é resolvido para `"com.example.myapp.MainActivity"`:

<manifest package="com.example.myapp" ... >
    <application ... >
        <activity android:name=".MainActivity" ... >
            ...
        </activity>
    </application>
</manifest>

Caso você tenha componentes de aplicativo 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 intents

As atividades do aplicativo, os serviços e os broadcast receivers são ativados pelos intents. O intent é uma mensagem definida por um objeto Intent que descreve uma ação a ser realizada, inclusive dados usados em ações, a categoria do componente que executará a ação e outras instruções.

Quando um aplicativo envia um intent ao sistema, este último localiza um componente do aplicativo que possa processar o intent com base nas declarações do filtro de intents do arquivo de manifesto do aplicativo. O sistema lança uma instância do componente correspondente e passa o objeto Intent a esse componente. Caso mais de um aplicativo possa processar o intent, o usuário pode escolher qual usar.

Um componente do aplicativo pode ter vários filtros de intents (definidos com o elemento <intent-filter>), cada um descrevendo um recurso diferente do componente.

Para mais informações, consulte o documento Intents e filtros de intents.

Ícones e rótulos

Diversos elementos do manifesto têm atributos icon e label para exibir, respectivamente, um pequeno ícone e um rótulo de texto aos usuários para o componente de aplicativo 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 aplicativo (como todas as atividades).

O ícone e o rótulo definidos no <intent-filter> do componente são exibidos ao usuário sempre que o componente é apresentado como opção de preenchimento de um intent. Por padrão, esse ícone é herdado de qualquer ícone que esteja declarado para o componente pai (o elemento <activity> ou <application>). No entanto, você pode querer alterar o ícone de um filtro de intents se ele fornecer uma ação única que você queira indicar melhor na caixa de diálogo seletora. Para mais informações, consulte Permitir que outros aplicativos iniciem sua atividade.

Permissões

Os aplicativos Android precisam solicitar permissão de acesso aos dados confidenciais do usuário (como contatos e SMS) ou a determinados recursos do sistema (como a câmera e o acesso à Internet). Cada permissão é identificada por um rótulo exclusivo. Por exemplo, um aplicativo que precisa enviar mensagens SMS precisa ter a seguinte linha no manifesto:

<manifest ... >
    <uses-permission android:name="android.permission.SEND_SMS"/>
    ...
</manifest>

A partir do Android 6.0 (API de nível 23), o usuário pode aprovar ou rejeitar algumas permissões de aplicativo no ambiente de execução. Mas independentemente de qual versão do Android seja compatível com seu aplicativo, é necessário declarar todas as solicitações de permissões com um elemento <uses-permission> no manifesto. Se a permissão for concedida, o aplicativo será capaz de usar os recursos protegidos. Caso contrário, a tentativa de acessar esses recursos falhará.

Seu aplicativo também pode proteger os próprios componentes com permissões. Ele pode usar quaisquer permissões definidas pelo Android, conforme listado em android.Manifest.permission, ou uma permissão declarada em outro aplicativo. Seu aplicativo 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 Visão geral das permissões.

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 aplicativo e com quais tipos de dispositivo ele é compatível. O Google Play Store não permite que seu aplicativo seja instalado em dispositivos que não fornecem os recursos ou a versão do sistema exigidos.

Há várias tags de manifesto que definem com quais dispositivos o aplicativo tem compatibilidade. Veja abaixo algumas das tags mais comuns.

<uses-feature>

O elemento <uses-feature> permite que você declare os recursos de hardware e software de que o aplicativo precisa. Por exemplo, se o aplicativo não consegue realizar funcionalidades básicas em um dispositivo que não tenha um sensor de bússola, é possível declarar o sensor de bússola como obrigatório com a seguinte tag de manifesto:

<manifest ... >
    <uses-feature android:name="android.hardware.sensor.compass"
                  android:required="true" />
    ...
</manifest>

Observação: se quiser que seu aplicativo seja disponibilizado para Chromebooks, há algumas limitações importantes de recursos de hardware e software que você precisa considerar. Para mais informações, consulte Compatibilidade do manifesto do aplicativo para Chromebooks.

<uses-sdk>

Cada versão sucessiva da plataforma frequentemente adiciona novas APIs não disponíveis na versão anterior. Para indicar a versão mínima de compatibilidade com o aplicativo, o manifesto precisa incluir a tag <uses-sdk> e o atributo minSdkVersion.

No entanto, os atributos no elemento <uses-sdk> são substituídos pelas propriedades correspondentes no arquivo build.gradle. Portanto, se estiver usando o Android Studio, é necessário especificar os valores minSdkVersion e targetSdkVersion no arquivo:

android {
  defaultConfig {
    applicationId 'com.example.myapp'

    // Defines the minimum API level required to run the app.
    minSdkVersion 15

    // Specifies the API level used to test the app.
    targetSdkVersion 28

    ...
  }
}

Para mais informações sobre o arquivo build.gradle, leia sobre como configurar sua compilação.

Para saber mais sobre como declarar o suporte do seu aplicativo para diferentes dispositivos, consulte a Visão geral da compatibilidade do dispositivo.

Convenções de arquivo

Esta seção descreve as convenções e as 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 meio de 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 o <activity> de quem ele é um alias.
O elemento <application> precisa ser o último elemento dentro do elemento <manifest>.

Atributos

Tecnicamente, os atributos são opcionais. No entanto, muitos deles precisam ser especificados para que um elemento possa cumprir a 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 prefixo android:. Por exemplo: android:alwaysRetainTaskState. Como o prefixo é universal, a documentação geralmente o omite ao referir-se a atributos pelo nome.

Vários valores

Se for especificado mais de um valor, 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 aplicativo. O valor desses atributos pode divergir de acordo com o idioma do usuário ou outras configurações do dispositivo (como para fornecer um tamanho de ícone diferente com base na densidade de pixel do dispositivo). Assim, os valores podem ser definidos de 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"

Será possível omitir o nome do package se o recurso for fornecido pelo seu aplicativo, inclusive por uma dependência de bibliotecas, porque os recursos de biblioteca são mesclados aos seus). Quando você quiser usar um recurso da biblioteca do Android, o único nome de pacote válido será android.

O type é um tipo de recurso, como uma string ou um drawable, e o name é o nome que identifica o recurso específico. Vejamos um exemplo:

<activity android:icon="@drawable/smallPic" ... >

Para mais informações sobre como adicionar recursos ao projeto, leia Como fornecer recursos.

Para aplicar um valor definido em um tema, o primeiro caractere precisa ser ? em vez de @:

"?[package:]type/name"

Valores de string

Onde um valor de atributo é uma string, você precisa 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 a seguir fornece links para documentos de referência para todos os elementos válidos no arquivo AndroidManifest.xml.

`<action>`	Adiciona uma ação a um intent de filtros.
`<activity>`	Declara um componente da atividade.
`<activity-alias>`	Declara um alias para a atividade.
`<application>`	É a declaração do aplicativo.
`<category>`	Adiciona um nome de categoria a um filtro de intents.
`<compatible-screens>`	Especifica cada configuração da tela que tem compatibilidade com o aplicativo.
`<data>`	Adiciona uma especificação de dados a um filtro de intents.
`<grant-uri-permission>`	Especifica os subconjuntos de dados do aplicativo que o provedor de conteúdo pai tem permissão para acessar.
`<instrumentation>`	Declara uma classe `Instrumentation` que permite que você monitore uma interação do aplicativo com o sistema.
`<intent-filter>`	Especifica a quais tipos de intents uma atividade, um serviço ou um broadcast receiver podem responder.
`<manifest>`	É o elemento raiz do arquivo AndroidManifest.xml.
`<meta-data>`	É um par de nome-valor para um item de dados adicionais e arbitrários que podem ser fornecidos ao componente pai.
`<path-permission>`	Define o caminho e as permissões obrigatórias para um subconjunto específico de dados dentro de 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 desse aplicativo ou de outros.
`<permission-group>`	Declara um nome para um agrupamento lógico de permissões relacionadas.
`<permission-tree>`	Declara o nome de base para uma árvore de permissões.
`<provider>`	Declara um componente do provedor de conteúdo.
`<receiver>`	Declara um componente do broadcast receiver.
`<service>`	Declara um componente de serviço.
`<supports-gl-texture>`	Declara um único formato de compressão da textura GL compatível com o aplicativo.
`<supports-screens>`	Declara os tamanhos de tela compatíveis com o aplicativo e ativa o modo de compatibilidade da tela para o que for maior do que o suportado pelo aplicativo.
`<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 a que o aplicativo precisa estar vinculado.
`<uses-permission>`	Especifica uma permissão do sistema que precisa ser concedida pelo usuário para que o aplicativo funcione corretamente.
`<uses-permission-sdk-23>`	Especifica que um aplicativo quer uma permissão específica, mas somente se o aplicativo estiver instalado em um dispositivo com Android 6.0 (API de nível 23) ou superior.
`<uses-sdk>`	Permite expressar a compatibilidade de um aplicativo com uma ou mais versões da plataforma Android por meio de um número inteiro de nível de API.

Arquivo de manifesto de exemplo

O XML abaixo é um simples exemplo de AndroidManifest.xml que declara duas atividades para o aplicativo.

<?xml version="1.0" encoding="utf-8"?>
<manifest
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:versionCode="1"
    android:versionName="1.0"
    package="com.example.myapp">

    <!-- 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 upon the package attribute -->
        <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>