앱 매니페스트 개요

모든 앱 프로젝트는 프로젝트 소스 세트의 루트에 AndroidManifest.xml 파일(정확히 이 이름이어야 함)이 있어야 합니다. 매니페스트 파일은 Android 빌드 도구, Android 운영체제 및 Google Play에 앱에 관한 필수 정보를 설명합니다.

매니페스트 파일은 다른 여러 가지도 설명하지만 특히 다음과 같은 내용을 선언해야 합니다.

• 앱의 구성요소(모든 활동, 서비스, broadcast receiver, 콘텐츠 제공자 포함). 각 구성요소는 Kotlin이나 Java 클래스의 이름과 같은 기본 속성을 정의해야 합니다. 또한 각 구성요소가 처리할 수 있는 기기 구성의 종류, 그리고 구성요소가 어떻게 시작되는지 설명하는 인텐트 필터와 같은 기능을 선언할 수도 있습니다. 다음 섹션에서 앱 구성요소에 관해 자세히 알아보세요.
• 앱이 시스템 또는 다른 앱의 보호된 부분에 액세스하기 위해 필요한 권한. 또한 다른 앱에서 이 앱의 콘텐츠에 액세스하려는 경우 보유해야 하는 모든 권한을 선언합니다. 다음 섹션에서 권한에 관해 자세히 알아보세요.
• 앱에 필요한 하드웨어 및 소프트웨어 기능으로, 이에 따라 앱을 Google Play에서 설치할 수 있는 기기의 종류가 달라집니다. 다음 섹션에서 기기 호환성에 관해 자세히 알아보세요.

Android 스튜디오를 사용하여 앱을 빌드하고 있다면 매니페스트 파일이 생성되고, 앱을 빌드하는 동안(특히, 코드 템플릿을 사용하는 시점에서) 대부분의 기본적인 매니페스트 요소가 추가됩니다.

파일 기능

다음 섹션에서는 앱의 가장 중요한 특징 중 일부가 어떻게 매니페스트 파일에 반영되는지 설명합니다.

앱 구성요소

앱에서 생성하는 각각의 앱 구성요소에 대해 매니페스트 파일에서 상응하는 XML 요소를 선언합니다.

• Activity의 각 서브클래스의 <activity>
• Service의 각 서브클래스의 <service>
• BroadcastReceiver의 각 서브클래스의 <receiver>
• ContentProvider의 각 서브클래스의 <provider>

이러한 구성요소를 매니페스트 파일에서 선언하지 않고 서브클래스로 분류하면 시스템에서 이를 시작할 수 없습니다.

전체 패키지 지정을 사용하여 name 속성으로 서브클래스의 이름을 지정합니다. 예를 들어 Activity 서브클래스는 다음과 같이 선언됩니다.

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

그러나 name 값의 첫 번째 문자가 마침표라면 앱의 네임스페이스(모듈 수준 build.gradle 파일의 namespace 속성에서)가 이름 앞에 붙습니다. 예를 들어 네임스페이스가 "com.example.myapp"이면 다음 활동 이름은 com.example.myapp.MainActivity로 확인됩니다.

<manifest ... >
    <application ... >
        <activity android:name=".MainActivity" ... >
            ...
        </activity>
    </application>
</manifest>

패키지 이름이나 네임스페이스 설정에 관한 자세한 내용은 네임스페이스 설정을 참고하세요.

하위 패키지(예: com.example.myapp.purchases) 안에 앱 구성요소가 있을 경우, name 값으로 누락된 하위 패키지 이름(예: ".purchases.PayActivity")을 추가하거나 정규화된 패키지 이름을 사용해야 합니다.

인텐트 필터

앱 활동, 서비스, broadcast receiver는 인텐트로 활성화됩니다. 인텐트는 실행할 작업을 설명하는 Intent 객체로 정의되는 메시지입니다. 여기에는 작업할 데이터, 작업을 실행할 것으로 예상되는 구성요소 카테고리, 기타 명령이 포함됩니다.

앱이 인텐트를 시스템에 발행하면 시스템은 각 앱의 매니페스트 파일에 선언된 인텐트 필터에 기초하여 인텐트를 처리할 수 있는 앱 구성요소를 찾습니다. 시스템은 일치하는 구성요소의 인스턴스를 시작하고 해당 구성요소에 Intent 객체를 전달합니다. 두 개 이상의 앱이 인텐트를 처리할 경우 사용자는 어느 앱을 사용할지 선택할 수 있습니다.

