Skip to Content
DecisionsADR-0027: native 인앱 업데이트에 Android Play In-App Update(Play Core)를 도입한다

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 의 “스토어로 이동” 버튼 → Android requestImmediateUpdate()(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