AndroidManifest.xml — o que é, principais componentes e configuração do manifesto

O que é AndroidManifest.xml

AndroidManifest.xml é o arquivo de configuração raiz no formato XML que todo projeto Android deve ter no diretório app/src/main. O sistema Android o analisa antes de executar qualquer código do aplicativo — durante a análise do APK na instalação. Se o manifesto tiver um erro de sintaxe ou faltar uma declaração obrigatória, a instalação é interrompida com uma mensagem de erro.

O arquivo contém uma declaração completa do aplicativo: uma lista de todos os componentes (Activity, Service, BroadcastReceiver, ContentProvider), permissões solicitadas, versão mínima do SDK, requisitos de hardware e configuração de temas e estilos. Cada componente que pode ser invocado pelo sistema ou por outros aplicativos deve ser explicitamente declarado no manifesto. Este é um requisito de segurança: sem uma declaração explícita, o componente não está disponível para invocação.

Sem um manifesto configurado corretamente, o aplicativo não pode ser instalado através do Google Play ou sideloading. O sistema verifica o manifesto durante a análise do APK e rejeita a instalação se houver erros. O Google Play também escaneia o manifesto em busca de configurações inseguras: se exported=true em um componente sem intent-filter, um aviso é emitido; e se permissões obrigatórias para targetSdk 34+ estiverem faltando, a publicação é bloqueada. Portanto, entender a estrutura do manifesto é uma habilidade obrigatória para desenvolvedores Android.

Componentes do aplicativo no manifesto

Cada componente de um aplicativo Android deve ser explicitamente registrado no manifesto. Este é um requisito obrigatório da plataforma para todos os quatro tipos de componentes. Sem registro, o componente não pode ser criado pelo sistema, e tentar iniciá-lo resultará em uma ActivityNotFoundException ou exceção similar. Os componentes são registrados dentro da tag application em uma ordem que não afeta seu funcionamento.

Activity

A tag activity registra uma tela do aplicativo. O atributo exported determina se outros aplicativos podem iniciar esta Activity. A partir do Android 12, a ausência de exported quando há intent-filter causa um erro de compilação — este é um requisito de segurança. O ponto de entrada é definido através de intent-filter com action MAIN e category LAUNCHER. Cada Activity deve ter um android:único que corresponda ao nome completo ou relativo da classe.

<activity
    android:name=".MainActivity"
    android:exported="true"
    android:windowSoftInputMode="adjustResize">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity>

Service

A tag service define um serviço em segundo plano. A partir do Android 8, os serviços em segundo plano têm limitações rigorosas: um foreground service requer uma notificação obrigatória visível ao usuário com um ícone, e um bound service só vive enquanto houver um cliente vinculado a ele. Serviços executados em segundo plano sem notificação são automaticamente encerrados pelo sistema dentro de alguns minutos após o aplicativo ir para segundo plano. Para tarefas de longa duração, use WorkManager em vez de Service.

<service
    android:name=".SyncService"
    android:exported="false"
    android:foregroundServiceType="dataSync" />

BroadcastReceiver

A tag receiver declara um receptor de mensagens de transmissão do sistema ou personalizadas. A partir do Android 8, a maioria das transmissões implícitas não são mais entregues a receptores declarados estaticamente no manifesto. Em vez disso, é recomendado registrar receptores dinamicamente através de Context.registerReceiver no código. As exceções incluem algumas transmissões do sistema como BOOT_COMPLETED, que ainda exigem registro estático no manifesto.

<receiver
    android:name=".ConnectivityReceiver"
    android:exported="true">
    <intent-filter>
        <action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
    </intent-filter>
</receiver>

Permissões no Android

Cada permissão perigosa no Android requer uma declaração no manifesto através da tag uses-permission. A partir do Android 6, permissões perigosas são solicitadas em tempo de execução através de um diálogo com o usuário, mas a declaração no manifesto permanece obrigatória. Sem ela, o método requestPermissions lança uma SecurityException. Permissões de nível normal como INTERNET e ACCESS_NETWORK_STATE são concedidas automaticamente na instalação.

A tag uses-permission-sdk-23 especifica permissões necessárias apenas no Android 6.0+. Isso permite manter compatibilidade com versões mais antigas sem solicitar permissões inexistentes. Por exemplo, POST_NOTIFICATIONS só está disponível no Android 13+, portanto deve ser especificada via uses-permission-sdk-33 para evitar um erro de permissão desconhecida em dispositivos mais antigos. O atributo maxSdkVersion em uses-permission permite revogar automaticamente permissões desnecessárias ao atualizar o aplicativo em versões mais recentes do Android.

