본문 바로가기
직접 업데이트

사용자가 앱을 열 때 최신 버전을 보여주세요

기본적으로 live update는 다운로드 후 한 세션이 지나야 적용됩니다. Direct update 모드에서는 그 대신 앱 실행 시 스플래시 화면 뒤에서 적용되므로, 사용자가 보는 첫 화면이 이미 새 버전입니다.

autoUpdate: atInstall, onLaunch 또는 always
업데이트가 준비될 때까지 스플래시 화면 유지
Delta 다운로드로 대기 시간을 줄입니다

문제점

백그라운드 업데이트는 한 세션 뒤에 적용됩니다

기본 모드에서는 어떻게 될까요?

1

사용자가 앱을 실행합니다

앱은 이미 가지고 있는 bundle로 시작합니다. updater는 새 bundle이 있는지 확인하고 백그라운드에서 다운로드합니다.

2

세션은 현재 버전으로 실행됩니다

해당 세션이 유지되는 동안, 사용자는 수정 사항이 반영되기 전의 code를 계속 사용하게 됩니다.

3

다음 resume 시점에 업데이트가 적용됩니다

사용자가 앱을 떠나면 updater가 새 bundle을 설치합니다. 사용자는 다음에 앱을 열 때 이를 보게 됩니다.

대부분의 릴리스에서는 이 방식이 적절한 트레이드오프입니다. 업로드 직후 시작되는 세션에서 새 code가 반드시 실행되어야 한다면, direct update 모드를 사용하세요.

첫 번째 세션이 중요한 경우

결제 또는 로그인 흐름 오류

수정 사항이 적용되기 전, 앱을 여는 사용자가 오류 화면을 다시 마주하게 해서는 안 됩니다.

웹 레이어 보안 패치

다음 세션이 아니라 앱 실행 시점부터 패치된 JavaScript가 실행되길 원할 때.

날짜가 정해진 변경

사용자가 처음 마주하는 화면에 반드시 최신 상태로 표시되어야 하는 약관, 공지 또는 이벤트 콘텐츠.

솔루션

Direct Update 모드에서 달라지는 점

업데이터는 앱 실행 시 스플래시 화면이 떠 있는 동안 업데이트를 확인합니다. 새 bundle이 있으면 스플래시 화면이 사라지기 전에 다운로드해 적용합니다.

기본 모드 (atBackground)

1
사용자가 앱을 실행합니다
2
앱은 현재 버전을 표시합니다
3
백그라운드에서 업데이트를 다운로드합니다
4
다음 resume 시점에 업데이트가 적용됩니다

앱 실행 시 대기 시간이 없습니다. 사용자는 한 세션 뒤에 업데이트를 확인합니다.

Direct 모드 (onLaunch)

1
사용자가 앱을 열면 스플래시 화면이 유지됩니다.
2
업데이터가 변경된 파일을 확인하고 다운로드합니다.
3
업데이트가 적용되고 스플래시가 사라지며 새 버전이 나타납니다.

사용자는 첫 화면에서 새 버전을 봅니다. 다운로드하는 동안 스플래시 화면에서 기다립니다.

업데이트 동작 문서

작동 방식

Direct 업데이트 설정 방법

Direct 모드는 네이티브 설정이라 스토어 빌드에 먼저 포함됩니다. 이후 모든 live update가 이를 따릅니다. 명령어는 Capgo 문서를 참고하세요.

  1. 스플래시 화면 플러그인을 추가하고 모드를 선택하세요

    @capacitor/splash-screen 설치 후, capacitor.config.ts에서 autoUpdate, autoSplashscreen, launchAutoHide를 설정하세요.

    npm install @capacitor/splash-screen
    npx cap sync
    
    // capacitor.config.ts
    plugins: {
      CapacitorUpdater: {
        autoUpdate: 'onLaunch', // or 'atInstall' / 'always'
        autoSplashscreen: true,
        keepUrlPathAfterReload: true,
      },
      SplashScreen: { launchAutoHide: false },
    }
    Splash screen 처리
  2. 스토어 빌드에 config를 포함해 배포하세요

    capacitor.config는 네이티브 앱에 컴파일되므로, 새 모드는 다음 스토어 릴리스와 함께 사용자에게 적용됩니다. Capgo Build로 클라우드에서 생성할 수 있습니다.

    npx @capgo/cli@latest build request --platform ios
    npx @capgo/cli@latest build request --platform android
    Capgo Build 문서
  3. 번들을 델타 방식으로 업로드하세요

    사용자는 앱 실행 시 다운로드를 기다리므로 변경된 파일만 전송하세요. CLI가 즉시 적용 모드를 감지하고 델타 업로드를 안내합니다.

    npx @capgo/cli@latest bundle upload --channel production --delta
    Delta updates 문서
  4. 자동 롤백을 켜 두세요

    앱이 시작되면 notifyAppReady()를 호출하세요. 새 번들이 시작되지 않으면 기기는 마지막으로 정상 작동한 번들로 돌아갑니다.

    import { CapacitorUpdater } from '@capgo/capacitor-updater'
    
    await CapacitorUpdater.notifyAppReady()
    notifyAppReady() 문서

