KappS 지식 베이스 · FAQ

Google Play의 버전 코드 관리 및 업데이트 호환성

FAQ 앱 심사 및 퍼블리싱

1. 두 필드, 완전히 다른 두 가지 역할. Google의 버전 관리 가이드는 두 필드를 따로 정의합니다. versionCode는 "내부 버전 번호로 사용되는 양의 정수입니다. 이 번호는 한 버전이 다른 버전보다 최신인지 판단하는 데 도움을 줍니다. 숫자가 높을수록 최신 버전임을 나타냅니다. 사용자에게 표시되는 버전 번호가 아니며, 그 번호는 versionName 설정으로 지정됩니다. Android 시스템은 versionCode 값을 사용하여 기기에 현재 설치된 버전보다 낮은 versionCode의 APK를 설치하지 못하게 함으로써 다운그레이드를 방지합니다." versionName은 "사용자에게 표시되는 버전 번호로 사용되는 문자열입니다... versionName은 사용자에게 표시되는 유일한 값입니다." Play Console 도움말은 개발자들이 가장 먼저 부딪히는 운용상의 세부 사항을 덧붙입니다. versionCode는 "새 릴리스마다 일관되게 증가하는 32비트 정수"이고, versionName은 "사용자에게 표시되는 버전 번호를 나타내는 문자열로, 예를 들어 '1.0.0', '1.1 Beta', '2.0'과 같습니다." 마케팅 팀은 4.9를 5.0으로 자유롭게 바꿀 수 있지만, 정수가 증가하지 않는 순간 업로드는 실패합니다. (§https://developer.android.com/studio/publish/versioning / §https://support.google.com/googleplay/android-developer/answer/17367361)

2. Play의 업로드 심사 기준은 단 하나의 비교이며, 엄격한 초과(>) 조건입니다. 공식 업데이트 요건은 세 가지 필수 조건을 다음 순서로 명시합니다. "업데이트된 Android 앱 번들의 패키지 이름은 현재 버전과 동일해야 합니다. 버전 코드는 현재 버전보다 커야 합니다... 업데이트된 앱 번들은 현재 버전과 동일한 서명으로 서명되어야 합니다." 바이너리가 다르면 같아도 된다는 예외 경로는 없으며, 심사에서 내세울 여지도 없습니다. 이 검사는 기계적으로 이루어지며 사람이나 정책 봇이 릴리스를 보기 전에 실행됩니다. (§https://support.google.com/googleplay/android-developer/answer/9859350)

3. versionCode는 절대 재사용할 수 없으며, 이 풀은 트랙이 아니라 앱에 속합니다. 버전 관리 가이드는 단호합니다. "이전 버전에 이미 사용한 versionCode로는 Play 스토어에 APK를 업로드할 수 없습니다." 콘솔에서는 익숙한 심사 거절 메시지 "Version code X has already been used."로 나타납니다. 카운터가 애플리케이션(패키지 이름)에 연결되어 있기 때문에 내부 테스트, 비공개 테스트, 공개 테스트, 프로덕션 모두 동일한 시퀀스에서 번호를 가져옵니다. 동일한 빌드를 두 번째 트랙에 올리려면 다시 업로드하지 않고 "라이브러리에서" 추가하면 됩니다. 별도의 패키지 이름(자체 applicationId를 가진 스테이징 앱이나 화이트라벨 버전)은 자체 시퀀스를 가지며, 바로 이 때문에 디버깅 중에 버전 코드를 소모하기에 스테이징 앱이 적합합니다. (§https://developer.android.com/studio/publish/versioning)

4. 상한은 2,100,000,000이며, 여기에 도달하는 것은 지원 티켓이 아니라 종료 상태입니다. 두 문서 모두 같은 숫자를 명시합니다. "Google Play에서 versionCode에 허용되는 최댓값은 2100000000입니다." 콘솔 페이지는 그 결과를 분명히 밝힙니다. "앱의 versionCode가 최대 한도에 도달하거나 초과하면 해당 애플리케이션에 대해 Google Play에 새 APK나 앱 번들을 더 이상 업로드할 수 없습니다. 즉, 사용자를 위한 버그 수정, 새로운 기능, 호환성 업데이트가 더 이상 불가능합니다." Google가 제시하는 유일한 해결책은 "Google Play이 지원을 제공할 수 있을지도 모른다"는 것뿐입니다. 리셋 버튼이 아니라 가능성일 뿐입니다. 따라서 운영 중인 앱으로 수익을 내는 비즈니스에게 이 숫자는 유효 기간이 있는 자산이며, 그에 맞게 사용해야 합니다. (§https://support.google.com/googleplay/android-developer/answer/17367361)

5. 개발자들이 예상하는 것보다 세 가지 번호 부여 관행이 사용 가능한 범위를 훨씬 빠르게 소진합니다. 초 단위 유닉스 타임스탬프는 이미 17억 9천만을 넘었고 빌드마다 올라갑니다. 브랜치, 플레이버, 형제 앱이 공유하는 글로벌 CI 실행 카운터는 실패한 파이프라인에서도 계속 앞으로 달려갑니다. 그리고 "빌드 번호 = 커밋 수" 방식은 모노레포 이력이 재작성되는 순간 폭발합니다. Play가 직접 제시하는 완화책 목록은 다음과 같습니다. "지속 가능한 버전 코드 전략을 도입하세요. 사용 가능한 범위의 급격한 소진을 피하면서 점진적이고 일관된 증가를 보장하는 버전 코드 생성 전략을 구현하세요. 버전 코드 사용량을 모니터링하세요. 앱의 버전 코드 진행 상황을 정기적으로 추적해 한도에 근접하는 시점을 예측하세요. 자동 검사를 구현하세요. 빌드 및 릴리스 프로세스에 검사를 통합해 지나치게 높은 버전 코드 값에 대해 경고하거나 사용을 막으세요." (§https://support.google.com/googleplay/android-developer/answer/17367361)

6. 코드는 게시가 아니라 업로드로 소모됩니다. 내부 테스트에 업로드하거나, 번들을 라이브러리에 보관하거나, 나중에 폐기할 초안 릴리스를 만들어도 번호는 그대로 소모됩니다. "라이브러리에서 추가"가 존재하는 이유가 바로 이것으로, 같은 바이너리를 이후 릴리스에 다시 붙일 수는 있어도 다시 만들 수는 없습니다. "통과하는지 보려고 콘솔에 빌드를 올려보는" 사람은 시도할 때마다 버전 번호 하나를 지불합니다. 파이프라인이 빠른 장수 앱에서는 이렇게 여유 있던 간격이 몇 년 뒤 위기가 됩니다.

7. 중단은 롤백이 아닙니다. Android은 다운그레이드를 허용하지 않기 때문입니다. 1번 항목에서 인용한 시스템 수준 규칙(기기에 이미 설치된 것보다 낮은 버전 코드는 설치되지 않음)이 바로 사용자를 지난주 빌드로 되돌리는 콘솔 버튼이 없는 이유입니다. Google의 단계적 배포 가이드도 운영상 같은 말을 합니다. "기존 앱 번들에서 문제를 발견하면 수정된 앱 번들로 새 릴리스를 만들어 배포하세요." 따라서 잘못된 프로덕션 빌드에서 진정한 복구 방법은 심사가 허용하는 한 빠르게, 문제가 된 빌드보다 높은 버전 코드로 새 번들을 출시하는 것뿐입니다. 그래서 번호 체계의 비상 슬롯은 필요해지기 전에 미리 마련해 두어야 합니다. (§https://support.google.com/googleplay/android-developer/answer/6346149)

8. 단계적 배포는 업데이트 전용 도구이며, 절대 자동으로 진행되지 않습니다. "단계적 배포를 사용하면 앱 업데이트를 프로덕션 트랙과 테스트 트랙에 출시할 수 있습니다. 단계적 배포를 사용하면 업데이트가 일부 사용자에게만 적용되며, 시간이 지나면서 비율을 높일 수 있습니다. 단계적 배포는 앱 업데이트에만 사용할 수 있으며, 앱을 최초로 게시할 때는 사용할 수 없습니다." 그리고 릴리스를 일주일 동안 5%에 묶어두는 함정은 바로 이것입니다. "앱의 단계적 배포 비율은 자동으로 증가하지 않습니다." 릴리스를 담당하는 사람이 직접 돌아와서 비율을 올려야 하며, Google 쪽에서 대신 해주는 것은 없습니다. 또한 사용자는 단계적 업데이트를 받았다는 사실을 통지받지 못합니다. "단계적 배포로 앱 버전을 받은 사용자에게는 알림이 전송되지 않습니다." 따라서 단계적 릴리스에 대한 피드백은 리뷰가 아니라 바이탈과 지원 채널에서 끌어와야 합니다. (§https://support.google.com/googleplay/android-developer/answer/6346149)

9. 단계적 배포 중단이 실제로 바꾸는 것. "문제를 발견한 경우 단계적 배포를 중단하여 앱에서 문제를 겪는 사용자 수를 최소화할 수 있습니다. 단계적 배포를 중단하면 기존 단계적 배포에서 추가 사용자에게 앱 버전이 제공되지 않습니다. 단계적 배포 버전에서 이미 앱 버전을 받은 사용자는 해당 버전에 그대로 남습니다." 사람들이 놓치는 두 가지 결과가 따릅니다. 재개해도 대상이 재편성되지 않으며("릴리스의 배포를 중단한 후 재개하면 동일한 사용자 집합에 영향을 줍니다"), 이전 릴리스가 완료되기 전에 새 릴리스를 시작하면 같은 코호트가 재사용됩니다("이전 릴리스의 배포를 완료하기 전에 새 릴리스를 단계적으로 배포하면, 새 릴리스는 배포 비율에 따라 이전 릴리스와 동일한 사용자 그룹을 사용합니다"). 수정 사항은 새로운 표본이 아니라 같은 불운한 5%에 의해 검증됩니다. (§https://support.google.com/googleplay/android-developer/answer/6346149)

10. 전체 배포된 릴리스의 배포 중단: 무엇이 바뀌고 무엇이 바뀌지 않는가. "앱에서 치명적인 문제를 발견한 경우, 배포 중단 기능은 신규 및 기존 사용자가 영향을 받는 버전의 앱을 설치하거나 업데이트하지 못하도록 하여 사용자 불편을 최소화합니다. 전체 릴리스를 중단하면 이전 버전의 앱이 신규 사용자와 중단된 버전을 사용하지 않는 모든 사용자에게 제공됩니다." 이는 서비스 제공 변경일 뿐 삭제가 아닙니다. "중단된 버전은 더 이상 사용자에게 제공되지 않지만", 이미 해당 버전을 받은 기기는 다운그레이드 방지 때문에 계속 그 버전을 유지합니다. 같은 페이지에 세 가지 제한이 명시되어 있습니다. "내부 테스트 트랙을 제외한 모든 트랙에서" 작동하며, "트랙의 최초 릴리스는 중단할 수 없고", "이전 릴리스에 정책 위반이 있는 경우 중단된 릴리스 대신 사용할 수 없습니다." 이후 재개 시에는 임의의 비율로 배포할 수 있으며, 이것이 수정된 빌드를 점진적으로 다시 도입하는 올바른 방법입니다. (§https://support.google.com/googleplay/android-developer/answer/16285429)

11. 트랙당 진행 중인 릴리스는 하나뿐이어야 합니다. 그리고 이것이 바로 최악의 순간에 핫픽스를 막는 원인입니다. "진행 중인 릴리스가 있으면 새 릴리스를 만들 수 없습니다. 단계적 릴리스를 100%까지 배포하거나, 게시 개요 페이지에서 변경사항을 제거하고 게시되지 않은 릴리스를 모두 폐기하세요." 방치된 20% 단계적 배포, 절반만 끝난 심사 제출, 프로덕션 트랙에 그대로 남아 있는 관리형 게시 보류는 긴급 빌드와 여러분 사이를 가로막습니다. 이를 방지하는 습관은 릴리스할 때마다 마무리하는 것입니다. 100%까지 배포하거나 제거 후 폐기하고, 릴리스 로그에 상태를 기록해 다음 담당자(혹은 미래의 여러분)가 새 릴리스를 열지 못하는 콘솔을 디버깅하는 일이 없도록 하세요. (§https://support.google.com/googleplay/android-developer/answer/9859348)

12. 10년간의 릴리스에도 견디는 번호 체계. 고정 폭 구간을 두어 계산이 읽히도록 하고 상한은 멀리 두십시오. versionCode = major * 100000 + minor * 1000 + patch * 10 + hotfix로 하면 major는 1부터 20999까지, minor는 1,000개, patch/hotfix는 각각 10개까지 쓸 수 있습니다. 빌드 스크립트에서 실제 사용 범위가 21억보다 눈에 띄게 낮도록 유지하고, 계산된 값이 예컨대 15억으로 설정한 소프트 임계값을 넘으면 업로드가 아니라 빌드를 실패시키십시오. CI에는 업로드 시에만 증가 권한을 주고 커밋마다 증가시키지 마십시오. 모든 탐색용 빌드는 스테이징 applicationId로 실행해 그 코드가 다른 시퀀스에서 소비되게 하고, 출시된 versionCode를 출시 노트에 기록해 숫자가 구전 지식이 아니라 검증 가능한 정보가 되게 하십시오.

13. 위 사항을 한 번에 잡아내는 업로드 전 점검표: (a) versionCode가 목표 트랙만이 아니라 모든 트랙에서 이 앱에 업로드된 모든 코드보다 엄격히 커야 한다. (b) versionName은 표시용 텍스트일 뿐이므로 자유롭게 반복되거나 건너뛸 수 있다. (c) 패키지 이름은 그대로이고 번들은 실제 서명 키로 서명되어야 한다. 앱 서명 키를 변경하면 "이미 앱을 설치한 내부 및 비공개 트랙 사용자는 더 이상 업데이트를 받지 못합니다. 이 사용자들은 업데이트를 받으려면 앱을 삭제하고 다시 설치해야 합니다"라는 결과가 따른다. (d) 업그레이드 경로는 이전 버전이 이미 설치된 기기에서 테스트해야 한다. 깨끗한 설치로는 업데이트에 대해 아무것도 증명할 수 없기 때문이다. (e) 번호가 2,100,000,000 상한과 자체 소프트 임계값을 넘지 않는지 확인한다. (f) 대상 트랙에 미완료된 다른 릴리스가 없어야 한다. (g) 현재 대역에 긴급 코드 슬롯이 아직 남아 있어야 한다. 이 모든 항목은 판단이 아니라 필드 또는 상태이므로, 목록 전체를 누군가의 기억이 아니라 CI와 릴리스 점검표에 둘 수 있다. (§https://support.google.com/googleplay/android-developer/answer/9859348)