업데이트 동작

Capgo 앱에 업데이트를 배포할 때, 사용자가 가능한 한 빨리 업데이트를 받기를 원하실 겁니다. 하지만 사용자가 다운로드를 기다리게 하거나 앱 사용 중에 앱을 재시작하도록 강제하여 사용자 경험을 해치고 싶지는 않을 것입니다.

Capgo의 업데이트 방식은 빠른 업데이트 배포와 사용자 경험 저해 최소화 사이의 균형을 맞추도록 설계되었습니다.

기본 업데이트 흐름

기본적으로 Capgo는 다음과 같이 앱 업데이트를 처리합니다:

1. 앱이 포그라운드로 전환될 때, Capgo 플러그인은 새로운 업데이트가 있는지 확인합니다. 앱이 열려 있는 동안에는 다음 설정에 따라 주기적으로 다시 확인합니다: periodCheckDelay (기본값 10분).

2. 업데이트가 발견되면 사용자가 현재 앱 버전을 사용하는 동안 백그라운드에서 다운로드가 진행됩니다.

3. 다운로드가 완료되면, Capgo는 사용자가 앱을 백그라운드로 전환할 때까지 기다립니다.

4. 사용자가 앱을 다시 포그라운드로 가져오면, 업데이트된 버전이 실행됩니다.

이 흐름을 통해 사용자는 업데이트 프롬프트로 방해받거나 다운로드를 기다릴 필요 없이 항상 최신 버전의 앱을 사용할 수 있습니다.

팁

Capgo는 앱이 포그라운드로 전환될 때마다, 그리고 앱이 열려 있는 동안에는 설정된 타이머에 따라 주기적으로 업데이트를 확인합니다. periodCheckDelay 해당 간격을 제어합니다 (기본값 10분).

이 방식을 사용하는 이유

백그라운드 전환이나 앱 종료 시점에 업데이트를 적용하면 사용자 경험 측면에서 몇 가지 주요 이점이 있습니다:

• 사용자가 세션 도중에 업데이트 프롬프트로 방해받거나 다운로드를 기다려야 하는 일이 없습니다.

• 세션 사이에 업데이트가 매끄럽게 적용되므로, 앱을 실행할 때마다 항상 최신 상태를 유지할 수 있습니다.

• 활성 사용자를 방해할 걱정 없이 업데이트를 자주 배포할 수 있습니다.

주요 단점은 사용자가 앱을 백그라운드로 보냈다가 곧바로 다시 열면, 그 사이에 업데이트가 적용되어 저장하지 않은 상태를 잃을 수 있다는 점입니다.

이를 완화하려면 다음을 권장합니다:

• 상태를 자주 저장하고, 앱이 다시 열릴 때 자연스럽게 복구하세요.

• 앱 상태의 많은 부분을 변경하는 업데이트를 너무 자주 배포하는 것은 피하세요.

• 민감한 플로우에 대해서는 업데이트 동작을 커스텀하는 것을 고려하세요 (아래 참조).

업데이트 적용 시점 커스텀하기

때로는 업데이트가 적용되는 정확한 시점을 직접 제어하고 싶을 수 있습니다. 예를 들어, 사용자가 진행 중인 플로우를 완료한 후에 업데이트를 적용하거나, 서버 측 변경 사항에 맞춰 앱 업데이트를 조정해야 하는 경우입니다.

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: 업데이트 적용 전, 특정 최소 버전 이상의 Native Build가 설치될 때까지 대기합니다.
• kill: 다음 앱 종료(kill) 이벤트가 발생할 때까지 업데이트 적용을 대기합니다.

이 조건들을 조합하여 업데이트 설치 시점을 정밀하게 제어할 수 있습니다.

위험

참고: kill 해당 조건은 다른 조건들과 달리 다음 백그라운드 이벤트가 아닌 첫 번째 종료(kill) 이벤트 후에 업데이트를 트리거합니다. 이 불일치 문제는 향후 릴리스에서 수정될 예정입니다.

업데이트 즉시 적용하기

중요한 업데이트나 상태 관리가 매우 단순한 앱의 경우, 백그라운드나 종료(kill) 이벤트를 기다리지 않고 다운로드 즉시 업데이트를 적용하고 싶을 수 있습니다. Capgo는 다음 기능을 통해 이를 지원합니다: autoUpdate Capacitor 설정의 policy 항목.

