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

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

기본적으로 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. 스토어 빌드에 설정을 포함하여 배포하세요

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

    npx @capgo/cli@latest build request --platform ios
npx @capgo/cli@latest build request --platform android
    Capgo 빌드 문서

  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: 앱을 새로 설치하거나 스토어에서 Native Build 업데이트를 받은 직후에만 적용
  • 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분 간격)를 통해 앱이 열려 있는 동안에도 업데이트를 적용할 수 있습니다. 적용 전 상태 저장을 권장합니다.

빠른 앱 실행

실행 시 대기 시간은 업데이트 확인과 download 시간에 결정됩니다. Delta update를 통해 변경된 파일만 download하여 시간을 단축하세요.

~50ms

API의 일반적인 지연 시간

Delta

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

10억+

월간 업데이트 전송량

팀 유형별 솔루션

팀의 니즈에 맞는 솔루션을 찾아보세요

Enterprise

멀티 앱, 멀티 팀 배포

스타트업

부담 없이 빠르게 배포

1인 개발자

14일 무료 체험, CLI 업로드

에이전시

여러 클라이언트 앱 관리

Capacitor로 빌드된 앱

공공 정보 앱에는 즉각적인 콘텐츠 수정이 필요합니다

긴급 재난, 보건, 시민 서비스 앱은 잘못된 체크리스트, 리소스 링크, 지역별 공지사항을 수정하기 위해 며칠씩 기다릴 수 없습니다. Direct updates를 사용하면 수정 사항이 승인되는 즉시 웹 레이어를 업데이트할 수 있습니다.

FEMA 앱 아이콘 날씨

FEMA

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

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

연결하기

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

Google Play 설치 수
27.7M
스토어 평점
4.6
e-Título 앱 아이콘 소셜

e-Título

여러 기기에서 버전 안전성을 보장하는 가이드가 필요한 시민 신원 확인 워크플로우.

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

고객 사례

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

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

Kapil

NuTriQ 창립자

“App Store의 전체 리뷰 과정을 기다리지 않고 프로덕션 OTA 업데이트를 즉시 배포할 수 있다는 점은 운영 측면에서 엄청난 이점입니다.”

Sergiu S의 프로필 사진

Sergiu S

drivolino GmbH, 리드 개발자

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

Luis Dominguez의 프로필 사진

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은 새로운 모드를 따르게 됩니다.

네이티브 호환성 문서

기존에 사용하던 directUpdate 설정도 여전히 지원되나요?

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

Updater 설정

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

트라이얼 기간 동안 테스트 빌드에서 direct update 모드를 사용해 보고, 실제 앱의 런칭 대기 시간을 직접 측정해 보세요.

14일 무료 체험. 카드 등록이 필요 없습니다.