앱 버전 관리 가이드
문서 정보
- 작성일: 2026-03-17
- 최종 업데이트: 2026-03-17
- 버전: v1.0.0
TL;DR
DB의 app_version 테이블에서 minimum_version을 올리면 강제 업데이트, latest_version을 올리면 권장 업데이트가 발동된다.
목차
개요
앱 시작 시 클라이언트가 GET /app/version-check 엔드포인트를 호출하여 현재 버전의 업데이트 필요 여부를 확인한다. 서버는 DB에 저장된 버전 정보와 비교하여 강제(FORCE), 권장(RECOMMEND), 불필요(NONE) 중 하나를 응답한다.
핵심 개념
업데이트 판단 흐름
버전 체계 (Semantic Versioning)
v{major}.{minor}.{patch} → v2.3.1
major: 호환성이 깨지는 변경 → 강제 업데이트 대상
minor: 새 기능 추가 → 권장 업데이트
patch: 버그 수정 → 선택 업데이트
DB 테이블 구조
| 컬럼 | 설명 | 예시 |
|---|---|---|
platform | 플랫폼 (unique) | ios, android |
latest_version | 최신 버전 | 3.0.0 |
minimum_version | 최소 지원 버전 | 2.5.0 |
store_url | 스토어 URL | https://apps.apple.com/app/id123456 |
update_message | 업데이트 안내 (nullable) | 중요한 보안 업데이트가 있습니다. |
운영 가이드
새 버전 배포 시 순서
1. 앱 v3.0.0 개발 완료
2. App Store / Play Store에 심사 제출
3. ⏳ 스토어 승인 대기
4. ✅ 스토어 배포 완료 확인
5. DB latest_version → "3.0.0" 업데이트
6. (필요 시) minimum_version 상향 → 강제 업데이트 발동
주의: 반드시 스토어 배포 완료 후 DB를 업데이트할 것. 순서가 바뀌면 사용자가 스토어에서 업데이트를 찾을 수 없다.
DB 업데이트 방법
Prisma Studio (권장)
pnpm db:cli # → studio 선택
브라우저에서 app_version 테이블을 열고 값을 수정한다.
SQL 직접 실행
-- 권장 업데이트 (latest_version만 올림)
UPDATE app_version
SET latest_version = '3.0.0', updated_at = NOW()
WHERE platform = 'ios';
-- 강제 업데이트 (minimum_version도 올림)
UPDATE app_version
SET latest_version = '3.0.0', minimum_version = '2.5.0', updated_at = NOW()
WHERE platform = 'ios';
-- 업데이트 메시지 변경
UPDATE app_version
SET update_message = '중요한 보안 업데이트가 있습니다.', updated_at = NOW()
WHERE platform = 'ios';
언제 뭘 올릴까?
| 상황 | 변경 대상 | 결과 |
|---|---|---|
| 새 버전 배포 (일반) | latest_version만 올림 | 기존 사용자에게 권장 업데이트 팝업 |
| API 호환성 깨짐 | minimum_version도 올림 | 구버전 사용자 강제 업데이트 |
| 보안 취약점 패치 | minimum_version도 올림 | 구버전 사용자 강제 업데이트 |
| 메시지만 변경 | update_message만 수정 | 팝업 메시지 내용 변경 |
초기 데이터 삽입
최초 1회, 플랫폼별 데이터를 삽입해야 한다:
INSERT INTO app_version (platform, latest_version, minimum_version, store_url, update_message)
VALUES
('ios', '1.0.0', '1.0.0', 'https://apps.apple.com/app/id{APP_ID}', NULL),
('android', '1.0.0', '1.0.0', 'https://play.google.com/store/apps/details?id={PACKAGE_NAME}', NULL);
API 사용법
요청
GET /app/version-check?platform=ios&version=2.1.0
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
platform | string | O | ios 또는 android |
version | string | O | 현재 앱 버전 (x.y.z 형식) |
- 인증 불필요 (Public 엔드포인트)
응답
{
"updateType": "RECOMMEND",
"latestVersion": "3.0.0",
"minimumVersion": "2.5.0",
"storeUrl": "https://apps.apple.com/app/id123456",
"message": "새로운 기능이 추가되 었습니다."
}
| 필드 | 타입 | 설명 |
|---|---|---|
updateType | string | FORCE / RECOMMEND / NONE |
latestVersion | string | 최신 버전 |
minimumVersion | string | 최소 지원 버전 |
storeUrl | string | 스토어 URL |
message | string | null | 업데이트 안내 메시지 |
클라이언트 처리 가이드
| updateType | 앱 동작 |
|---|---|
| FORCE | 닫기 불가 팝업 → "업데이트" 버튼만 → storeUrl로 이동 |
| RECOMMEND | 닫기 가능 팝업 → "업데이트" / "나중에" 버튼 |
| NONE | 아무것도 안 함, 정상 진입 |
FAQ
Q: iOS와 Android 버전을 다르게 관리할 수 있나요?
네. app_version 테이블은 platform별로 별도 행이므로 iOS는 3.0.0, Android는 2.8.0처럼 독립적으로 관리할 수 있습니다.
Q: 스토어 심사 중에 DB를 미리 업데이트해도 되나요?
안 됩니다. 스토어에 아직 새 버전이 없으므로, 사용자가 업데이트 팝업을 보고 스토어에 가도 업데이트할 수 없는 상황이 됩니다. 반드시 스토어 배포 완료 후 DB를 업데이트하세요.
Q: update_message를 null로 두면 어떻게 되나요?
클라이언트가 기본 메시지를 표시합니다. 특별한 안내가 필요한 경우에만 메시지를 설정하면 됩니다.
Q: 강제 업데이트를 해제하려면?
minimum_version을 낮추면 됩니다. 예를 들어 minimum_version을 1.0.0으로 설정하면 모든 사용자가 강제 업데이트 대상에서 제외됩니다.
관련 문서
- ADR-001: 앱 버전 관리 및 강제 업데이트 (
docs/maintained/infra/app-version/adr/001-app-version-management.md)
변경 이력
| 버전 | 날짜 | 변경 내용 |
|---|---|---|
| v1.0.0 | 2026-03-17 | 초기 문서 작성 - 운영 가이드, API 사용법, FAQ 포함 |