앱을 다 만들었다고 끝이 아니다. 지금까지 ./gradlew installDebug로 내 폰에만 깔아봤다면, 이제는 다른 사람 폰에도 깔릴 수 있는 형태로 만들어야 한다. 그게 릴리스 빌드고, 그걸 사람들이 받을 수 있게 올리는 게 Play 스토어 배포다.

처음 해보면 "서명"이라는 개념에서부터 막힌다. 왜 앱에 서명을 해야 하고, 키가 왜 두 종류나 있는지부터 보자.

왜 서명이 필요한가

안드로이드는 앱을 설치할 때 "이 앱이 진짜 그 개발자가 만든 건지"를 확인한다. 그 확인 수단이 서명이다. 디버그 빌드(installDebug)는 안드로이드 스튜디오가 자동으로 만들어주는 임시 디버그 키로 서명되는데, 이 키는 아무나 가진 거라 스토어에 올릴 수 없다. 릴리스용으로는 나만 가진 키로 서명해야 한다.

서명 키가 두 종류인 이유: 업로드 키 vs 앱 서명 키

여기서 처음 헷갈리는 부분이 나온다. Play 스토어에 "Play 앱 서명(Play App Signing)"이라는 기능이 있는데, 이걸 쓰면 키가 두 개로 나뉜다.

• 업로드 키(upload key): 내가 들고 있는 키. AAB 파일에 서명해서 Play Console에 올릴 때 쓴다.
• 앱 서명 키(app signing key): Google이 보관하는 키. 실제로 사용자 기기에 설치되는 최종 APK는 이 키로 다시 서명돼서 나간다.

왜 이렇게 나눠놨을까. 업로드 키는 내 컴퓨터에 파일로 있으니 분실하거나 유출될 위험이 있다. 만약 분실해도, 앱 서명 키는 Google이 안전하게 보관하고 있으니 "업로드 키를 분실했다"고 Google에 요청하면 새 업로드 키로 교체할 수 있다. 반면 앱 서명 키 자체를 잃어버리면 그 앱은 영영 업데이트를 못 올리게 된다. 그래서 그 중요한 키는 Google이 대신 들고 있어주는 구조다.

처음 앱을 만들 때는 이 구조를 신경 쓸 필요 없이, Android Studio가 안내하는 대로 업로드 키 하나만 만들면 나머지는 Play Console이 알아서 처리해준다.

1. 서명 키 만들기

Android Studio에서 Build → Generate Signed Bundle / APK를 선택하면, 키가 없는 경우 Create new...로 새 키스토어(keystore)를 만들 수 있다. 이때 입력하는 값들:

• Key store path: .jks 파일이 저장될 위치. 이 파일 자체가 키다. 절대 잃어버리면 안 되고, git에 올리면 안 된다.
• Password: 키스토어 비밀번호, 키 비밀번호. 이것도 잃어버리면 안 된다.
• Alias: 키 이름. 보통 앱 이름으로 짓는다.
• Validity (years): 유효 기간. 넉넉하게 25년 이상으로 잡는 게 보통이다. (너무 짧게 잡으면 몇 년 뒤 "서명이 만료됐다"는 사고가 난다.)

커맨드라인으로 직접 만들 수도 있다.

keytool -genkey -v -keystore my-release-key.jks \
  -keyalg RSA -keysize 2048 -validity 10000 \
  -alias my-key-alias

2. 비밀번호를 코드에 박지 않기

키스토어 경로와 비밀번호를 build.gradle.kts에 그대로 적으면 git에 올라가서 유출된다. 그래서 따로 파일로 뺀다.

# keystore.properties (git에 올리지 않음, .gitignore에 추가)
storeFile=../my-release-key.jks
storePassword=여기에_비밀번호
keyAlias=my-key-alias
keyPassword=여기에_비밀번호

// app/build.gradle.kts
val keystorePropertiesFile = rootProject.file("keystore.properties")
val keystoreProperties = Properties()
if (keystorePropertiesFile.exists()) {
    keystoreProperties.load(FileInputStream(keystorePropertiesFile))
}

android {
    signingConfigs {
        create("release") {
            storeFile = file(keystoreProperties["storeFile"] as String)
            storePassword = keystoreProperties["storePassword"] as String
            keyAlias = keystoreProperties["keyAlias"] as String
            keyPassword = keystoreProperties["keyPassword"] as String
        }
    }
    buildTypes {
        getByName("release") {
            signingConfig = signingConfigs.getByName("release")
            isMinifyEnabled = true
            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
        }
    }
}

keystore.properties를 꼭 .gitignore에 추가하자. 이 파일이 깃허브 공개 저장소에 올라가는 사고가 생각보다 흔하다.

3. AAB로 빌드하기