앱에 맞는 모드를 선택하세요

Direct updates는 트레이드오프입니다. 앱 실행 시 잠시 기다리는 대신 첫 화면에서 새 버전을 볼 수 있습니다.

세 가지 즉시 적용 모드

capacitor.config.ts에서 autoUpdate를 설정하세요. 각 모드는 사용자가 기다리는 동안 업데이트가 적용될 시점을 결정합니다.

  • atInstall: 네이티브 앱을 새로 설치하거나 스토어에서 업데이트한 직후에만 적용
  • onLaunch: 앱이 완전히 종료된 상태에서 시작될 때(cold start) 적용
  • always: 앱이 열려 있는 중에도 포그라운드 체크마다 실행
Updater 설정

3

autoUpdate의 즉시 적용 모드

Splash screen 처리

Direct 모드에는 launchAutoHide를 false로, autoSplashscreen을 true로 설정한 @capacitor/splash-screen이 필요합니다. Updater는 업데이트가 적용되거나 업데이트가 필요 없다고 판단하면 Splash screen을 숨깁니다.

  • SplashScreen.hide()를 수동으로 호출할 필요 없음
  • keepUrlPathAfterReload를 사용하면 리로드 후에도 사용자가 동일한 라우트에 유지됩니다
  • Splash screen이 숨겨진 후 추가 작업이 필요한 경우 appReady를 리스닝하세요
Splash screen 처리

autoSplashscreen

모든 Direct 모드에서 필수

고려해야 할 트레이드오프

사용자는 앱 실행 시 다운로드를 기다리고, 업데이트가 있으면 사용 중에도 앱을 다시 로드할 수 있습니다. 두 경우 모두 대비하세요.

  • 변경된 파일만 다운로드되도록 --delta로 업로드하세요
  • 앱 상태를 저장하고 복원해 새로고침해도 사용자 진행 상황이 유지되게 하세요
  • 한 세션 지연이 괜찮다면 기본 모드를 유지하세요
Delta updates 문서

--delta

모든 direct update 업로드에 권장

Direct updates를 사용해야 하는 경우

현재 세션에서 새 code를 실행해야 할 때 direct 모드를 사용하세요. 그 외에는 기본 모드를 유지하세요.

치명적 버그 수정

결제, 로그인 또는 데이터 버그로 이전 code를 한 세션 더 실행하기엔 부담스러운 경우.

첫 실행 온보딩

atInstall은 새로 설치하거나 스토어에서 업데이트한 직후 최신 bundle을 적용하므로, 신규 사용자가 현재 onboarding으로 시작합니다.

날짜 기반 콘텐츠

사용자가 앱을 열 때 최신 상태여야 하는 이벤트 페이지, 공지사항 또는 약관.

보안 패치

앱 실행 시점부터 적용되어야 하는 웹 레이어 보안 수정 사항. native code의 수정은 여전히 스토어 출시가 필요합니다.

정기 릴리스

스타일 수정이나 작은 기능 때문에 앱 실행 시 기다릴 필요는 거의 없습니다. 기본 모드에서는 다음 세션에 적용됩니다.

몇 시간씩 열려 있는 앱

always 모드에서는 주기적 확인(기본 10분마다)으로 앱이 열려 있는 동안 업데이트를 적용할 수 있습니다. 이 기능에 의존하기 전에 상태를 저장하세요.

앱 실행 대기 시간 단축

앱 실행 시 대기 시간은 업데이트 확인과 다운로드를 합한 것입니다. Delta update는 변경된 파일만 다운로드합니다.

~50ms

평균 API 지연 시간

델타

변경된 파일만 다운로드됩니다

10억+

월간 업데이트 전송량

Capacitor로 빌드된 앱

공공 정보 앱은 콘텐츠를 즉시 수정해야 합니다

