lightbulb_outline Help shape the future of the Google Play Console, Android Studio, and Firebase. Start survey

Manifesto do aplicativo

Todo aplicativo tem que ter um arquivo AndroidManifest.xml (precisamente com esse nome) no diretório raiz. O arquivo de manifesto apresenta informações essenciais sobre o aplicativo ao sistema Android, necessárias para o sistema antes que ele possa executar o código do aplicativo.

Entre outras coisas, o arquivo do manifesto serve para:

  • Nomear o pacote Java para o aplicativo. O nome do pacote serve como identificador exclusivo para o aplicativo.
  • Descrever os componentes do aplicativo, que abrangem atividades, serviços, receptores de transmissão e provedores de conteúdo que compõem o aplicativo. Ele também nomeia a classe que implementa cada um dos componentes e publica suas capacidades, como as mensagens Intent que podem lidar. Essas declarações informam ao sistema Android os componentes e as condições em que eles podem ser inicializados.
  • Determinar os processos que hospedam os componentes de aplicativo.
  • Declarar as permissões que o aplicativo deve ter para acessar partes protegidas da API e interagir com outros aplicativos. Ele também declara as permissões que outros devem ter para interagir com os componentes do aplicativo.
  • Listar as classes Instrumentation que fornecem geração de perfil e outras informações durante a execução do aplicativo. Essas declarações estão presentes no manifesto somente enquanto o aplicativo está em desenvolvimento e são removidas antes da publicação do aplicativo.
  • Declarar o nível mínimo da Android API que o aplicativo exige.
  • Listar as bibliotecas às quais o aplicativo deve se vincular.

Observação: À medida que você prepara o seu aplicativo Android para executar em Chromebooks, há algumas limitações de recursos importantes de hardware e software a considerar. Consulte o documento Compatibilidade do manifesto do aplicativo para Chromebooks para obter mais informações.

Estrutura do arquivo do manifesto

O snippet de código abaixo ilustra a estrutura geral do arquivo de manifesto e cada elemento que ele pode conter. Cada elemento e seus atributos estão documentados completamente em um arquivo separado.

Dica: Para ver informações detalhadas de qualquer elemento mencionado no texto deste documento, basta clicar no nome do elemento.

Eis um exemplo do arquivo de manifesto:

<?xml version="1.0" encoding="utf-8"?>

<manifest>

    <uses-permission />
    <permission />
    <permission-tree />
    <permission-group />
    <instrumentation />
    <uses-sdk />
    <uses-configuration />  
    <uses-feature />  
    <supports-screens />  
    <compatible-screens />  
    <supports-gl-texture />  

    <application>

        <activity>
            <intent-filter>
                <action />
                <category />
                <data />
            </intent-filter>
            <meta-data />
        </activity>

        <activity-alias>
            <intent-filter> . . . </intent-filter>
            <meta-data />
        </activity-alias>

        <service>
            <intent-filter> . . . </intent-filter>
            <meta-data/>
        </service>

        <receiver>
            <intent-filter> . . . </intent-filter>
            <meta-data />
        </receiver>

        <provider>
            <grant-uri-permission />
            <meta-data />
            <path-permission />
        </provider>

        <uses-library />

    </application>

</manifest>

A lista a seguir contém todos os elementos que podem aparecer no arquivo de manifesto em ordem alfabética:

Observação: Estes são os únicos elementos legais – não é possível adicionar elementos ou atributos próprios.

Convenções de arquivo

Esta seção descreve as convenções e as regras que se aplicam geralmente a todos elementos e atributos no arquivo de manifesto.

Elementos
Só são necessários os elementos <manifest> e <application>. Eles devem estar presentes e ocorrer somente uma vez. A maioria dos outros elementos podem ocorrer várias vezes ou nenhuma. No entanto, ao menos alguns deles devem estar presentes antes de o arquivo de manifesto se tornar útil.

Se um elemento contiver qualquer coisa, ele conterá outros elementos. 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 se combinar em qualquer sequência. Há duas exceções principais a essa regra:

  • O elemento <activity-alias> deve seguir o <activity> para o qual ele é um alias.
  • O elemento <application> deve ser o último elemento dentro do elemento <manifest>. Em outras palavras, a tag de fechamento </application> deve aparecer imediatamente antes da tag de fechamento </manifest>.
Atributos
Formalmente, todos os atributos são opcionais. No entanto, é preciso especificar alguns atributos para que um elemento realize o seu propósito. Use a documentação como guia. Para atributos verdadeiramente opcionais, ele menciona um valor padrão ou declara o que acontece na ausência de uma especificação.