앱 구성요소는 인텐트 필터(<intent-filter> 요소로 정의)를 몇 개든 가질 수 있으며, 각 인텐트 필터는 구성요소의 각 기능을 설명합니다.

자세한 내용은 인텐트 및 인텐트 필터 문서를 참고하세요.

아이콘 및 라벨

많은 매니페스트 요소에는 해당 앱 구성요소에 대해 작은 아이콘과 텍스트 라벨을 사용자에게 각각 표시하기 위한 icon과 label 속성이 있습니다.

모든 경우에 상위 요소에 설정된 아이콘과 라벨은 모든 하위 요소에 관해 기본 icon과 label 값이 됩니다. 예를 들어 <application> 요소에 설정된 아이콘과 라벨이 앱의 각 구성요소(예: 모든 활동)의 기본 아이콘과 라벨이 됩니다.

구성요소의 <intent-filter>에 설정된 아이콘과 라벨은 구성요소가 인텐트를 처리하기 위한 옵션으로 제시될 때마다 사용자에게 표시됩니다. 기본적으로 이 아이콘은 상위 구성요소(<activity> 또는 <application> 요소)에 대해 어떤 아이콘이 선언되든 이를 상속받습니다.

선택기 대화상자에서 더 잘 보여주고 싶은 고유한 작업을 제공하는 경우 인텐트 필터의 아이콘을 변경할 수도 있습니다. 자세한 내용은 다른 앱이 활동을 시작하도록 허용을 참고하세요.

권한

Android 앱은 민감한 사용자 데이터(예: 연락처, SMS) 또는 특정 시스템 기능(예: 카메라, 인터넷 액세스)에 액세스하기 위한 권한을 요청해야 합니다. 각 권한은 고유한 라벨로 식별됩니다. 예를 들어 SMS 메시지를 보내야 하는 앱은 매니페스트에 다음과 같은 줄이 있어야 합니다.

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

Android 6.0(API 수준 23)부터 사용자는 런타임에서 일부 앱 권한을 승인하거나 거절할 수 있게 됩니다. 그러나 앱이 어떤 Android 버전을 지원하든 매니페스트에서 <uses-permission> 요소로 모든 권한 요청을 선언해야 합니다. 권한이 부여되면 앱이 보호된 기능을 사용할 수 있습니다. 권한이 부여되지 않으면 그러한 기능에 액세스하려는 시도가 실패합니다.

앱은 권한을 사용하여 자체 구성요소를 보호할 수도 있습니다. 그리고 Android에서 정의된 권한(android.Manifest.permission에서 설명) 또는 다른 앱에서 선언된 권한을 사용할 수 있습니다. 앱은 자체 권한을 정의할 수도 있습니다. 새 권한을 선언할 때는 <permission> 요소를 사용합니다.

자세한 내용은 Android의 권한을 참고하세요.

기기 호환성

매니페스트 파일에서는 앱에 필요한 하드웨어 또는 소프트웨어 기능 유형을 선언할 수 있고, 따라서 앱과 호환되는 기기 유형도 선언할 수 있습니다. Google Play 스토어에서는 사용자가 앱에 필요한 기능 또는 시스템 버전을 제공하지 않는 기기에 앱을 설치할 수 없습니다.

어느 기기가 앱과 호환되는지 정의하는 매니페스트 태그가 여러 가지 있습니다. 가장 일반적인 태그는 다음과 같습니다.

<uses-feature>

<uses-feature> 요소를 사용하면 앱에 필요한 하드웨어 및 소프트웨어 기능을 선언할 수 있습니다. 예를 들어 나침반 센서가 없는 기기에서 앱이 기본적인 기능을 실행할 수 없다면, 필요에 따라 다음과 같이 매니페스트 태그를 사용하여 나침반 센서를 선언할 수 있습니다.

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

참고: Chromebook에서 앱을 사용할 수 있게 하려면 중요한 하드웨어 및 소프트웨어 기능 제한사항을 고려해야 합니다. 자세한 내용은 Chromebook의 앱 매니페스트 호환성을 참고하세요.

<uses-sdk>

연속적인 각 플랫폼 버전에서는 이전 버전에서 사용할 수 없는 새 API를 추가하는 경우가 많습니다. 앱이 호환되는 최소 버전을 나타내려면 매니페스트에 <uses-sdk> 태그와 그 minSdkVersion 속성을 포함해야 합니다.

그러나 <uses-sdk> 요소의 속성은 build.gradle 파일의 상응하는 속성으로 재정의됩니다. 따라서 Android 스튜디오를 사용하면 minSdkVersion 및 targetSdkVersion 값을 대신 지정합니다.

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
        ...
    }
}

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)
        ...
    }
}

