업데이트 동작
이 플러그인의 설치 단계와 전체 마크다운 가이드가 포함된 설정 프롬프트를 복사하세요.
Capgo 앱에 업데이트를 배포할 때, 사용자들이 최대한 빨리 그 업데이트를 받기를 바라실 겁니다. 하지만 다운로드를 기다리거나 세션 중간에 앱을 재시작하도록 강제해서 사용자 경험을 방해하고 싶지는 않으실 겁니다.
Capgo의 업데이트 동작은 빠른 업데이트 제공과 사용자 경험 방해 최소화 사이의 균형을 맞추도록 설계되었습니다.
기본 업데이트 흐름
“기본 업데이트 흐름” 섹션기본적으로 Capgo는 다음과 같이 앱 업데이트를 처리합니다:
-
앱이 포그라운드로 전환될 때, Capgo 플러그인은 새 업데이트가 있는지 확인합니다. 앱이 열려 있는 동안에는 설정된 반복 타이머에 따라 다시 확인합니다
periodCheckDelay(기본값 10분). -
업데이트가 발견되면 사용자가 현재 앱 버전을 계속 사용하는 동안 백그라운드에서 다운로드가 진행됩니다.
-
다운로드가 완료되면, Capgo는 사용자가 앱을 백그라운드로 전환할 때까지 기다립니다.
-
사용자가 다음에 앱을 포그라운드로 전환하면, 업데이트된 버전이 실행됩니다.
이 흐름을 통해 사용자는 업데이트 프롬프트로 방해받거나 다운로드를 기다릴 필요 없이 항상 최신 버전의 앱을 사용할 수 있습니다.
이 방식을 사용하는 이유
“이 방식을 사용하는 이유” 섹션백그라운드 또는 앱 종료 시점에 업데이트를 적용하면 사용자 경험 측면에서 다음과 같은 주요 이점이 있습니다:
-
사용자는 세션 도중 업데이트 프롬프트로 방해받거나 다운로드를 기다릴 필요가 없습니다.
-
세션 사이에 업데이트가 매끄럽게 적용되므로 앱을 실행할 때마다 항상 최신 상태를 유지합니다.
-
활성 사용자를 방해할 걱정 없이 자주 업데이트를 배포할 수 있습니다.
주요 단점은 사용자가 앱을 백그라운드로 보낸 뒤 빠르게 다시 열면, 그 사이에 업데이트가 적용되어 저장하지 않은 상태를 잃을 수 있다는 점입니다.
이를 완화하려면 다음을 권장합니다:
-
상태를 자주 저장하고 앱이 다시 열릴 때 자연스럽게 복원하세요.
-
앱 상태의 많은 부분을 변경하는 지나치게 잦은 업데이트는 피하세요.
-
민감한 플로우에서는 업데이트 동작을 커스텀하는 것을 고려해 보세요 (아래 참고).
업데이트 적용 시점 커스텀하기
“업데이트 적용 시점 커스텀하기” 섹션어떤 경우에는 업데이트가 적용되는 정확한 시점을 직접 제어하고 싶을 수 있습니다. 예를 들어, 사용자가 진행 중인 플로우를 완료한 뒤에 업데이트되도록 하거나, 서버 측 변경에 맞춰 앱 업데이트 시점을 조정하고 싶을 수 있습니다.
Capgo는 업데이트 설치 전에 충족되어야 하는 조건을 지정할 수 있는 setDelay 함수를 제공합니다:
import { CapacitorUpdater } from '@capgo/capacitor-updater';
await CapacitorUpdater.setMultiDelay({ delayConditions: [ { kind: 'date', value: '2023-06-01T00:00:00.000Z', }, { kind: 'background', value: '60000', }, ],});이 예시는 2023년 6월 1일 이후이면서 앱이 백그라운드로 전환된 지 최소 60초가 지난 경우에만 업데이트 설치를 지연시킵니다.
사용 가능한 지연 조건은 다음과 같습니다:
date: 특정 날짜/시간이 지난 후에 업데이트를 적용하도록 대기합니다.background: 앱이 백그라운드로 전환된 후 최소 일정 시간이 지난 뒤 업데이트를 적용하도록 대기합니다.nativeVersion: 업데이트를 적용하기 전에 최소 버전 이상의 네이티브 바이너리가 설치될 때까지 대기합니다.kill: 다음 앱 종료(kill) 이벤트가 발생할 때까지 업데이트 적용을 대기합니다.
이 조건들을 조합하여 업데이트 설치 시점을 정밀하게 제어할 수 있습니다.
업데이트 즉시 적용하기
“업데이트 즉시 적용하기” 섹션중요한 업데이트이거나 앱 상태가 매우 단순한 경우, 백그라운드나 종료(kill) 이벤트를 기다리지 않고 다운로드되는 즉시 업데이트를 적용하고 싶을 수 있습니다. Capgo는 다음을 통해 이를 지원합니다: autoUpdate Capacitor 설정의 policy 항목.
autoUpdate 은(는) 파일에 설정됩니다 capacitor.config.ts JavaScript code에서는 아닙니다. 다음 값을 지원합니다:
false또는'off': 자동 업데이트 확인 비활성화true또는'atBackground'(기본값): 포그라운드 체크할 때마다 자동으로 확인 및 다운로드한 뒤, 다음번에 앱이 백그라운드로 전환될 때 업데이트를 적용합니다'atInstall': 즉시 적용은 새로 설치하거나 네이티브 앱 스토어에서 업데이트한 직후에만 하고, 그 외에는"atBackground"동작 방식'onLaunch': 앱이 종료된 상태에서 포그라운드로 전환될 때(콜드 스타트)만 즉시 적용합니다. 첫 확인 이후에는 다음 동작으로 대체합니다."atBackground"동작 방식'always': 포그라운드로 전환될 때마다 확인하고, 업데이트가 있으면 즉시 적용합니다.'onlyDownload': 자동으로 확인 및 다운로드하며, 다음 이벤트를 발생시킵니다.updateAvailable, 다음 번들을 설정하거나 업데이트를 자동으로 적용하지 않습니다.
Live Updates 없이 Native Build 테스트하기
“Live Updates 없이 Native Build 테스트하기” 섹션자세한 내용은 Live Updates 없이 Native Build 테스트하기 native-version, channel-policy, CI 구성 안전 장치를 참고하세요.
import { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = { plugins: { CapacitorUpdater: { autoUpdate: 'always', // or 'atInstall' for updates only on app install/update autoSplashscreen: true, keepUrlPathAfterReload: true, }, SplashScreen: { launchAutoHide: false, // Required for instant apply with autoSplashscreen }, },};
export default config;사용하면 autoUpdate: 'always', Capgo는 포그라운드로 전환될 때마다 확인하고, 사용자가 앱을 사용 중이더라도 해당 확인 중 다운로드가 완료되는 즉시 업데이트를 적용합니다. 다음 설정으로 제어되는 주기적 확인은 periodCheckDelay 앱이 열려 있는 동안 동일한 즉시 적용 동작을 트리거할 수 있습니다.
참고로, autoUpdate 는 네이티브 설정이므로, instant apply 모드를 사용하려면 JavaScript code에서 추가적인 처리가 필요합니다.
적용 없이 자동 다운로드
“적용 없이 자동 다운로드” 섹션Capgo가 업데이트를 자동으로 확인하고 다운로드하되 자동으로 적용하지는 않게 하려면 다음을 사용하세요 autoUpdate: 'onlyDownload':
const config: CapacitorConfig = { plugins: { CapacitorUpdater: { autoUpdate: 'onlyDownload', }, },};이 모드에서 플러그인은 번들 다운로드 후 updateAvailable 이벤트를 발생시킵니다. 앱은 이 시점에 CapacitorUpdater.set() 를 호출하거나 자체 업데이트 프롬프트를 표시할 수 있습니다.
스플래시 화면 자동 처리
“자동 스플래시 스크린 처리” 섹션즉시 적용 모드("atInstall", "onLaunch", "always") 필요 autoSplashscreen 및 @capacitor/splash-screen (버전 7.6.0부터 사용 가능). 플러그인을 설치한 후, Capgo이 스플래시를 숨길 때까지 스플래시를 표시 상태로 유지하세요:
const config: CapacitorConfig = { plugins: { CapacitorUpdater: { autoUpdate: 'always', // or 'atInstall' autoSplashscreen: true, // Automatically hide splashscreen keepUrlPathAfterReload: true, }, SplashScreen: { launchAutoHide: false, }, },};시기 autoSplashscreen 이 활성화되어 있습니다:
- 업데이트가 적용되면 플러그인이 자동으로 스플래시 스크린을 숨깁니다
- 업데이트가 필요 없으면 플러그인이 자동으로 스플래시 스크린을 숨깁니다
- 직접
appReady이벤트를 수신하거나SplashScreen.hide()
스플래시 화면이 사라진 후 추가 작업
“스플래시가 숨겨진 후 추가 작업” 섹션유지하세요 autoSplashscreen: true를 호출할 필요가 없습니다. 업데이트가 준비된 후 추가 로직이 필요하면 appReady 도 수신하세요. 이를 위해 스플래시 플러그인이나 autoSplashscreen 를 건너뛰지 마세요:
import { CapacitorUpdater } from '@capgo/capacitor-updater';
CapacitorUpdater.addListener('appReady', () => { // Update is applied. autoSplashscreen already hid the splash.});
CapacitorUpdater.notifyAppReady();이 appReady 이벤트는 앱이 초기화를 마치고 대기 중인 업데이트를 모두 적용한 뒤 한 번 발생합니다.
설정 keepUrlPathAfterReload 대상 true 즉시 적용 모드 사용 시. 업데이트로 인해 앱이 다시 로드될 때 현재 URL 경로를 유지합니다.
즉시 적용 모드를 사용하면 중요한 버그 수정이나 보안 패치를 배포하는 데 유용할 수 있지만, 몇 가지 트레이드오프가 있습니다:
- 업데이트가 적용될 때 사용자에게 짧은 깜빡임이나 로딩 상태가 보일 수 있습니다:
@capacitor/splash-screen이 항목이 누락되었거나autoSplashscreen이 항목이 활성화되어 있지 않은 경우입니다. - 업데이트가 앱 상태나 UI를 수정하는 경우, 사용자가 세션 중간에 방해가 되는 변경 사항을 볼 수 있습니다.
- 앱 내 사용자 위치가 손실될 수 있습니다:
keepUrlPathAfterReload이 항목이 설정되지 않으면 사용자가 혼란스러울 수 있습니다. - 매끄러운 전환을 보장하려면 상태를 저장하고 복원하는 과정을 신중하게 처리해야 합니다.
즉시 적용을 활성화하는 경우, 다음을 권장합니다:
- 다음과 함께 업로드
npx @capgo/cli@latest bundle upload --delta다운로드가 사용자 경험을 저하시키지 않도록. - 설치
@capacitor/splash-screen및 설정autoSplashscreen: true포함launchAutoHide: false. - 설정
keepUrlPathAfterReload대상true앱에서 사용자 위치를 유지하기 위해 - 사용자 진행 상황을 잃지 않도록 필요에 따라 앱 상태를 저장하고 복원합니다.
- 갑작스러운 전환, 상태 손실, 혼란스러운 위치 변경이 없도록 앱의 업데이트 동작을 철저히 테스트합니다.
대부분의 경우 기본 업데이트 동작은 업데이트를 빠르게 전달하면서 불편을 최소화하는 최적의 균형을 제공합니다. 하지만 특정 요구 사항이 있는 앱이라면 Capgo을 통해 업데이트 적용 시점과 방식을 유연하게 사용자 지정할 수 있습니다.
Update Behavior에서 계속하기
섹션 제목: “Update Behavior”에서 계속하기사용 중이라면 업데이트 동작 live update 배포를 계획하려면, 다음과 연결하세요 Capgo Live Update Capgo Live Updates의 제품 워크플로우를 보려면, 개요 Overview의 구현 상세를 보려면, 기능 Features의 구현 상세를 보려면, 업데이트 유형 구현 세부 사항은 Update Types를 참고하고, 시작하기 시작하기 페이지의 구현 상세 내용.