Exceto por alguns atributos do elemento <manifest>, 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.

Declaração de nomes de classe
Vários elementos correspondem a objetos Java, inclusive elementos para o próprio aplicativo (o elemento <application>) e seus principais componentes: atividades (<activity>), serviços (<service>), receptores de transmissão (<receiver>) e provedores de conteúdo (<provider>).

Se você definir uma subclasse, como quase sempre acontece para classes de componentes (Activity, Service, BroadcastReceiver e ContentProvider), ela será declarada por meio de um atributo name. O nome deve conter toda a designação do pacote. Por exemplo, pode-se declarar uma subclasse Service assim:

<manifest . . . >
    <application . . . >
        <service android:name="com.example.project.SecretService" . . . >
            . . .
        </service>
        . . .
    </application>
</manifest>

No entanto, se o primeiro caractere da string for um ponto, a string será acrescentada ao nome do pacote do aplicativo (conforme especificado pelo atributo package do elemento <manifest>). A seguinte atribuição é a mesma mostrada acima:

<manifest package="com.example.project" . . . >
    <application . . . >
        <service android:name=".SecretService" . . . >
            . . .
        </service>
        . . .
    </application>
</manifest>

Ao iniciar um componente, o sistema Android cria uma instância da subclasse nomeada. Se nenhuma subclasse for especificada, ele criará uma instância da classe base.

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 intent 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 é possível exibir aos usuários, como um rótulo e um ícone de uma atividade. Os valores desses atributos devem ser localizados e definidos a partir de um recurso ou tema. Os valores de recurso são expressos no formato a seguir:

@[<i>package</i>:]<i>type</i>/<i>name</i>

É possível omitir o nome do pacote se o recurso estiver no mesmo pacote que o aplicativo. O type é um tipo de recurso, como uma string ou um drawable (desenhável), e name é o nome que identifica o recurso específico. Vejamos um exemplo:

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

Os valores de um tema são expressados similarmente, mas com um ? inicial em vez de @:

?[<i>package</i>:]<i>type</i>/<i>name</i>

Valores de string
Onde um valor de atributo é uma string, você deve usar barras invertidas duplas (\\) para caracteres de escape, como \\n para uma nova linha ou \\uxxxx para um caractere Unicode.

Recursos de arquivo

As seções a seguir descrevem como alguns recursos do Android se refletem no arquivo de manifesto.

Filtros de intent

Os componentes fundamentais de um aplicativo, como atividades, serviços e receptores de transmissão, são ativados por intents. Intents são pacotes de informações (objetos Intent) que descrevem uma ação desejada, inclusive dados usados em ações, a categoria do componente que deve executar a ação e outras instruções pertinentes. O sistema Android localiza um componente adequado para responder à intent, inicia uma nova instância do componente se necessário e passa-o ao objeto Intent.

Os componentes aconselham os tipos de intents aos quais podem responder pelos filtro de intent. Como o sistema Android precisa saber que intents um componente pode processar antes de iniciá-lo, os filtros de intent são especificados no manifesto como elementos <intent-filter>. Os componentes podem ter qualquer quantidade de filtros, em que cada um descreve um recurso diferente.

A intent que nomeia explicitamente um componente alvo ativará aquele componente para que o filtro não assuma nenhuma função. Uma intent que não especifica nenhum alvo pelo nome pode ativar um componente somente se ele puder passar por um dos filtros do componente.

Para obter informações sobre como objetos Intent são testados contra filtros de intent, confira o documento Intents e filtros de intent.

Ícones e rótulos

Alguns elementos têm atributos icon e label de um pequeno ícone e um rótulo de texto que pode ficar visível para os usuários. Alguns deles também têm um atributo description para um texto explicativo mais longo que também pode ser exibido na tela. Por exemplo: o elemento <permission> tem todos os três atributos; assim, quando o usuário é consultado para dar permissão a um aplicativo que a solicitou, serão apresentados ao usuário um ícone que representa a permissão, o nome da permissão e uma descrição de tudo o que está envolvido.

Em todos os casos, o ícone e o rótulo definidos em um elemento recipiente se tornam as configurações icon e label padrão de todos os subelementos do contêiner. Assim, o ícone e o rótulo definidos no elemento <application> são o ícone e o rótulo padrão para cada um dos componentes do aplicativo. Da mesma forma, o ícone e o rótulo definidos para um componente, como um elemento <activity>, são as configurações padrão para cada um dos elementos <intent-filter> do componente. Se um elemento <application> define um rótulo, mas uma atividade e seu filtro de intent não definem, o rótulo do aplicativo é tratado como o rótulo da atividade e do filtro de intent.

