앱 MVP Android 버전 코드와 버전명: 내부 릴리스·사용자 안내·업데이트 확인을 나누는 5가지 기준

앱 MVP Android 버전 코드와 버전명: 내부 릴리스·사용자 안내·업데이트 확인을 나누는 5가지 기준

Android 앱을 배포할 때 1.2.0이라고 적힌 화면만 보고 “이번 업데이트가 준비됐다”고 판단하면 놓치는 것이 생깁니다. 사용자에게 보이는 버전명과 Android·Google Play가 새 릴리스를 비교하는 내부 번호는 역할이 다르기 때문입니다. 한쪽은 고객지원·공지·오류 재현에 쓰이고, 다른 한쪽은 같은 앱의 새 빌드인지 판단하는 기준이 됩니다.

이 글은 Android MVP에서 내부 릴리스 번호, 사용자 표시 버전, 배포 후보 확인을 같은 완료 신호로 섞지 않기 위한 범위 결정 문서입니다. 특정 앱의 심사 통과, 스토어 반영, 사용자 업데이트를 보장하지 않습니다.

1. 먼저 분리하기: versionCode는 내부 순서, versionName은 사용자 언어

Android 공식 문서에서 versionCode는 내부 버전 번호입니다. 양의 정수로 두며 숫자가 클수록 새 릴리스로 판단됩니다. 이미 기기에 설치된 앱보다 낮은 versionCode의 APK는 설치되지 않도록 Android가 다운그레이드를 막는 데도 이 값이 쓰입니다. 반대로 versionName은 사용자가 보는 문자열입니다. 1.2.0, 1.2 베타처럼 팀이 이해하기 쉬운 표시 방식을 정할 수 있지만, 그 문구 자체가 새 빌드 여부를 판정하지는 않습니다.

Android의 앱 버전 관리 가이드는 두 값을 Gradle 빌드 파일에서 정의하는 예시와 각 역할을 설명합니다. MVP 단계에서는 숫자 규칙을 복잡하게 만들기보다, 누가 다음 내부 번호를 정하고 누가 사용자 표시 문구를 확정하는지부터 정하는 편이 안전합니다.

2. 두 번째 기준: ‘같은 기능 수정’과 ‘다음 배포 후보’를 구분하기

코드를 고쳤다는 사실은 아직 스토어에 올릴 새 후보가 준비됐다는 뜻이 아닙니다. 같은 기능 수정이라도 테스트 빌드, 내부 테스트, 공개 배포 후보가 각각 있을 수 있습니다. 팀이 versionName만 바꾸거나, 반대로 내부 번호만 올리고 변경 내용을 남기지 않으면 테스트 결과와 사용자 문의를 서로 연결하기 어려워집니다.

1. 이전에 배포·테스트한 내부 릴리스 번호

2. 이번 후보의 내부 릴리스 번호

3. 사용자에게 표시할 버전명

4. 변경한 핵심 흐름과 재현한 기기·계정 조건

5. 다음 단계가 테스트인지, 심사 제출인지, 실제 공개인지

이 표는 특정 번호 체계를 강요하지 않습니다. 핵심은 이전 후보보다 큰 내부 번호와, 사람이 읽을 수 있는 표시 버전을 독립적으로 확인하는 것입니다. Android 공식 문서는 각 successive release에 더 큰 versionCode를 사용해야 하며, 이미 사용한 값으로는 Play에 APK를 올릴 수 없다고 안내합니다.

3. 세 번째 기준: Google Play 업데이트 조건을 빌드 성공과 구분하기

빌드가 끝났다고 기존 사용자에게 업데이트가 전달된 것은 아닙니다. Google Play의 업데이트 안내는 업데이트 Android App Bundle이 현재 버전과 같은 package name을 사용하고, 더 큰 version code를 가지며, 같은 서명으로 서명돼야 한다고 설명합니다. 즉 버전 번호 확인은 서명과 패키지 식별을 대체하지 않습니다.

Google Play는 업데이트 제출 뒤 Dashboard에서 In review 상태가 보일 수 있고, 게시된 뒤에도 기존 사용자에게 전달되는 데 시간이 걸릴 수 있다고 설명합니다. 그래서 QA 종료, 콘솔 업로드, 검토 통과, 사용자 수신 확인을 하나의 “업데이트 완료”로 묶지 않는 것이 좋습니다.