Permissões de nível normal (INTERNET, ACCESS_NETWORK_STATE) são concedidas automaticamente na instalação e não exigem solicitação em tempo de execução. Elas também são declaradas via uses-permission, mas não são mostradas ao usuário em um diálogo. Para controlar o acesso aos componentes do aplicativo a partir de outros aplicativos, é usado o mecanismo de componentes protegidos por permissão: você pode especificar uma permissão personalizada no nível de Activity ou Service, que será verificada pelo sistema quando o componente for chamado externamente. Isso fornece uma camada adicional de segurança para comunicação entre processos.

Intent Filters e deep links

A tag intent-filter no manifesto declara quais intents implícitos um componente pode manipular. Este é o mecanismo através do qual o Android conecta ações do sistema ou personalizadas ao aplicativo. Um intent filter consiste em três elementos: action (ação), category (categoria) e data (dados). Os três podem ser combinados para uma descrição precisa de quais intents o componente deve receber. O sistema seleciona o componente apropriado com base no filtro mais específico.

<activity android:name=".DeepLinkActivity">
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:scheme="https"
            android:host="itsectr.com"
            android:pathPrefix="/app" />
    </intent-filter>
</activity>

O atributo autoVerify ativa a verificação de Android App Links: o sistema contata o servidor para confirmar a propriedade do domínio. Sem verificação, os deep links funcionam através do diálogo de escolha padrão onde o usuário seleciona qual aplicativo abrir o link. Após verificação bem-sucedida, os links abrem diretamente no aplicativo sem diálogo. O Google Search Console também usa autoVerify para indexar deep links e exibi-los nos resultados de pesquisa.

Filtros com action.VIEW e as categorias DEFAULT e BROWSABLE lidam com links de navegadores, e-mails e outros aplicativos. Este é o principal mecanismo para implementar deep links no Android. Para suportar esquemas de URL personalizados como myapp://, basta especificar o scheme sem host. No entanto, o Google recomenda usar deep links HTTPS em vez de esquemas personalizados porque são mais seguros e não exigem permissões adicionais. Esquemas personalizados podem ser interceptados por qualquer aplicativo que registre o mesmo esquema.

Atributos do aplicativo e metadados

A tag raiz manifest contém atributos de pacote, versão e SDK. A tag application armazena configurações globais: tema, ícone, label e flags de depuração. Os atributos de manifest definem o versionamento no nível do pacote, enquanto os atributos de application determinam a aparência e o comportamento geral do aplicativo. Os valores podem ser referências a recursos através da sintaxe @ ou literais de string.

<manifest
    xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.itsectr.myapp"

    <uses-sdk
        android:minSdkVersion="24"
        android:targetSdkVersion="34" />

    <application
        android:label="MyApp"
        android:icon="@mipmap/ic_launcher"
        android:theme="@style/Theme.MyApp"
        android:supportsRtl="true"
        android:allowBackup="true">
        <!--  Componentes do aplicativo  -->
    </application>
</manifest>

A tag meta-data dentro de application permite armazenar pares chave-valor arbitrários. Isso é útil para configurar bibliotecas de terceiros: chaves de API, URLs de endpoints e flags de funcionalidade. Os dados de meta-data são acessíveis via PackageManager.getApplicationInfo().metaData em tempo de execução. Por exemplo, Firebase e Google Maps usam meta-data para passar chaves de acesso sem codificá-las diretamente no código fonte. Em vez disso, as chaves são definidas no manifesto e podem diferir para diferentes variantes de compilação.

O atributo android:extractNativeLibs controla a extração de bibliotecas nativas do APK. Para aplicativos com targetSdk 34+, este atributo deve ser explicitamente especificado, caso contrário, a compilação pode falhar com o erro INSTALL_FAILED_INVALID_APK. Se extractNativeLibs=false, as bibliotecas nativas permanecem dentro do APK sem descompactação, reduzindo o tamanho do aplicativo instalado, mas aumentando o tempo de carregamento das bibliotecas. Para a maioria dos aplicativos modernos, recomenda-se extractNativeLibs=false para reduzir o uso de espaço em disco no dispositivo do usuário.

O atributo android:networkSecurityConfig permite especificar um arquivo de configuração de segurança de rede. Isso é especialmente importante para aplicativos com targetSdk 28+, onde o tráfego HTTP é bloqueado por padrão. O arquivo de configuração define certificados confiáveis, domínios para conexões HTTP e regras de pinning de certificados. Isso substitui o atributo obsoleto android:usesCleartextTraffic e fornece um mecanismo mais flexível para gerenciar a segurança das conexões no nível do sistema operacional.

O atributo android:largeHeap solicita um tamanho de heap aumentado para o aplicativo. Por padrão, o Android aloca a cada aplicativo uma quantidade limitada de memória que depende do dispositivo e da versão do SO. Se o aplicativo trabalha com imagens pesadas, vídeos ou grandes conjuntos de dados, largeHeap pode evitar OutOfMemoryError. No entanto, abusar deste atributo é prejudicial: um aplicativo com alto consumo de memória é encerrado mais rapidamente pelo sistema quando os recursos estão baixos. Use largeHeap somente após perfilamento e confirmação da necessidade.