Package Name — 정의, 리버스 도메인 표기법 및 요구사항

Android에서 Package Name이란

Package Name은 Android가 운영 체제 수준에서 애플리케이션을 식별하는 데 사용하는 고유 문자열입니다. 이는 AndroidManifest.xml 파일의 package 필드와 애플리케이션 모듈의 build.gradle 파일의 applicationId 필드에 해당합니다. 고유한 Package Name이 없으면 사용자 기기에 애플리케이션을 설치할 수 없습니다.

Package Name의 목적

기기에서 Package Name은 애플리케이션 관리의 키 역할을 합니다: 시스템은 /data/data/[packageName] 디렉토리에 각 애플리케이션의 데이터, 설정 및 캐시를 저장합니다. 동일한 식별자를 가진 두 애플리케이션은 공존할 수 없습니다 — 중복 설치를 시도하면 시스템이 기존 앱을 제거하라는 메시지를 표시합니다.

Package Name과 Application ID

Android Gradle Plugin 버전 0.11+에서 Package Name(매니페스트 내)과 Application ID(build.gradle 내) 간의 분리가 도입되었습니다. Application ID는 시스템 및 Google Play에 대한 실제 애플리케이션 식별자입니다. 매니페스트의 Package Name은 리소스 해결 및 R-클래스 생성을 위해 사용됩니다. 단순화를 위해 동일하게 유지하는 것이 좋습니다.

// build.gradle (Module: app)
android {
    defaultConfig {
        applicationId "com.example.myapplication"
        minSdkVersion 24
        targetSdkVersion 34
        versionCode 1
        versionName "1.0"
    }

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

applicationIdSuffix 필드는 다양한 빌드 구성에 대해 Application ID에 접미사를 추가할 수 있게 합니다. 디버그 버전은 com.example.app.debug 식별자를 가질 수 있어 프로덕션 버전과 함께 설치하여 병렬 테스트가 가능합니다.

Package Name 명명 규칙

Google Play는 게시 시 준수해야 하는 Package Name에 대한 엄격한 규칙을 설정합니다. 식별자는 전체 스토어에서 고유해야 하며, 구문 요구사항을 충족하고 상표 정책을 위반하지 않아야 합니다.

구문 요구사항

Package Name에는 라틴 문자(A-Z, a-z), 숫자(0-9), 점(.), 밑줄(_)만 포함될 수 있습니다. 최대 길이는 150자입니다. 점 사이의 각 세그먼트는 문자로 시작해야 합니다. 하이픈, 공백 및 특수 문자는 Google Play 규칙에 의해 금지됩니다.

고유성 요구사항

Package Name의 고유성은 Google Play Store의 절대적인 요구사항입니다. 다른 애플리케이션이 이미 선택한 식별자를 사용하고 있는 경우 게시가 거부됩니다. Google은 삭제된 애플리케이션의 식별자를 해제하지 않으므로 첫 번째 Package Name을 선택하는 것은 모든 개발자에게 중요한 결정입니다.

리버스 도메인 표기법 및 규약

리버스 도메인 표기법은 회사 도메인 이름을 역순으로 작성하는 명명 표준입니다: example.com 대신 com.example. 이 시스템은 모든 도메인 이름이 본질적으로 고유하기 때문에 식별자의 글로벌 고유성을 보장합니다.

표준 접두사

개발자는 일반적으로 도메인의 TLD에 해당하는 접두사를 사용합니다: com은 상업 조직, org는 비영리 조직, io는 기술 프로젝트, net은 네트워크 서비스 및 솔루션용입니다. 개인 프로젝트의 경우 com.github.username 또는 com.email이 허용됩니다.

• com.company.app — 상업용 애플리케이션의 표준 형식
• org.company.app — 비영리 및 오픈소스 프로젝트용
• io.company.app — 스타트업 및 SaaS 제품에서 인기
• com.github.username — GitHub의 개인 프로젝트용

멀티플랫폼 프로젝트 규약

iOS 및 Android에서 출시되는 애플리케이션의 경우 두 플랫폼에서 동일한 식별자를 사용하는 것이 좋습니다. 이렇게 하면 프로젝트 식별자에 바인딩되는 Firebase, AppsFlyer, Adjust 및 기타 분석 시스템과의 통합이 간소화됩니다. 예를 들어, com.mycompany.myapp은 iOS에서 Bundle ID, Android에서 Package Name이 됩니다.

Android 프로젝트에서 Package Name 구성

Android 프로젝트에서 Package Name 구성은 build.gradle의 applicationId 변경과 해당 Java/Kotlin 소스 코드 디렉토리 구조 변경을 포함합니다. Android Studio는 Package Name 리팩토링 도구를 제공하지만, 복잡한 프로젝트의 경우 단계별 마이그레이션이 권장됩니다.

디렉토리 구조 및 Package Name

// 파일 경로가 Package Name에 해당함
// com/example/myapp/MainActivity.kt

package com.example.myapp

import android.os.Bundle
import androidx.activity.ComponentActivity

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
    }
}