즉시 적용을 위한 필수 항목: --delta, autoSplashscreen, SplashScreen

"atInstall", "onLaunch", 그리고 "always" 사용자가 기다리는 동안 업데이트를 적용하세요. 사용하세요: Delta 업데이트 그래서 변경된 파일만 다운로드됩니다. 전체 zip 업로드는 사용자 경험을 저하시킵니다.

이 모드들에는 다음도 필요합니다: @capacitor/splash-screen 및 autoSplashscreen: true 함께 SplashScreen.launchAutoHide: false. splash plugin이 없으면 업데이트 적용 중 화면이 깜빡이거나 이전 UI가 보일 수 있습니다.

호출 시 autoUpdate ~로 설정됨 "atInstall", "onLaunch", 또는 "always" 내 capacitor.config, CLI가 이를 감지합니다. 비대화형 환경에서는 Delta 업데이트를 자동으로 전송하며, 대화형 환경에서는 업로드 전 확인 프롬프트를 표시합니다. 기존 directUpdate 설정도 여전히 감지됩니다. 다음을 사용하여 --no-delta 전체 번들 업로드를 강제할 수 있습니다.

npx @capgo/cli@latest bundle upload --delta

autoUpdate is set in your capacitor.config.ts JavaScript code 파일이 아닌 파일입니다. 다음 값들을 지원합니다:

• false 또는 'off': 자동 업데이트 확인 비활성화
• true 또는 'atBackground' (기본값): 앱이 포그라운드로 전환될 때마다 자동으로 확인 및 다운로드하며, 다음 앱이 백그라운드로 전환될 때 업데이트를 적용합니다.
• 'atInstall': 앱을 새로 설치하거나 앱 스토어에서 Native Build 업데이트를 받은 직후에만 즉시 적용합니다. 그 외에는 "atBackground" 동작
• 'onLaunch': 앱이 종료된 상태에서 포그라운드로 전환될 때(cold start)만 즉시 적용합니다. 그 이후에는 다음 방식을 따릅니다: "atBackground" 동작
• 'always': 포그라운드로 전환될 때마다 확인하며, 업데이트가 있으면 즉시 적용합니다.
• 'onlyDownload': 자동으로 확인 및 다운로드하며, 다음 이벤트를 발생시킵니다: updateAvailable, 다음 번들을 설정하거나 업데이트를 자동으로 적용하지 않습니다.

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;

참고

중요: instant apply 모드는 플러그인이 실제로 업데이트를 확인할 때만 업데이트를 적용합니다. 기본적으로 앱이 포그라운드로 전환될 때와 앱이 열려 있는 동안 주기적인 타이머에 따라 확인을 수행합니다. periodCheckDelay 해당 간격을 제어합니다 (기본값 10분).

GCP는 autoUpdate: 'always', Capgo는 모든 포그라운드 전환 시 확인을 수행하며, 사용자가 앱을 사용 중이더라도 해당 확인 과정에서 다운로드가 완료되는 즉시 업데이트를 적용합니다. 다음 설정으로 제어되는 주기적 확인은 periodCheckDelay 앱이 열려 있는 동안 동일한 즉시 적용 동작을 트리거할 수 있습니다.

참고로, autoUpdate 는 네이티브 설정이므로, instant apply 모드를 사용하려면 JavaScript code에서 추가적인 처리가 필요합니다.

주의

즉시 적용 모드를 사용하려면 @capacitor/splash-screen 및 autoSplashscreen: true. 를 launchAutoHide: false SplashScreen 설정에 지정하세요(위와 동일). 그래야 업데이트가 완료될 때까지 스플래시 화면이 유지됩니다.

적용하지 않고 자동 다운로드

Capgo가 업데이트를 자동으로 확인하고 다운로드하되, 자동으로 적용하지는 않게 하려면 autoUpdate: 'onlyDownload':

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'onlyDownload',
    },
  },
};

이 모드에서 플러그인은 번들 다운로드 후 updateAvailable 를 발생시킵니다. 앱에서 직접 CapacitorUpdater.set() 를 호출하거나 자체 업데이트 프롬프트를 표시할 수 있습니다.

Splashscreen 자동 처리

