5.3 AndroidManifest.xml

Role of the Android Manifest

Every Android app must include a file named AndroidManifest.xml in its project. This single file acts as a central declaration of what your app is, what it contains, and how it interacts with the Android system. When Android installs or runs your app, it reads the manifest first. It uses this information to know which components your app has, which permissions it needs, and what should happen when a user launches it.

The manifest does not contain the actual logic of your app. Instead, it is a structured description that tells Android about the building blocks that you implemented in Kotlin classes and in resources.

Basic Structure of AndroidManifest.xml

The manifest is an XML file with a specific structure. At the top level, there is a manifest tag that usually includes the package attribute. Inside this tag, you declare the application and its components such as activities, services, and more.

A minimal manifest often looks similar to this:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.myfirstapp">
    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/Theme.MyFirstApp">
        <activity
            android:name=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>

You do not need to memorize this structure, but you should recognize its main parts. The manifest tag sets the package. The application tag configures global information about the app and contains the components. Inside application, each activity tag describes one screen of the app. Other components such as services and broadcast receivers use similar tags and are added in the same area.

The manifest and the package name

The package attribute on the manifest tag defines the application ID that Android uses to uniquely identify your app on devices and in the system. This is usually a reversed domain style name, such as com.example.myfirstapp.

This value is important because Android uses it for internal identification, for permissions, and for data storage areas. It is not just an arbitrary label. Changing it creates a completely different app from the system point of view.

In addition to the package attribute, Gradle can define an applicationId for your build. The relationship between these two values and how Gradle affects them is handled in the Gradle chapter. For now, remember that the manifest package is part of your app identity and must be consistent with the rest of your project configuration.

Declaring the application

The application tag sits inside the root manifest. It wraps all application components and sets properties that apply to the entire app. Some of the most common attributes are:

android:icon references the app icon resource. This is what appears on the launcher and in system lists.

android:label sets a default label for the app. Usually this references a string resource, for example @string/app_name. You can think of it as the user visible app name.

android:theme points to a style that defines the look and feel of your app screens, such as colors and widgets appearance. The details of themes and styles are covered in the styling chapters.

android:allowBackup indicates if the system is allowed to back up your app data.

You can also declare an android:name attribute here to point to a custom Application class if you have one. That case belongs to more advanced architecture topics, but the manifest is where you would plug it in.

The application tag is always present in a real app. Even if you do not modify it manually at first, Android Studio generates a default version when you create a new project.

Declaring activities and the launcher activity

Activities are the main components that represent screens in a classic Android app. Each activity that your app uses must be declared in the manifest as an activity element inside application. If you create a new activity from Android Studio, the IDE can add this entry for you automatically.

A typical activity declaration looks like this:

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

The android:name attribute specifies the Kotlin class that implements the activity. You can write the full package name, for example com.example.myfirstapp.MainActivity, or a shortened version starting with a dot which means relative to the manifest package.

The android:exported attribute tells Android whether external apps can start this activity. From Android 12 and above, this attribute is required on components that have intent filters. Its correct use is part of security best practices and is revisited in the permissions and security topics.

Inside the activity, an intent-filter declares how and when this activity can be launched. The combination of MAIN action and LAUNCHER category marks the entry point that appears on the home screen. Your app should have exactly one activity that uses this pair. This is usually your main activity. Other activities can have different intent filters or none at all, depending on how they are used.

If you add more activities, each one needs its own activity tag inside application. Without such a declaration, the system does not know that the activity exists, and it cannot be started.

Permissions in the manifest

Some features of Android require explicit permission from the user. The manifest is where you declare that your app wants to use those features. Common examples include internet access, reading contacts, and using the camera.

To request a permission, you add a <uses-permission> element directly inside the root manifest tag, outside the application tag. For example:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.myfirstapp">
    <uses-permission android:name="android.permission.INTERNET" />
    <application
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/Theme.MyFirstApp">
        <!-- app components here -->
    </application>
</manifest>

This declaration tells the system that your app needs access to the internet. For some permissions, declaring them in the manifest is enough. For others, the user must also grant them at runtime. The detailed process of requesting and handling runtime permissions is covered in the permissions and security section. For the moment, it is important to understand that the manifest is the first place where you declare any permission your app might need.

If a permission is not declared in the manifest, the system will block access to the protected feature even if you try to use it in your code.

Other manifest declarations

Besides activities and permissions, the manifest supports several other declarations that describe how your app integrates with the platform.

You can use <uses-feature> to declare hardware or software features that your app expects, such as a camera or GPS. This information helps Google Play and the system know which devices can install your app.

You can declare services, broadcast receivers, and content providers when your app uses them. Each of these has its own tag, such as <service> or <receiver>, and they live inside the application tag like activities. The details of these specific components are covered in their dedicated chapters, but you should recognize that the manifest is where they are registered.

Another important role of the manifest is to set the minimum and target Android versions that your app supports. These values are part of the build configuration and are often reflected through manifest entries as well. How you configure these values through Gradle and the overall build system is discussed in the Gradle build system chapter. From the manifest point of view, you should know that Android reads these values to decide if your app can run on a particular device.

Merged manifests and auto generated entries

Modern Android projects often have more than one manifest file. Libraries, external dependencies, and build variants can all contribute their own manifest fragments. During the build, Android Studio and Gradle merge these pieces into a single final manifest that the system uses.

This means that some entries that affect your app might not appear directly in your main AndroidManifest.xml file. For example, if you add a third party library that needs a particular permission, that library might add a <uses-permission> entry through its own manifest. The merge process combines everything.

Android Studio provides tools to inspect the merged manifest. Although the full process of manifest merging belongs to the build system discussions, it is useful to be aware that the final manifest the device sees might be slightly different from what you typed by hand.

Modifying the manifest in Android Studio

In Android Studio, AndroidManifest.xml is located in the app/src/main directory of your module. When you create a new project, Android Studio generates a starter manifest that contains the package, the application tag, and your main activity.

You usually modify the manifest when any of the following happens. You add a new activity, service, or other component that the system should know about. You need a new permission, feature, or configuration. You change global properties such as the app icon, label, or theme.

Android Studio offers completion and suggestions while you edit the file. This helps you discover available attributes and avoids simple mistakes, for example typos in permission names. Since the file is XML, you must keep the structure correct. Unclosed tags or invalid attributes can cause build errors.

When you run your app, the build process validates and packages the manifest together with your code and resources. If the manifest is invalid or inconsistent, the build will fail. Learning to read the manifest and understand what each part does will help you diagnose configuration problems more easily.

Summary of the manifest role

The manifest is the contract between your app and the Android system. It identifies your app through the package, declares your application and its components, states which permissions and features you need, and connects configuration from other parts of the project so the platform can install and run your app correctly.

As you progress, you will revisit the manifest many times. When you add new screens, request permissions, integrate background services, or adjust app wide behavior, you will almost always update AndroidManifest.xml to match those changes.