앱 번들 자체의 범위와 기기별 제공을 먼저 정리하려면 Android 앱 번들 배포 기준도 함께 보세요. 이 글은 번들의 구성보다, 같은 앱의 릴리스 번호와 사용자 안내를 어떻게 연결할지에 초점을 둡니다.

버전 규칙과 출시 체크를 제품 요구사항으로 정리해야 한다면, 유인어스가 핵심 사용자 흐름과 배포 제약을 기준으로 MVP 범위를 함께 검토할 수 있습니다. MVP 범위 상담하기

4. 네 번째 기준: 자동 증가 규칙보다 되돌릴 수 있는 기록을 먼저 만들기

내부 번호를 자동 증가시키는 방식은 편리할 수 있지만, 규칙이 실제 배포 이력과 어긋나면 오히려 추적이 어려워집니다. 예를 들어 테스트 채널에 올린 후보와 실제 공개 후보가 어떤 관계인지 모르면, 오류 제보를 받은 뒤 어떤 빌드를 봐야 하는지 판단하기 어렵습니다.

이 중 빌드 식별자와 상태는 Android가 정해 주는 값이 아니라 운영을 위한 기록입니다. 팀의 도구와 흐름에 맞춰 정하되, 존재하지 않는 배포 상태나 사용자 수신을 기록하지 마세요. 특히 되돌림이 필요할 때는 사용자 표시 버전이 비슷해도 내부 번호, 서명, 실제 Play 상태를 함께 다시 확인해야 합니다.

5. 다섯 번째 기준: 출시 전에는 코드·콘솔·사용자 안내를 한 번에 대조하기

마지막 점검은 “버전 번호를 올렸다”가 아니라 “누가 무엇을 근거로 이 후보를 다음 단계로 보낼 수 있는가”입니다. Gradle 설정의 versionCode와 versionName, 생성한 번들의 package name·서명, Play Console의 릴리스 상태, 변경 공지가 서로 같은 후보를 말하는지 확인하세요.

출시 전 체크리스트

• 이전 배포 후보와 이번 후보의 내부 릴리스 번호를 나란히 확인했는가

• 사용자 표시 버전이 고객지원·QA 기록과 같은 문자열인가

• package name과 서명이 기존 공개 앱의 업데이트 조건과 맞는가

• 테스트·제출·검토·게시 상태를 구분해 기록했는가

• 사용자에게 전달됐다는 사실은 실제 확인 전까지 추정하지 않았는가

• 되돌림 또는 긴급 수정 때 참조할 빌드 식별자를 남겼는가

버전명은 안내를 돕고, 내부 릴리스 번호는 순서를 돕습니다. 둘 다 필요하지만 어느 하나가 배포 완료를 증명하지는 않습니다.

자주 묻는 질문

versionCode와 versionName 중 어느 것이 사용자에게 보이나요?

Android 공식 문서는 versionName을 사용자에게 표시되는 문자열로 설명합니다. versionCode는 내부 비교용 양의 정수입니다. 따라서 고객지원 문구에는 versionName을 쓰되, 재현·업데이트 확인에는 내부 번호도 함께 기록하는 방식이 좋습니다.

같은 versionCode로 수정된 앱을 다시 올릴 수 있나요?

Android 공식 문서는 각 successive release에 더 큰 versionCode를 사용하라고 안내하며, 이미 사용한 versionCode로는 Play에 APK를 업로드할 수 없다고 설명합니다. 실제 제출 전에는 최신 Play Console 안내와 현재 릴리스 상태를 확인하세요.

버전명만 바꾸면 Google Play 업데이트 조건이 충족되나요?

아닙니다. Google Play의 업데이트 안내에 따르면 업데이트 번들은 현재 앱과 같은 package name, 더 큰 version code, 같은 서명이 필요합니다. 버전명은 사용자 표시용이므로 이 조건을 대신하지 않습니다.

업로드가 끝나면 기존 사용자가 바로 업데이트받나요?

그렇게 단정할 수 없습니다. Google Play는 제출 뒤 검토 상태가 있을 수 있고, 게시 뒤에도 기존 사용자에게 업데이트가 전달되는 데 시간이 걸릴 수 있다고 안내합니다. 콘솔의 실제 상태와 사용자 수신을 별도로 확인하세요.

앱의 릴리스 규칙, 테스트 범위, 고객 안내를 같은 기준으로 정리하고 싶다면 유인어스에 MVP 범위 문의하기