앱 버전 관리 시스템 (App Version Management)
문서 정보
- 작성일: 2026-03-17
- 최종 업데이트: 2026-03-17
- 버전: v1.0.0
TL;DR
앱 업데이트가 나왔을 때, 사용자에게 강제 업데이트 또는 권장 업데이트 팝업을 보여주는 시스템입니다. 서버 DB에 저장된 버전 정보를 기준으로 판단하며, DB 값을 바꾸는 것만으로 즉시 정책이 적용됩니다.
목차
이게 뭔가요?
App Store / Google Play Store에 새 버전을 배포했을 때, 구버전 사용자에게 업데이트를 안내하는 기능입니다.
예를 들어:
- API가 크게 바뀌어서 구버전 앱이 동작하지 않을 때 → 강제 업데이트
- 새 기능이 추가되었을 때 → 업데이트 권장 팝업
어떻게 동작하나요?
- 앱이 시작되면 서버에 현재 버전을 보냅니다
- 서버는 DB에 저장된 최소 버전 / 최신 버전과 비교합니다
- 비교 결과에 따라 업데이트 유형을 응답합니다
업데이트 유형
| 유형 | 조건 | 앱 동작 | 사용 시점 |
|---|---|---|---|
| 🔴 FORCE | 현재 버전 < 최소 버전 | 앱 사용 불가, 스토어로 이동 | API 호환성 깨짐, 보안 취약점 |
| 🟡 RECOMMEND | 최소 버전 ≤ 현재 버전 < 최신 버전 | 팝업 표시, "나중에" 가능 | 새 기능, 개선사항 |
| 🟢 NONE | 현재 버전 ≥ 최신 버전 | 아무것도 안 함 | 이미 최신 버전 |
예시
DB 설정: minimumVersion = 2.5.0, latestVersion = 3.0.0
| 사용자 앱 버전 | 결과 | 설명 |
|---|---|---|
| 2.1.0 | FORCE | 2.5.0보다 낮으므로 강제 업데이트 |
| 2.5.0 | RECOMMEND | 최소 버전 이상이지만 3.0.0보다 낮음 |
| 2.8.0 | RECOMMEND | 최소 버전 이상이지만 3.0.0보다 낮음 |
| 3.0.0 | NONE | 최신 버전과 동일 |
| 3.1.0 | NONE | 최신 버전보다 높음 (테스트 빌드 등) |
운영 방법
새 버전 배포 시
순서가 중요합니다
반드시 스토어 배포가 완료된 후 DB를 업데이트하세요.
순서가 바뀌면 사용자가 업데이트 팝업을 보고 스토어에 가도 새 버전을 찾을 수 없습니다.
DB에서 변경하는 값
| 변경 대상 | 언제 | 효과 |
|---|---|---|
latest_version만 올림 | 일반적인 새 버전 배포 | 기존 사용자에게 권장 업데이트 팝업 |
minimum_version도 올림 | API 호환성 깨짐 / 보안 패치 | 구버전 사용자 강제 업데이트 |
update_message 수정 | 특별한 안내 필요 시 | 팝업에 표시되는 메시지 변경 |
iOS / Android 독립 관리
플랫폼별로 별도의 행(row)이 있으므로, iOS는 3.0.0이고 Android는 2.8.0처럼 각각 다른 버전으로 관리할 수 있습니다.
주의사항
| 상황 | 주의 |
|---|---|
| 스토어 심사 중 | DB를 미리 업데이트하지 않기 |
| 강제 업데이트 해제 | minimum_version을 낮추면 됨 |
| 메시지를 안 보여주고 싶을 때 | update_message를 NULL로 설정 → 클라이언트 기본 메시지 사용 |
| 최초 서비스 시작 | DB에 ios, android 2건의 초기 데이터 삽입 필요 |
관련 문서
- ADR-001: 앱 버전 관리 및 강제 업데이트 (
docs/maintained/infra/app-version/adr/001-app-version-management.md) - 기술적 의사결정 기록 - 앱 버전 관리 가이드 - 개발자를 위한 API 사용법 및 운영 상세 가이드
변경 이력
| 버전 | 날짜 | 변경 내용 |
|---|---|---|
| v1.0.0 | 2026-03-17 | 초기 문서 작성 - 시스템 개요, 동작 방식, 운영 방법 |