긴급 대응, 보건, 공공 서비스 앱은 오류가 있는 체크리스트, 리소스 링크, 지역별 공지를 수정하는 데 며칠씩 기다릴 수 없습니다. Direct updates를 사용하면 수정이 승인되는 즉시 웹 레이어를 반영할 수 있습니다.

FEMA 앱 아이콘 날씨

FEMA

작은 콘텐츠 오류가 긴급 상황으로 이어질 수 있는 비상 안내.

Google Play 설치 수
160만
스토어 평점
4.0
Conecte SUS 앱 아이콘 의료

연결하기

승인된 문구 변경을 빠르게 전달해야 하는 의료 기록 및 안내 화면.

Google Play 설치 수
2,770만
스토어 평점
4.6
e-Título 앱 아이콘 소셜

e-Título

기기 간 버전 안전성 안내가 중요한 시민 신원 워크플로.

Google Play 설치 수
5,490만
스토어 평점
4.8

고객 사례

Capgo로 배포하는 팀들의 이야기

5.0/5 개발 팀 평점 9,400+ 팀 리뷰 보기

카필

NuTriQ 창립자

“App Store의 전체 리뷰 주기를 기다리지 않고 프로덕션 OTA 업데이트를 즉시 푸시할 수 있다는 점은 운영상 엄청난 이점이었습니다.”

Sergiu S의 사진

Sergiu S

drivolino GmbH 리드 개발자

“Capgo Capacitor Updater 플러그인 덕분에 업데이트 배포 방식이 완전히 바뀌었습니다. 며칠씩 걸리던 작업이 이제는 단 몇 분 만에 끝납니다.”

Luis Dominguez의 사진

루이스 도밍게스

돈을 내는 사람이 주인이다

“Capgo를 쓰기 시작한 뒤로 모든 게 더 빨라졌고, 일상도 놓치지 않으면서 사용자에게 마땅히 줘야 할 시간을 쓸 수 있게 됐습니다.”

자주 묻는 질문

Direct Updates에 대한 FAQ

사용 시점, 설정 방법, 출시 시 비용을 알아봅니다.

Direct Updates와 기본 백그라운드 모드 중 무엇을 사용해야 하나요?

대부분의 릴리스에는 기본 모드를 사용하세요. 출시 시 대기 시간이 없고, 사용자는 한 세션 뒤에 업데이트를 받습니다. 업로드 후 시작되는 세션에서 새 code가 반드시 실행되어야 하는 경우(예: 결제 오류 수정 또는 웹 레이어 보안 수정)에는 Direct 모드를 사용하세요.

업데이트 동작 문서

atInstall, onLaunch, always의 차이점은 무엇인가요?

atInstall은 네이티브 앱을 새로 설치하거나 스토어에서 업데이트한 직후에만 업데이트를 즉시 적용하며, 그 이후에는 기본 모드처럼 동작합니다. onLaunch는 앱이 종료된 상태에서 시작될 때 즉시 적용됩니다. always는 포그라운드로 전환될 때마다 확인하고, 사용자가 앱을 사용 중이어도 다운로드가 끝나는 즉시 업데이트를 적용합니다.

Updater 설정

Splash Screen 플러그인이 왜 필요한가요?

Direct 모드는 사용자가 기다리는 동안 업데이트를 적용합니다. @capacitor/splash-screen, autoSplashscreen: true, launchAutoHide: false가 없으면 리로드 전에 화면이 깜빡이거나 이전 UI가 보일 수 있습니다. 이 설정들을 사용하면 업데이트가 적용되거나 업데이트가 필요 없다고 판단될 때까지 스플래시 화면이 유지됩니다.

Splash screen 처리

live update를 사용하여 Direct Updates를 켤 수 있나요?

아니요. autoUpdate는 capacitor.config에 있고, 이 값은 빌드 시점에 네이티브 앱으로 읽힙니다. 새 설정은 스토어 릴리스로 배포하세요. 그 이후에는 모든 live update이 새 모드를 따릅니다.

네이티브 호환성 문서

현재 config에서 directUpdate를 사용 중인데, 계속 지원되나요?

directUpdate는 deprecated되었지만 여전히 감지됩니다. 해당 값은 atInstall, onLaunch, always 같은 autoUpdate 모드와 일치합니다. 다음 네이티브 릴리스에서 설정을 autoUpdate로 옮기세요.

Updater 설정

다음 수정 사항을 첫 화면에 바로 적용하세요

트라이얼 기간에 테스트 빌드에서 direct update 모드를 써 보고, 본인 앱에서 실행 대기 시간을 측정해 보세요.

14일 무료 체험. 신용카드가 필요 없습니다.