build.gradle 파일에 관한 자세한 내용은 빌드 구성 방법을 참고하세요.

각 기기의 앱 지원을 선언하는 방법에 관한 자세한 내용은 기기 호환성 개요를 참고하세요.

파일 규칙

이 섹션에서는 매니페스트 파일에 포함되는 모든 요소 및 속성에 일반적으로 적용되는 규칙에 관해 설명합니다.

요소

<manifest> 및 <application> 요소만 필수입니다. 두 요소는 각각 한 번만 실행되어야 합니다. 다른 요소는 대부분 한 번도 실행되지 않거나 한 번 이상 실행되어도 됩니다. 다만 이들 중 일부가 있어야만 매니페스트 파일에 쓸모가 있습니다.

모든 값은 요소 내의 문자 데이터로서가 아니라 속성을 통해 설정됩니다.

같은 레벨에 있는 여러 요소는 보통 순서가 지정되지 않습니다. 예를 들어 <activity>, <provider> 및 <service> 요소는 어느 순서로든 배치할 수 있습니다. 이 규칙에는 두 가지 중요한 예외 사항이 있습니다.

• <activity-alias> 요소는 이 요소를 별칭으로 사용하는 <activity> 다음에 와야 합니다.
• <application> 요소는 <manifest> 요소 내부에 있는 마지막 요소여야 합니다.

속성

엄밀히 말해서 모든 속성은 선택사항입니다. 그러나 어떤 요소의 용도를 실현하기 위해서는 많은 속성을 지정해야 합니다. 철저히 선택사항인 속성의 경우 참조 문서에서 기본값을 확인할 수 있습니다.

루트 <manifest> 요소의 일부 속성을 제외하고 모든 속성 이름은 android: 접두사로 시작합니다(예: android:alwaysRetainTaskState). 이 접두사는 범용이기 때문에 이름으로 속성을 참조하는 경우 관련 문서에서 접두사를 생략하는 경우가 일반적입니다.

여러 개의 값

둘 이상의 값을 지정할 수 있는 경우, 한 요소 안에 여러 값이 나열되지 않고 해당 요소가 거의 항상 반복됩니다. 예를 들어 한 인텐트 필터가 여러 개의 작업을 나열할 수 있습니다.

<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>

리소스 값

일부 속성에는 사용자에게 표시되는 값이 있습니다(예: 활동의 제목 또는 앱 아이콘). 이런 속성에 대한 값은 사용자 언어나 다른 기기 구성에 따라 달라질 수 있으므로(예를 들어 기기 픽셀 밀도에 따라 다른 아이콘 크기 제공) 매니페스트 파일에 하드코딩하지 말고 리소스 또는 테마에서 값을 설정해야 합니다. 그러면 실제 값을 각 기기 구성에 제공하는 대체 리소스에 따라 변경할 수 있습니다.

리소스는 다음과 같은 형식의 값으로 표현됩니다.

"@[package:]type/name"

앱에서 리소스를 제공할 경우 package 이름을 생략할 수 있습니다(라이브러리 리소스가 앱 리소스에 병합되므로 라이브러리 종속성에서 제공하는 경우도 포함). Android 프레임워크의 리소스를 사용하고자 할 때 유효한 다른 패키지 이름은 android뿐입니다.

type은 string 또는 drawable 같은 리소스 유형이며 name는 특정 리소스를 식별하는 이름입니다. 예를 들면 다음과 같습니다.

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

프로젝트에 리소스를 추가하는 방법에 관한 자세한 내용은 앱 리소스 개요를 참고하세요.

대신 테마에 정의된 값을 적용하려면 첫 문자는 @가 아니라 ?가 되어야 합니다.

"?[package:]type/name"

문자열 값

속성 값이 문자열인 경우, 문자를 이스케이프 처리하려면 이중 백슬래시(\\)를 사용합니다(예: 줄바꿈의 경우 \\n 또는 유니코드 문자의 경우 \\uxxxx).

매니페스트 요소 참조 문서

다음 표에서는 AndroidManifest.xml 파일에 있는 모든 유효한 요소에 대한 참조 문서의 링크를 제공합니다.

제한

다음 태그는 매니페스트 파일에서 발생 횟수가 제한됩니다.

다음 속성에는 최대 길이 제한이 있습니다.

매니페스트 파일의 예시

아래의 XML은 앱의 두 가지 액티비티를 선언하는 단순 예시 AndroidManifest.xml입니다.

<?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>