애플리케이션 ID 설정

모든 Android 앱에는 com.example.myapp과 같이 자바 패키지 이름처럼 보이는 고유한 애플리케이션 ID가 있습니다. 이 ID로 기기와 Google Play 스토어에서 앱을 고유하게 식별할 수 있습니다. 새 버전의 앱을 업로드하려면 애플리케이션 ID와 앱 서명에 사용할 인증서가 원본 아티팩트와 같아야 합니다. 애플리케이션 ID를 변경하면 Google Play 스토어는 업로드를 완전히 다른 앱으로 취급합니다. 따라서, 일단 앱을 게시한 후에는 애플리케이션 ID를 변경하면 안 됩니다.

아래에 나오는 것처럼 애플리케이션 ID는 모듈의 build.gradle 파일에 applicationId 속성으로 정의됩니다.

Groovy

android {
    defaultConfig {
        applicationId "com.example.myapp"
        minSdkVersion 15
        targetSdkVersion 24
        versionCode 1
        versionName "1.0"
    }
    ...
}

Kotlin

android {
    defaultConfig {
        applicationId = "com.example.myapp"
        minSdkVersion(15)
        targetSdkVersion(24)
        versionCode = 1
        versionName = "1.0"
    }
    ...
}

Android 스튜디오에서 새 프로젝트를 생성하면 applicationId는 설치 과정 중에 선택한 자바 스타일 패키지 이름과 정확히 일치합니다. 하지만, 애플리케이션 ID와 패키지 이름은 이 시점 이후로는 서로 관련이 없습니다. 코드의 패키지 이름(코드 네임스페이스)을 변경할 수 있고 이름을 변경하더라도 애플리케이션 ID에는 영향을 주지 않습니다. 반대의 경우도 마찬가지입니다. 단, 이때도 일단 앱을 게시한 후에는 애플리케이션 ID를 변경하면 안 됩니다. 또한, 패키지 이름을 변경하면 다른 결과가 발생한다는 점을 알고 있어야 합니다. 패키지 이름 변경 방법에 관한 섹션을 참조하세요.

애플리케이션 ID는 기존의 자바 패키지 이름과 같은 형태이지만 애플리케이션 ID의 명명 규칙은 다음과 같이 좀 더 제한적입니다.

  • 이름은 두 개 이상의 세그먼트(한 개 이상의 점)로 구성해야 합니다.
  • 각 세그먼트는 문자로 시작해야 합니다.
  • 모든 문자는 영숫자나 밑줄[a~z, A~Z, 0~9 또는 _]이어야 합니다.

참고: 전에는 애플리케이션 ID가 코드의 패키지 이름과 직접 연결되었으므로, 일부 Android API는 메서드 이름과 매개변수 이름에 '패키지 이름'이라는 용어를 사용합니다. 그러나 실제로 이는 애플리케이션 ID입니다. 예를 들어, Context.getPackageName() 메서드는 애플리케이션 ID를 반환합니다. 코드의 실제 패키지 이름을 앱 코드 외부에서 공유할 필요는 없습니다.

주의: WebView를 사용하고 있다면 애플리케이션 ID에서 패키지 이름을 접두사로 사용하는 것이 좋습니다. 그렇게 하지 않으면 문제 211768에 설명한 것과 같은 문제가 발생할 수 있습니다.

빌드 변형의 애플리케이션 ID 변경

앱의 APK 또는 AAB를 빌드할 때 빌드 도구는 build.gradle 파일의 defaultConfig 블록에 정의된 애플리케이션 ID로 앱에 태그를 지정합니다(아래 참고). 그러나, Google Play 스토어에 다양한 앱 버전(예: 'free' 및 'pro' 버전)이 별도의 목록으로 표시되도록 하려면 애플리케이션 ID가 서로 다른 별개의 빌드 변형을 만들어야 합니다.

이 경우에는 빌드 변형마다 별도의 제품 버전을 정의해야 합니다. productFlavors 블록 내부의 각 버전에 applicationId 속성을 재정의하거나, 아래와 같이 applicationIdSuffix를 사용하여 기본 애플리케이션 ID에 세그먼트를 추가할 수 있습니다.

Groovy

android {
    defaultConfig {
        applicationId "com.example.myapp"
    }
    productFlavors {
        free {
            applicationIdSuffix ".free"
        }
        pro {
            applicationIdSuffix ".pro"
        }
    }
}

Kotlin

android {
    defaultConfig {
        applicationId = "com.example.myapp"
    }
    productFlavors {
        create("free") {
            applicationIdSuffix = ".free"
        }
        create("pro") {
            applicationIdSuffix = ".pro"
        }
    }
}

이렇게 하면 'free' 제품 버전의 애플리케이션 ID는 'com.example.myapp.free'가 됩니다.

아래와 같이 빌드 유형에 따라 applicationIdSuffix를 사용하여 세그먼트를 추가할 수도 있습니다.

Groovy

android {
    ...
    buildTypes {
        debug {
            applicationIdSuffix ".debug"
        }
    }
}

Kotlin

android {
    ...
    buildTypes {
        getByName("debug") {
            applicationIdSuffix = ".debug"
        }
    }
}

Gradle에서는 제품 버전 뒤에 빌드 유형 구성을 적용하므로 'free debug' 빌드 변형의 애플리케이션 ID는 'com.example.myapp.free.debug'입니다. 이는 두 개의 앱이 동일한 애플리케이션 ID를 가질 수 없으므로 하나의 기기에 디버그 빌드와 출시 빌드를 모두 두려고 할 때 유용합니다.