예전에는 APK를 올렸지만, 지금 Play 스토어는 AAB(Android App Bundle)를 기본으로 요구한다. APK는 모든 기기용 리소스(화면 밀도별 이미지, CPU 아키텍처별 바이너리 등)를 다 한 파일에 욱여넣은 거고, AAB는 그 조각들을 따로 담아서 Google이 "이 사용자 기기에는 이 조각들만 조합해서 보내줘"라고 처리하게 만든 형식이다. 그래서 사용자가 받는 설치 파일 용량이 더 작아진다.

Build → Generate Signed Bundle / APK에서 Android App Bundle을 선택하고 앞서 만든 서명 키를 지정하면 app-release.aab 파일이 나온다. 커맨드라인으로는:

./gradlew bundleRelease

결과물은 app/build/outputs/bundle/release/app-release.aab에 생긴다.

4. Play Console에 처음 등록하기

Play Console(play.google.com/console)에서 새 앱을 만들면 대략 이런 순서로 진행된다.

• 앱 이름, 기본 언어, 앱/게임 구분, 무료/유료 선택
• 스토어 등록정보 작성: 짧은 설명, 긴 설명, 스크린샷(폰/태블릿별 규격 있음), 아이콘, 그래픽 이미지
• 콘텐츠 등급 설문: 질문에 답하면 자동으로 등급이 매겨짐
• 타겟 사용자층, 개인정보처리방침 URL 등록 (데이터를 하나라도 수집하면 필수)
• 앱 액세스 권한: 로그인이 필요한 앱이면 테스트 계정 정보 제공
• 프로덕션(또는 먼저 내부 테스트/비공개 테스트) 트랙에 AAB 업로드

처음 올리는 앱은 바로 프로덕션에 공개하기보다 내부 테스트(internal testing) 트랙에 먼저 올려서 나와 소수의 테스터끼리 설치가 잘 되는지 확인하는 걸 권장한다. 트랙마다 심사 속도와 공개 범위가 다르다.

5. 업데이트할 때는 versionCode를 꼭 올린다

android {
    defaultConfig {
        versionCode = 2   // 매 업로드마다 반드시 증가
        versionName = "1.1.0"  // 사용자에게 보이는 버전, 자유롭게
    }
}

versionCode를 안 올리고 AAB를 다시 올리면 Play Console이 "이미 있는 버전 코드"라며 업로드를 거부한다. versionName은 사용자에게 보여주는 숫자라 자유롭게 지어도 되지만, versionCode는 내부 관리용 정수라서 매번 올려야 한다.

삽질 사례: 업로드했는데 "서명이 기존 앱과 다르다"는 에러

업로드하신 APK 또는 Android App Bundle이 이 앱에 대해 이전에 사용된 것과 다른 서명 인증서를 사용하여 서명되었습니다.

처음 앱을 만들 때 쓴 키스토어 파일을 나중에 잃어버리거나, 다른 컴퓨터에서 새로 만든 키스토어로 빌드해서 생기는 문제다. 업로드 키는 앱마다 한 번 정해지면 (분실 신고 전까지는) 계속 같은 걸 써야 한다. 그래서 키스토어 파일과 비밀번호를 안전한 곳에 따로 백업해두는 게 중요하다. 팀으로 작업한다면 1Password 같은 비밀번호 관리 도구나 CI 시스템의 시크릿 저장소에 넣어두는 걸 추천한다.

정리

• 릴리스 빌드는 나만의 서명 키로 서명해야 스토어에 올릴 수 있다.
• Play 앱 서명을 쓰면 업로드 키(내가 보관)와 앱 서명 키(Google이 보관)가 나뉘는데, 업로드 키를 잃어버려도 Google에 재발급을 요청할 수 있는 안전장치다.
• 키스토어 경로/비밀번호는 keystore.properties 같은 별도 파일로 빼서 git에서 제외한다.
• 지금 Play 스토어는 APK 대신 AAB(./gradlew bundleRelease)를 요구한다.
• 처음 앱은 내부 테스트 트랙부터 올려서 설치/동작을 확인하고 넘어가는 게 안전하다.
• 업데이트 때마다 versionCode를 올리는 걸 잊지 말 것.

(참고: Play App Signing, 업로드 키/앱 서명 키 구조는 Android 공식 문서 - 앱 서명에서 다시 확인하는 걸 권장한다. Play Console 화면 구성은 수시로 바뀌니, 실제 등록할 때는 그 시점의 화면을 기준으로 따라가면 된다.)

다음 글은 이 시리즈의 마지막 글이다. 하나의 To-do 앱을 1번 글의 컴포저블 기초부터 오늘의 배포까지, 구조가 어떻게 바뀌어왔는지 전체를 돌아보는 회고형 글로 정리한다.