O ícone e o rótulo definidos para um filtro de intent são usados para representar um componente apresentado para o usuário para preencher a função anunciada pelo filtro. Por exemplo: um filtro com as configurações android.intent.action.MAIN e android.intent.category.LAUNCHER anuncia uma atividade como uma que inicia um aplicativo. Ou seja, que deve ser exibida no inicializador do aplicativo. O ícone e o rótulo definidos no filtro são exibidos no inicializador.

Permissões

Permissão é uma restrição que limita o acesso a parte do código ou aos dados de um dispositivo. A limitação é imposta para proteger dados essenciais que podem sofrer mau uso e distorções ou prejudicar a experiência do usuário.

Cada permissão é identificada por um rótulo exclusivo. Geralmente o rótulo indica a ação que foi restringida. Eis algumas permissões que são definidas pelo Android:

  • android.permission.CALL_EMERGENCY_NUMBERS
  • android.permission.READ_OWNER_DATA
  • android.permission.SET_WALLPAPER
  • android.permission.DEVICE_POWER

Um recurso pode ser protegido somente por uma permissão.

Se um aplicativo precisar de acesso a um recurso protegido por uma permissão, ele deverá declarar que precisa da permissão com um elemento <uses-permission> no manifesto. Assim, quando o aplicativo é instalado no dispositivo, o instalador determina se concederá ou não a permissão solicitada, marcando as autoridades que assinaram os certificados do aplicativo e, em alguns casos, perguntando ao usuário. Se a permissão for concedida, o aplicativo será capaz de usar os recursos protegidos. Caso contrário, sua tentativa de acessar esses recursos falhará sem nenhuma notificação ao usuário.

Um aplicativo também pode proteger os próprios componentes com permissões. Ele pode empregar qualquer uma das permissões definidas pelo Android, conforme listadas em android.Manifest.permission, ou declaradas por outros aplicativos. Ele também pode definir uma permissão própria. As novas permissões são declaradas com o elemento <permission>. Por exemplo, uma atividade pode ser protegida da seguinte forma:

<manifest . . . >
    <permission android:name="com.example.project.DEBIT_ACCT" . . . />
    <uses-permission android:name="com.example.project.DEBIT_ACCT" />
    . . .
    <application . . .>
        <activity android:name="com.example.project.FreneticActivity"
                  android:permission="com.example.project.DEBIT_ACCT"
                  . . . >
            . . .
        </activity>
    </application>
</manifest>

Observe que, nesse exemplo, a permissão DEBIT_ACCT, além de declarada com o elemento <permission>, tem seu uso solicitado com o elemento <uses-permission>. É preciso solicitá-la para que outros componentes do aplicativo iniciem a atividade protegida, mesmo que a proteção seja imposta pelo próprio aplicativo.

Se, no mesmo exemplo mostrado acima, o atributo permission fosse definido como uma permissão declarada em outro lugar, como android.permission.CALL_EMERGENCY_NUMBERS, não seria necessário declará-la novamente com um elemento <permission>. No entanto, ainda seria necessário solicitar seu uso com <uses-permission>.

O elemento <permission-tree> declara um namespace para um grupo de permissões que é definido no código, e <permission-group> define um rótulo para um conjunto de permissões, ambos declarados no manifesto com os elementos <permission> e aqueles declarados em outros lugares. Isto afeta somente a forma com que as permissões estão agrupadas quando apresentadas ao usuário. O elemento <permission-group> não especifica as permissões que pertencem ao grupo, mas fornece um nome ao grupo. É possível incluir uma permissão no grupo atribuindo o nome do grupo ao atributo permissionGroup do elemento <permission>.

Bibliotecas

Todo aplicativo está vinculado à biblioteca Android padrão, que contém os pacotes básicos para programar aplicativos (com classes comuns como Activity, Service, Intent, View, Button, Application e ContentProvider).

No entanto, alguns pacotes residem em bibliotecas próprias. Se o aplicativo usar código de algum desses pacotes, ele deverá receber solicitação explícita para ser vinculado a eles. O manifesto deve conter um elemento <uses-library> separado para nomear cada uma das bibliotecas. É possível encontrar o nome da biblioteca na documentação do pacote.