Google Play에서 APK를 사용하여 배포하는 기존 앱의 경우(2021년 8월 이전에 생성된 앱) 동일한 앱 등록정보를 사용하여 각각 다른 기기 설정(예: API 수준)을 타겟팅하는 여러 APK를 배포하려면 각 빌드 변형에 같은 애플리케이션 ID를 사용하고 각 APK에 다른 versionCode를 부여해야 합니다. 자세한 내용은 다중 APK 지원을 참고하세요. AAB를 사용하는 게시는 기본적으로 단일 버전 코드와 애플리케이션 ID를 사용하는 단일 아티팩트를 사용하므로 영향을 받지 않습니다.

주의: build.gradle 파일에서 applicationId 속성을 정의하지 않으면 빌드 도구는 이전 SDK 도구 호환성을 위해 AndroidManifest.xml 파일의 패키지 이름을 애플리케이션 ID로 사용합니다. 이 경우 패키지 이름을 리팩터링하면 애플리케이션 ID도 변경됩니다.

도움말: 매니페스트 파일에서 애플리케이션 ID를 참조해야 할 경우 모든 매니페스트 속성에서 ${applicationId} 자리표시자를 사용할 수 있습니다. Gradle은 빌드 중에 이 태그를 실제 애플리케이션 ID로 교체합니다. 자세한 내용은 매니페스트에 빌드 변수 삽입을 참조하세요.

테스트를 위해 애플리케이션 ID 변경

기본적으로 빌드 도구에서는 지정된 빌드 변형의 애플리케이션 ID에 .test를 추가하여 계측 테스트 APK에 애플리케이션 ID를 적용합니다. 예를 들어, com.example.myapp.free 빌드 변형의 테스트 APK는 애플리케이션 ID로 com.example.myapp.free.test를 사용합니다.

필수는 아니지만, defaultConfig 또는 productFlavor 블록에 testApplicationId 속성을 정의하여 애플리케이션 ID를 변경할 수 있습니다.

패키지 이름 변경

프로젝트의 패키지 이름이 기본적으로 애플리케이션 ID와 일치하더라도 이를 변경할 수 있습니다. 하지만, 패키지 이름을 변경하려면 아래와 같이 (프로젝트 디렉터리 구조에 정의된 대로) 패키지 이름이 항상 AndroidManifest.xml 파일의 package 속성과 일치해야 합니다.

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

Android 빌드 도구는 다음 두 가지 이유로 package 속성을 사용합니다.

  • 앱에서 생성된 R.java 클래스의 네임스페이스로 이 이름을 사용합니다.

    예: 위의 매니페스트를 사용하면 R 클래스는 com.example.myapp.R이 됩니다.

  • 빌드 도구는 package 속성을 사용하여 매니페스트 파일에 선언된 상대 클래스 이름을 결정합니다.

    예: 위의 매니페스트를 사용하면 <activity android:name=".MainActivity">로 선언된 활동은 com.example.myapp.MainActivity입니다.

이와 같이 package 속성에 있는 이름은 활동 및 기타 앱 코드를 유지하는 프로젝트의 기본 패키지 이름과 항상 일치해야 합니다. 물론, 프로젝트에 하위 패키지가 있을 수 있지만, 그렇다면 하위 패키지에 포함된 파일은 package 속성의 네임스페이스를 사용하여 R.java 클래스를 가져와야 하고, 매니페스트에 선언된 모든 앱 구성요소는 누락된 하위 패키지 이름을 추가하거나 정규화된 패키지 이름을 사용해야 합니다.

패키지 이름을 완전히 리팩터링하려면 package 속성도 업데이트해야 합니다. Android 스튜디오의 도구를 사용하여 패키지 이름을 바꾸고 리팩터링한다면 패키지는 동기화된 상태로 자동 유지됩니다. (패키지가 동기화된 상태로 유지되지 않으면 R 클래스가 더 이상 같은 패키지에 있지 않으므로 앱 코드에서 이 클래스를 확인할 수 없고 매니페스트는 활동이나 기타 구성요소를 식별하지 못합니다.)

항상 프로젝트의 기본 AndroidManifest.xml 파일에 package 속성을 지정해야 합니다. 예를 들어, 제품 버전이나 빌드 유형에 맞는 매니페스트 파일이 추가로 있는 경우 최종적으로 병합된 매니페스트는 항상 우선순위가 가장 높은 매니페스트 파일에서 제공하는 패키지 이름을 사용합니다. 자세한 내용은 여러 매니페스트 파일 병합을 참고하세요.

한 가지 더 알아둘 점: 매니페스트의 package와 Gradle의 applicationId가 다른 이름을 가질 수 있지만, 빌드 도구는 빌드가 종료될 때 최종 앱 매니페스트 파일에 애플리케이션 ID를 복사합니다. 따라서, 빌드 후에 AndroidManifest.xml 파일을 검사해 보면 package 속성이 변경되어 있습니다. package 속성은 Google Play 스토어와 Android 플랫폼에서 실제로 앱을 식별하기 위한 항목이므로, 빌드에서 원래 값을 사용하여 R 클래스에 네임스페이스를 지정하고 매니페스트 클래스 이름을 결정하고 나면 원래 값을 삭제하고 애플리케이션 ID로 대체합니다.