업데이트 유형

Capgo는 여러 유형의 OTA(Over-The-Air) 업데이트를 지원합니다. 이 페이지에서는 앱에 적합한 조합을 선택할 수 있도록 모든 유형을 나열하고 설명합니다.

적용 타이밍

제어 할 때 업데이트는 다운로드된 후 적용됩니다. 플러그인은 앱이 포그라운드로 전환될 때와 앱이 열려 있는 동안 반복 타이머로 업데이트를 확인합니다. periodCheckDelay 이 간격을 제어합니다(기본값 10분).

유형	설명	사용 사례
autoUpdate: atBackground	포그라운드 체크마다 확인 및 다운로드, 앱이 백그라운드로 전환될 때 적용	대부분의 앱; 사용자 방해 최소화
autoUpdate: atInstall	신규 설치 또는 네이티브 앱 스토어 업데이트 직후에만 즉시 적용; 그 외에는 다음 방식 사용 atBackground	신규 사용자는 최신 버전을 받고, 기존 사용자는 백그라운드 적용
autoUpdate: onLaunch	콜드 스타트(종료 → 포그라운드) 시에만 즉시 적용하고, 이후에는 atBackground	최신성과 세션 안정성 사이의 균형
autoUpdate: always	포그라운드 전환 시마다 확인하고 업데이트가 있으면 즉시 적용	긴급 수정 사항, 상태가 단순한 앱
autoUpdate: onlyDownload	자동으로 확인 및 다운로드하고, emit updateAvailable자동 적용은 하지 않음	자체 업데이트 프롬프트를 표시하거나 호출 시점을 직접 제어하는 앱 set()

다음에서 설정: capacitor.config.ts:

plugins: {
  CapacitorUpdater: {
    autoUpdate: 'atBackground', // default; true is still accepted
    // or: 'off' | 'atInstall' | 'onLaunch' | 'always' | 'onlyDownload'
  }
}

팁

전체 세부 사항 및 스플래시 스크린 처리에 대해서는 업데이트 동작.

지연 조건

충족해야 하는 조건 첫 번째 제출이 승인되기 업데이트가 설치됩니다. 다음을 사용하세요 setMultiDelay 조건을 결합합니다(모든 조건이 충족되어야 함).

조건	설명	예시
date	특정 날짜/시간 이후까지 대기	서버 측 릴리스와 조정
background	앱이 백그라운드로 전환된 후 최소 시간(ms) 대기	빠른 앱 전환 중 적용 방지
nativeVersion	최소 네이티브 바이너리 버전 요구	호환되지 않는 네이티브 code에서 업데이트 차단
kill	다음 앱 kill 이벤트까지 대기	완전 재시작 시에만 적용

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

await CapacitorUpdater.setMultiDelay({
  delayConditions: [
    { kind: 'date', value: '2023-06-01T00:00:00.000Z' },
    { kind: 'background', value: '60000' },
  ],
});

위험

이 kill condition은 다른 항목들과 달리 다음 background가 아니라 첫 번째 kill 이벤트 후에 트리거됩니다. 이 문제는 향후 릴리스에서 수정될 예정입니다.

버전 차단 (채널 정책)

어떤 semver 업데이트를 채널이 자동으로 전달할지 제어합니다. 다음을 통해 설정합니다. --disable-auto-update 채널에서.

전략	차단	허용	사용 사례
없음	없음	모든 대상 번들 버전	기본값; 전체 자동 업데이트
메이저	major 버전이 더 높은 경우 version_build, 예: 1.2.3 -> 2.0.0	동일 major, 예: 1.2.3 -> 1.9.0 또는 1.2.3 -> 1.2.4	기존 네이티브 code에 breaking changes가 도달하지 않도록 방지
minor는	major 또는 minor 버전이 다른 경우 version_build, 예: 1.2.3 -> 1.3.0	major와 minor가 동일한 경우, 예: 1.2.3 -> 1.2.4	업데이트를 하나의 네이티브 minor 라인 내에서 유지
patch는	major, minor, patch 번호 중 어떤 것이든 변경되는 경우, 예: 1.0.0 -> 1.0.1	suffix만 변경되고 MAJOR.MINOR.PATCH 동일하게 유지되는 경우, 예: 1.0.0-beta.1 -> 1.0.0-beta.2 또는 1.0.0+build.1 -> 1.0.0+build.2	가장 엄격한 모드: 코어 버전 변경 없음
메타데이터	누락됨 min_update_version, 또는 version_build 그 아래	대상 번들의 min_update_version 이하인 version_build	번들별 커스텀 호환성 규칙

이 체크는 네이티브 베이스라인과 대상 번들을 비교합니다. 네이티브 베이스라인은 version_build로 전송되며, 현재 설치된 다운로드 번들(로 전송)이 아닙니다. version_name.

npx @capgo/cli channel set production --disable-auto-update major

주의

patch 및 metadata 설정에 주의가 필요합니다. 자세한 내용은 CLI 명령어 및 버전 타겟팅 에서 확인하세요.

전송 방식

어떻게 bundle이 기기로 전송되는지.

유형	설명	사용 시점
전체 bundle	전체 JS 번들이 다운로드됩니다	최초 설치, 대규모 변경 또는 델타 사용 불가 시
델타	변경된 파일만 다운로드됩니다	대부분의 업데이트; 더 빠르고 대역폭 효율적

# Full bundle (default)
npx @capgo/cli bundle upload --channel production

# Delta updates
npx @capgo/cli bundle upload --channel production --delta

팁

instant apply 모드를 사용할 때 (atInstall, onLaunch, 또는 always), 델타 업데이트 를 활성화하여 다운로드 시간을 최소화하고 UX를 개선하세요.

빠른 참조

카테고리	타입
적용 시점	off, atBackground, atInstall, onLaunch, always, onlyDownload
지연 조건	date, background, nativeVersion, kill
버전 차단	none, major, minor, patch, metadata
전송 방식	풀 번들, 델타

관련 항목

• 업데이트 동작 — 적용 시점 및 지연 시간 설정
• 버전 타겟팅 — 채널 기반 버전 라우팅
• Delta 업데이트 — 변경된 파일만 다운로드
• 채널 — 채널 설정 및 우선순위

Update Types에서 계속하기

사용 중이라면 업데이트 유형 live update 배포를 계획하려면, 다음과 연결하세요 Capgo Live Update Capgo Live Updates의 제품 워크플로우를 보려면, 개요 Overview의 구현 상세를 보려면, 기능 Features의 구현 상세를 보려면, 업데이트 동작 Update Behavior의 구현 세부 사항은 다음과 같고, 시작하기 시작하기 페이지의 구현 상세 내용.