Kotlin 및 Java에서 소스 파일의 Package Name은 디렉토리 구조와 일치해야 합니다. build.gradle에서 Package Name을 변경할 때는 파일을 해당 디렉토리로 이동하고 모든 package 및 import 선언을 업데이트해야 합니다. Android Studio는 Refactor -> Move를 통해 자동으로 이 작업을 수행할 수 있지만, 수십 개의 파일이 있는 대규모 프로젝트의 경우 리팩토링 후 결과를 확인하는 것이 좋습니다.

프로젝트가 Data Binding, View Binding 또는 Hilt를 사용하는 경우 Package Name 변경은 생성된 클래스에도 영향을 미칩니다. 바인딩 클래스는 모듈의 Package Name과 레이아웃 디렉토리를 기반으로 생성됩니다. 식별자를 변경한 후에는 생성된 모든 참조를 업데이트하기 위해 프로젝트를 다시 빌드해야 합니다. 캐시된 이전 참조로 인한 오류를 방지하기 위해 Package Name 변경 후 클린 빌드를 수행하는 것이 좋습니다.

Gradle 7.0+에서는 R-클래스 및 리소스 생성을 위해 AndroidManifest.xml의 package 필드를 대체하는 build.gradle의 namespace 지원이 도입되었습니다. 한편, applicationId는 시스템 및 Google Play에 대한 실제 애플리케이션 식별자로 유지됩니다. 이를 통해 네임스페이스는 고정되고 공개 식별자는 빌드 중에 변경될 수 있는 라이브러리 모듈에 유용하게 서로 다른 applicationId와 namespace를 가질 수 있습니다.

모듈식 아키텍처를 사용하는 프로젝트의 경우 한 모듈의 Package Name 변경이 다른 모듈의 import에 영향을 줄 수 있습니다. data 모듈이 com.example.data 패키지를 가지고 있고 domain 모듈이 해당 클래스를 사용하는 경우, 식별자 변경 후 모든 종속 모듈의 import를 업데이트하세요. Android Gradle Plugin 버전 8.0+는 build.gradle에서 자동 namespace 생성을 통해 이 프로세스를 간소화합니다.

코드를 통한 Package Name 확인

현재 Application ID를 얻으려면 BuildConfig 클래스를 사용하세요: BuildConfig.APPLICATION_ID. 이는 코드의 조건부 로직, 환경 바인딩 또는 디버그 화면에 식별자 표시에 유용합니다. BuildConfig는 build.gradle을 기반으로 자동 생성됩니다.

// 런타임에 Application ID 가져오기
val packageName = BuildConfig.APPLICATION_ID
val packageManager = packageManager
val appInfo = packageManager.getPackageInfo(packageName, 0)

println("App version: ${appInfo.versionName} (${appInfo.versionCode})")
println("Package: $packageName")

게시 후 Package Name 변경

Google Play에 애플리케이션을 게시한 후 Package Name 변경은 완전히 새로운 제품을 만드는 것을 의미합니다. 시스템은 다른 Package Name으로 기존 애플리케이션을 업데이트하는 것을 허용하지 않으므로 식별자를 변경하는 결정은 스토어에서 프로젝트를 다시 시작하는 것과 같습니다.

Package Name 변경의 영향

Package Name을 변경하면 다음이 손실됩니다: 모든 평점 및 리뷰, 설치 통계, Google Services 통합(마이그레이션되지 않은 경우), Firebase 프로젝트 링크(새 google-services.json 생성 필요). 사용자는 자동 업데이트를 받지 못합니다 — 스토어에서 새 애플리케이션을 보게 됩니다.

• 평점 및 리뷰 — 이전 앱에 남아 있으며 이전되지 않음
• 설치 통계 — 새 Package Name에 대해 재설정됨
• Firebase 프로젝트 — 새 google-services.json 구성 및 모든 서비스 재구성 필요
• 사용자 — 자동 업데이트를 받지 않으며 별도로 알려야 함

Package Name 변경이 정당화되는 경우

Package Name 변경은 회사 리브랜딩, 애플리케이션을 다른 개발자 계정으로 이전, 또는 다른 지역용 별도 버전 생성 시 정당화될 수 있습니다. 어떤 경우든 변경 전에 이전 애플리케이션을 통해 사용자에게 알리고 데이터 전송이 포함된 마이그레이션 계획을 준비하는 것이 좋습니다. 마이그레이션 계획이 없으면 사용자는 구매한 콘텐츠, 구독 및 저장된 애플리케이션 데이터에 대한 액세스를 잃게 됩니다. 마이그레이션에는 SharedPreferences 또는 Room을 통한 데이터베이스 및 파일 전송이 포함됩니다.

Package Name을 변경하기 전에 새 식별자가 고유하고 명명 규칙을 준수하는지 확인하세요. 새 Package Name으로 Google Play에 새 애플리케이션을 만들고 별도 제품으로 게시하세요. 이전 애플리케이션 설명에 새 앱에 대한 링크를 제공하세요. 사용자를 리디렉션하기 위해 Google Play Custom Store Listing 사용을 고려하세요.