앱 버전 관리 시스템 (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 | 초기 문서 작성 - 시스템 개요, 동작 방식, 운영 방법 |