업데이트 동작

설치 단계와 이 플러그인의 전체 마크다운 가이드를 포함한 설정 프롬프트를 복사하세요.

Capgo 앱에 대한 업데이트를 릴리스할 때, 사용자들이 가능한 한 빨리 업데이트를 받기를 원할 것입니다. 그러나 사용자 경험을 방해하지 않고 다운로드를 기다리거나 앱을 다시 시작하지 않도록 하기 위해 업데이트를 받지 않기를 원할 것입니다.

Capgo의 업데이트 동작은 업데이트를 빠르게 제공하고 사용자 경험을 최소화하는 균형을 맞추기 위해 설계되었습니다.

기본 업데이트 흐름

Capgo의 기본 동작은 다음과 같습니다.

Capgo 플러그인은 앱을 시작할 때 새로운 업데이트가 있는지 확인합니다.
If an update is found, it’s downloaded in the background while the user continues using the current version of the app.
Once the download completes, Capgo waits for the user to either background the app or kill it entirely.
When the user next launches the app, they’ll be running the updated version.

This flow ensures that users are always running the latest version of your app, without ever being interrupted by update prompts or forced to wait for downloads.

Why This Approach?

앱이 백그라운드에서 업데이트를 적용하거나 종료 이벤트를 사용하는 것은 사용자 경험에 몇 가지 주요 이점을 제공합니다.

사용자는 업데이트를 위한 알림이나 다운로드를 기다리며 중단되지 않습니다.
업데이트는 세션 사이에 무방비적으로 적용되므로, 앱을 시작할 때 항상 최신 버전의 경험을 제공합니다.
활발한 사용자에게 영향을 미치지 않도록 자주 업데이트를 제공할 수 있습니다.

주된 단점은 사용자가 앱을 백그라운드에 보내고 다시 앱을 시작하면 업데이트가 적용된 사이에 저장되지 않은 상태를 잃을 수 있다는 것입니다.

이 문제를 완화하기 위해 다음을 추천합니다.

앱이 다시 시작될 때 상태를 자주 저장하고 부드럽게 복원하는 것이 좋습니다.
앱 상태의 큰 부분을 수정하는 매우 자주 업데이트를 피하는 것이 좋습니다.
Sensitive 흐름을 커스터마이즈하는 경우 (아래 참조)를 고려하는 것이 좋습니다.

업데이트가 적용되는 시기를 커스터마이즈하는 방법

일부 경우, 업데이트가 적용되는 시기를 더 제어하고 싶을 수 있습니다. 예를 들어, 사용자가 진행 중인 흐름을 완료하기 전에 업데이트를 적용하거나, 서버 측 변경과 앱 업데이트를 동기화하고 싶을 수 있습니다.

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: 앱이 종료된 후에 업데이트를 적용하지 않습니다.

이러한 조건을 혼합하여 업데이트를 설치할 때 정확히 제어할 수 있습니다.

__CAPGO_KEEP_0__

중요한 업데이트 또는 상태가 매우 단순한 앱의 경우, 다운로드가 완료된 즉시 업데이트 적용을 기다리지 않고, 배경 또는 종료 이벤트를 기다리지 않고 업데이트 적용을 원할 수 있습니다. Capgo은 이 기능을 지원하기 위해 directUpdate 구성 옵션을 제공합니다.

Delta (Manifest) 업데이트 directUpdate를 사용할 때, 강력히 추천합니다. Delta (manifest) 업데이트 를 활성화하여 다운로드 시간을 최소화하고 사용자 경험을 개선하세요. Delta (manifest) 업데이트에서는 변경된 파일만 다운로드하여 전체 패키지를 다운로드하는 대신, 특히 사용자가 앱을 활성화하고 있는 동안 즉시 업데이트 적용을 할 때 중요합니다. Direct Updates의 경우, 이 점이 중요합니다:

Direct Updates의 경우, 이 점이 중요합니다:

빠른 업데이트: 다운로드가 작아 업데이트가 완료되면 로딩 화면을 보지 않도록 시간을 절약합니다
최고의 모바일 경험: 셀룰러 네트워크나 느린 연결을 사용하는 사용자는 긴 대기 시간을 겪지 않습니다
낮은 대역폭 사용: 변경된 파일만 다운로드되며, 당신과 사용자 모두에게 데이터를 절약합니다

Delta 업데이트가 directUpdate 활성화되어 있는 경우 __CAPGO_KEEP_0__이 감지합니다. 비 인터랙티브 환경에서는 Delta (매니페스트) 업데이트를 자동으로 보내고, 인터랙티브 환경에서는 업로드하기 전에 확인을 요청합니다. Delta 업데이트를 강제로 업로드하려면 capacitor.config, the CLI detects it. In non-interactive environments it sends Delta (manifest) updates automatically, and in interactive environments it prompts you to confirm before uploading. Use --no-delta Delta (매니페스트) 업데이트를 활성화하려면 업로드할 때

flag를 사용하세요: --delta Delta (manifest) 업데이트를 사용하려면

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

더 알아보기 델타 (매니페스트) 업데이트 문서.

directUpdate __CAPGO_KEEP_0__에서 설정된 파일, JavaScript에서 설정하지 않습니다. capacitor.config.ts file, not in JavaScript code. It supports three values:

false (기본값): 앱이 시작될 때 다운로드, 배경화면이 될 때 설정
'atInstall'스토어에서 앱을 설치, 업데이트 한 경우에만 직접 업데이트, 그 외에는 directUpdate = false로 동작
'onLaunch'스토어에서 앱을 설치, 업데이트 또는 앱을 종료한 경우에만 직접 업데이트, 그 외에는 directUpdate = false로 동작
'always'앱이 설치된 경우, 스토어에서 앱을 설치, 업데이트 또는 앱을 종료한 경우에만 직접 업데이트, 그 외에는 directUpdate = false로 동작
true 앱이 설치된 경우, 스토어에서 앱을 설치, 업데이트 또는 앱을 종료하거나 앱을 재개동한 경우에만 직접 업데이트, 그 외에는 directUpdate = false로 동작 'always' (deprecated): __CAPGO_KEEP_0__와 동일한 값으로 사용, 이전 버전의 호환성을 위해

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      directUpdate: 'always', // or 'atInstall' for updates only on app install/update
      autoSplashscreen: true, // NEW: Automatically handle splashscreen
      keepUrlPathAfterReload: true,
    },
    SplashScreen: {
      launchAutoHide: false, // Still required when using directUpdate
    },
  },
};

export default config;

활성화되면 __CAPGO_KEEP_0__ 업데이트가 다운로드 완료되면 즉시 업데이트를 적용합니다. 사용자가 앱을 활성화하고 있는 경우에도. directUpdate enabled, Capgo will immediately apply an update as soon as the download completes during an update check, even if the user is actively using the app. Without periodic checking enabled, this means updates will only be applied when the app starts or resumes from background.

이 기능은 native configuration이므로 JavaScript __CAPGO_KEEP_0__에서 추가 처리가 필요합니다. directUpdate is a native configuration, it requires some additional handling in your JavaScript code.

업데이트 프로세스가 완료되면 스플래시 스크린을 숨기기 위해 언제든지 전체 제어를 보장합니다.

자동 스플래시 스크린 처리 directUpdate easier to use, Capgo provides an autoSplashscreen 를 제공합니다.

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

활성화되면 autoSplashscreen 업데이트가 적용될 때 플러그인은 스플래시 스크린을 자동으로 숨깁니다.

를 활성화하면
플러그인은 업데이트가 필요하지 않으면 자동으로 스플래시 화면을 숨깁니다.
업데이트가 필요하지 않으면 스플래시 화면을 숨기지 않아야 하는 경우를 제외하고는 수동으로 appReady 이벤트를 듣거나 SplashScreen.hide()

호출할 필요가 없습니다.

수동 제어를 선호하거나 커스텀 로직이 필요하다면 autoSplashscreen 을 비활성화하고

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

CapacitorUpdater.addListener('appReady', () => {
  // Hide splash screen
  SplashScreen.hide();
});

CapacitorUpdater.notifyAppReady();

클립보드 복사 appReady The

이벤트는 앱이 초기화 및 적용 중인 업데이트를 완료한 후 발생합니다. 이 시점에서 앱의 UI를 표시할 수 있으며, 사용자는 최신 버전을 볼 수 있습니다. appReady 스플래시 화면을 표시하기 전에 keepUrlPathAfterReload 설정 옵션을 true 업데이트로 인해 앱이 다시 로드 될 때 현재 URL 경로를 유지하기 위해 사용됩니다. 사용자의 위치를 유지하고 혼란을 줄이는 데 도움이 됩니다. directUpdateIf you don’t handle the

event and set appReady 업데이트가 적용될 때 사용자가 잠시 동안陈舊한 앱 버전을 보거나 초기 경로로 돌아가거나 화면이 깜빡이는 것을 방지하기 위해 keepUrlPathAfterReload can be useful for delivering critical bug fixes or security patches, but it comes with some tradeoffs: directUpdate사용자가 업데이트가 적용될 때properly handle the splashscreen (either with

or manual directUpdate event handling)로 처리하지 않으면 화면에 짧은 깜빡임이나 로딩 상태를 보게 될 수 있습니다.

event handling autoSplashscreen event handling appReady event handling
업데이트가 앱 상태나 UI를 수정하는 경우 사용자는 세션 중간에 갑작스러운 변경을 볼 수 있습니다.
앱의 사용자의 위치가 손실될 수 있습니다. keepUrlPathAfterReload 이미지 소스가 설정되지 않은 경우 사용자는 혼란스럽게 될 수 있습니다.
앱이 부드러운 전환을 보장하기 위해 상태를 저장하고 복원하는 것을 신중하게 처리해야 합니다.

이 옵션을 활성화하는 경우, 우리는 다음을 추천합니다. directUpdate가장 간단한 설정을 위해

을 사용하거나, 만약 사용자 정의 로직이 필요하다면 autoSplashscreen: true 이벤트를 수동으로 처리하는 것을 추천합니다. appReady 를
으로 설정하여 앱의 사용자의 위치를 보존합니다. keepUrlPathAfterReload __CAPGO_KEEP_0__ true __CAPGO_KEEP_1__
사용자 진행을 잃지 않도록 앱 상태를 필요에 따라 저장하고 복원합니다.
업데이트 동작을 철저히 테스트하여 갑작스러운 전환, 잃어버린 상태, 또는 혼란스러운 위치 변경이 없는지 확인합니다.

대부분의 경우 기본 업데이트 동작이 빠르게 업데이트를 제공하고 방해를 최소화하는 최적의 균형을 제공합니다. 하지만 특정 요구를 가진 앱의 경우 Capgo가 업데이트를 언제 그리고 어떻게 적용할 수 있는 유연성을 제공합니다.