ADR-0027: native 인앱 업데이트에 Android Play In-App Update(Play Core)를 도입한다
- Status: Accepted
- Date: 2026-10-29 (라이브러리 교체·반응형 버튼 반영 2026-11-06)
- 관련: HMH-10392 (이 ADR) · ADR-0006·ADR-0017 는 무관. 기존 업데이트 경로:
features/app-update(isDropped→ForceUpdate)·lib/appUpdate.ts(promptUpdateRequired)·OTA(expo-updates,features/ota)
Context
현재 네이티브 업데이트 UX 는 셋뿐이다.
- 강제:
AppVersionGate가getIsDroppedVersion(백엔드 “지원종료” 판정)이면ForceUpdate전체화면을 띄워 스토어로 리다이렉트한다(유저가 앱을 나갔다 스토어에서 찾아 설치 후 복귀 — 이탈·이탈률 손실). - 미인식 딥링크:
promptUpdateRequired(lib/appUpdate.ts)가 Alert “업데이트가 필요해요” →Linking.openURL(STORE_URL). - 더보기 버전 정보:
isUpToDate로 “최신 아님” 표기만(능동 유도 없음).
즉 “새 버전이 있지만 아직 지원되는” 구간에 앱 내 업데이트 수단이 전혀 없다. OTA(expo-updates)는 JS 만 갱신하고, 네이티브 변경은 스토어 재빌드가 필요한데 그 설치를 앱 안에서 유도·수행할 길이 없었다.
Android 는 Play Core In-App Update API 로 앱 내 다운로드/설치가 가능하다(flexible/immediate). iOS 는 Apple 정책상 앱 내 바이너리 업데이트가 불가해 스토어 유도만 가능하다. 환경은 RN 0.86 + New Architecture(Fabric/TurboModules)다.
검토한 대안
| 대안 | 채택 안 한 이유 |
|---|---|
| 기존 스토어 리다이렉트 유지 | 앱 이탈 + 수동 탐색이라 최신화 전환이 저해될 것으로 보고(별도 측정값은 없음, 예상), “지원중 새 버전” 유도 수단이 아예 없다 |
sp-react-native-in-app-updates (처음 채택 → 철회) | 커뮤니티 표준이고 README 상 New Arch 지원이나, New Architecture 에서 startUpdate 가 promise 를 settle 하지 못해 hang(버튼 무반응). getCurrentActivity() null 경로를 reject 하지 않고 SendIntentException 만 catch — 이슈 #213 계열 잔존 버그. checkNeedsUpdate(액티비티 불필요)는 동작, startUpdate(액티비티 사용)만 깨짐. 내부테스트 트랙 실측으로 확인 |
@chankruze/react-native-in-app-updates (채택) | zero-dep 네이티브 TurboModule(New-Arch-first). startUpdate 가 currentActivity null 체크 + catch-all 로 모든 경로를 reject/resolve → 절대 hang 안 함(최악=스토어 폴백). flexible/immediate·status/result 리스너 API 동등. 내부트랙 실측 end-to-end 동작 |
| 직접 네이티브 모듈 작성 | chankruze 가 바로 그 얇은 TurboModule(~150줄)이라 자체 유지보수 불필요. 미유지보수화되면 재검토 |
| 새 능동 체크/배너로 업데이트를 적극 유도 | 새 유도 표면은 성가심·범위 확대라 제외. 기존 “스토어 유도” 플로우만 Android 에서 인앱 업데이트로 바꾸고(새 플로우 추가 안 함), flexible/immediate 를 각 기존 지점에 매핑한다 |
Decision
@chankruze/react-native-in-app-updates 를 도입한다. Android 는 Play Core(flexible/immediate), iOS 는 라이브러리의 iTunes 체크로 스토어 유도.
- 통합 서비스
apps/native-app/src/features/app-update/appUpdateService.ts: 라이브러리를 래핑(checkAppUpdate/requestFlexibleUpdate/requestImmediateUpdate/completeFlexibleUpdate/isFlexibleDownloadPending/ 공용startFlexibleUpdateWithRestartPrompt). 모든 경로가 fail-safe 로 스토어 폴백(iOS·Play 불가 시 스토어). - 범위 원칙: 기존 “스토어 유도” 플로우를 Android 인앱 업데이트로 바꾼다(기존 트리거 유지). 단 더보기 버튼은 진행 상태를 반영하도록 UI 를 확장한다(아래).
- immediate(강제):
ForceUpdate의 “스토어로 이동” 버튼 → AndroidrequestImmediateUpdate()(Play immediate), 불가/iOS 는 기존 스토어. (AppVersionGate의 isDropped→ForceUpdate렌더 흐름은 불변) - flexible(소프트): ①
lib/appUpdate.ts의promptUpdateRequired(미인식 딥링크)는 alert 기반startFlexibleUpdateWithRestartPrompt유지. ②MoreScreenContent의FooterVersion은 상태 반응형 버튼(useFlexibleUpdate훅): 대기(“업데이트”) → 다운로드 중(“업데이트 준비 중…”, 비활성) → 완료(“업데이트 적용”, 탭 시completeFlexibleUpdate+재시작). 다운로드 완료 시 alert 도 띄우고, 앱 재진입 시 설치 대기(DEVELOPER_TRIGGERED) 감지 → “업데이트 적용” 복원(isFlexibleDownloadPending). iOS=기존 스토어. - Play Core gradle 의존성은 라이브러리 autolinking(TurboModule codegen)으로 반영된다(내부트랙 빌드로 실증, 별도 config plugin 불필요).
Consequences
좋아지는 것
- Android 유저가 앱을 떠나지 않고 업데이트를 받는다(flexible=백그라운드, immediate=앱 내 강제) → 최신화율↑·강제 업데이트 이탈↓.
- 강제·소프트·딥링크 유도가 단일 서비스로 통합되고, 기존 스토어 리다이렉트 로직을 재사용한다.
감수하는 것
- 네이티브 모듈이라 OTA 불가 — 새 스토어 빌드(native-release)에만 반영된다. 이 기능 자체는 핫픽스가 안 된다.
- Play in-app update 는 Play 설치본(내부테스트 트랙+)에서만 실동작 — dev client/sideload/CI 에서 Play UI 를 검증할 수 없다(결정 로직만 유닛테스트, 실 플로우는 트랙 빌드로).
- iOS 는 여전히 앱 내 설치 불가(스토어 유도) — 플랫폼 비대칭이 남는다.
- 신생·소규모 라이브러리(chankruze, ⭐ 적음) 유지보수에 의존한다. 미유지보수화되면 포크/자체 모듈화(chankruze 는 zero-dep ~150줄이라 포크 비용 낮음).
교훈
- “New Architecture 지원”이라고 적힌 라이브러리도 활동(액티비티) 실행 경로에서 깨질 수 있다(getCurrentActivity null). New-Arch 네이티브 모듈은 promise 를 반드시 settle(모든 실패를 reject) 하는지가 관건 — 안 그러면 UI 가 hang 한다. 실동작 검증은 Play 내부테스트 트랙 실빌드로만 가능하다(유닛테스트로 못 잡음).
- 내부테스트 트랙 테스트는 versionCode 를 영구 소진한다. 긴 디버깅으로 다수 소진(이 PR 은 42~59) → 다음 릴리즈 versionCode 는 소진 최대치보다 커야(auto-bump 가 Play 소진분을 모르므로 릴리즈 담당이 수동 확인).
이 결정을 다시 열어야 할 때
- 라이브러리가 RN New Architecture 신버전에서 깨지거나 미유지보수 상태가 되면 → 포크/직접 모듈 재검토.
- Apple 이 앱 내 업데이트를 허용하면(현재 불가) → iOS 대칭 재검토.
- Expo 가 공식 in-app-update 모듈을 제공하면 → 교체 검토.
Last updated on