Instant apply 모드 ("atInstall", "onLaunch", "always")에는 다음이 필요합니다: autoSplashscreen 및 @capacitor/splash-screen (7.6.0 버전부터 사용 가능). 플러그인을 설치한 후, Capgo가 숨길 때까지 splash를 유지하세요:

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'always', // or 'atInstall'
      autoSplashscreen: true, // Automatically hide splashscreen
      keepUrlPathAfterReload: true,
    },
    SplashScreen: {
      launchAutoHide: false,
    },
  },
};

호출 시 autoSplashscreen 가 활성화됨:

• 업데이트가 적용되면 플러그인이 자동으로 splashscreen을 숨깁니다
• 업데이트가 필요하지 않으면 플러그인이 자동으로 splashscreen을 숨깁니다
• 직접 다음을 감지할 필요는 없습니다: appReady 이벤트를 리스닝하거나 SplashScreen.hide()

Splashscreen이 숨겨진 후 추가 작업

유지 autoSplashscreen: true. 업데이트가 준비된 후 추가 로직이 필요하면 다음도 리스닝하세요: appReady . splash 플러그인을 건너뛰지 마세요. 또는 autoSplashscreen 이를 위해:

import { CapacitorUpdater } from '@capgo/capacitor-updater';

CapacitorUpdater.addListener('appReady', () => {
  // Update is applied. autoSplashscreen already hid the splash.
});

CapacitorUpdater.notifyAppReady();

이 appReady 이 이벤트는 앱 초기화와 대기 중인 업데이트 적용이 완료되면 발생합니다.

설정 keepUrlPathAfterReload 로 true instant apply 모드를 사용할 때 발생합니다. 이를 통해 업데이트로 인해 앱이 다시 로드되어도 현재 URL 경로가 유지됩니다.

instant apply 모드는 치명적인 버그 수정이나 보안 패치를 배포할 때 유용하지만, 다음과 같은 트레이드오프가 있습니다:

• 업데이트가 적용될 때 다음과 같은 경우 사용자가 짧은 깜빡임이나 로딩 상태를 경험할 수 있습니다: @capacitor/splash-screen 가 누락되었거나 autoSplashscreen 가 활성화되지 않은 경우.
• 업데이트가 앱 상태나 UI를 변경하면, 사용자가 앱을 사용하는 도중 갑작스러운 변화를 겪을 수 있습니다.
• 다음과 같은 경우 사용자의 앱 내 위치 정보가 유실되어 혼란을 줄 수 있습니다: keepUrlPathAfterReload 가 설정되지 않은 경우.
• 매끄러운 전환을 위해 상태 저장 및 복구 로직을 세심하게 처리해야 합니다.

instant apply를 활성화하는 경우, 다음 사항을 권장합니다:

• 를 사용하여 업로드하여 npx @capgo/cli@latest bundle upload --delta 다운로드가 사용자 경험을 저해하지 않도록 합니다.
• 를 설치하여 @capacitor/splash-screen 및 설정 autoSplashscreen: true 함께 launchAutoHide: false.
• 설정 keepUrlPathAfterReload 로 true 앱 내 사용자 위치를 유지하기 위해.
• 사용자의 진행 상황이 유실되지 않도록 필요에 따라 앱 상태를 저장하고 복구합니다.
• 업데이트 시 갑작스러운 화면 전환, 상태 유실, 또는 위치 변화로 인한 혼란이 없도록 앱의 업데이트 동작을 철저히 테스트하세요.

대부분의 경우 기본 업데이트 동작이 빠른 업데이트 배포와 중단 최소화 사이에서 최적의 균형을 제공합니다. 하지만 특정 요구사항이 있는 앱을 위해, Capgo는 업데이트 적용 시점과 방식을 커스텀할 수 있는 유연성을 제공합니다.

Update Behavior에서 계속하기

사용 중인 경우 업데이트 동작 live update 배포를 계획하려면, 이를 다음 항목과 연결하세요: Capgo Live Updates Capgo Live Updates의 제품 워크플로우를 위해, 개요 Overview의 구현 세부 사항을 위해, 주요 기능 Features의 구현 세부 사항은, 업데이트 유형 구현 세부 사항은 Update Types에서 확인하고, 시작하기 구현 세부 사항은 Getting Started에서 확인하세요.