페이지 옵션 복사

Capgo live update은 앱의 버전을 자동으로 업데이트합니다. 자바스크립트 번들 즉시 대체되지만 네이티브 part of your app — the Capacitor/Cordova plugins, native dependencies, and native project configuration that are compiled into the installed binary. When a new bundle expects native code that the installed binary doesn’t have, the bundle is native-incompatible: Capgo 가 여전히 전달할 수 있지만, 여전히 이전의 네이티브 빌드가 실행 중인 기기에서 충돌하거나 비정상적으로 동작할 수 있습니다.

이 페이지는 Capgo 가 네이티브 호환성을 감지하는 방법, 사용자에게 불일치한 업데이트가 의미하는 바, 네이티브 변경 사항을 안전하게 배포하는 방법에 대해 설명합니다.

주의

Live updates는 JavaScript 번들 변경에만 제한됩니다. 네이티브 code 업데이트가 필요할 경우(플러그인 추가 또는 제거, Capacitor 업그레이드, 네이티브 프로젝트 구성 변경)에는 일반적인 앱 스토어 배포 프로세스를 통해 새로운 바이너리 빌드를 제출해야 합니다.

TLDR: OTA 또는 네이티브?

Capgo can send files from your generated web build folder. If the change only affects HTML, CSS, JavaScript, assets, or pure-JavaScript packages bundled into that output, ship it as a live update.

또는 capacitor.config.tsCapacitor 는 웹 빌드 폴더에서 파일을 전송할 수 있습니다. 변경 사항이 HTML, CSS, JavaScript, 자원, 또는 그 출력에 포함된 순수 자바스크립트 패키지에만 영향을 미치는 경우 Capacitor 로 배포하세요. npx cap sync or npx cap copy __CAPGO_KEEP_0__

변경	Capgo 실시간 업데이트로 배포할까요?	왜
HTML, CSS, 앱 자바스크립트, 이미지, 글꼴 및 다른 웹 빌드 자산	네	웹 번들에서 런타임에 로드됩니다.
자바스크립트 패키지 변경이 웹 출력에 패키징됩니다.	네	생성된 자바스크립트는 웹 번들에 포함됩니다.
capacitor.config.ts 변경	아니오	Capacitor 설정은 빌드 시간에 네이티브 앱에 읽어들어집니다.
Capacitor/Cordova 플러그인 추가, 제거, 업그레이드	아니요	설치된 네이티브 바이너리에는 매칭되는 네이티브 code이 포함되어야 합니다.
iOS 또는 Android 프로젝트 파일 변경	아니요	기존 사용자는 스토어에서 새로운 바이너리를 받을 필요가 있습니다.

클라이언트 플러그인별 스택

Capgo는 각 하이브리드 런타임에 전용 업데이터 클라이언트를 제공합니다.

플러그인	사용할 때
@capgo/capacitor-updater	Capacitor iOS/Android 앱
@capgo/cordova-updater	Cordova iOS 7+ / Android 13+ 앱
@capgo/electron-updater	Electron 데스크톱 앱

네이티브 호환성 검사에는 클라이언트 플러그인에 관계없이 적용됩니다. - 설치된 바이너리와 기록된 네이티브 의존성을 비교합니다.

네이티브 호환성의 중요성

모든 Capacitor 앱은 두 가지 층으로 배포됩니다.

• The 네이티브 바이너리 사용자가 앱 스토어 / 플레이 스토어에서 설치합니다. - 이에는 Capacitor, 네이티브 플러그인 및 네이티브 구성이 포함됩니다.
• The 자바스크립트 번들 (your web app)가 Capgo에서 Capgo을 Capgo으로 업데이트할 수 있습니다.

live update은 JavaScript layer만 교체합니다. 새로운 JavaScript가 native plugin 또는 API을 호출한다면, 설치된 바이너리 내에 컴파일되지 않은 API에 대한 호출은 런타임에 실패할 수 있습니다. 이는 앱이 충돌하거나 silent하게 기능이 깨질 수 있습니다. 간단히 말해, Capgo은 native code을 업데이트할 수 없으므로, old native build를 실행하는 기기는 new native code을 기반으로 빌드된 배포판을 안전하게 실행할 수 없습니다.

Capgo이 호환성을 검사하는 방법

배포판을 업로드하거나 수동으로 검사할 때, Capgo은 자연적인 패키지 local 프로젝트 내의 (your Capacitor/Cordova 플러그인 및 버전)와 배포판에 현재 라이브 채널에서 기록된 native packages:

• 이 두 가지가 일치하면, 변경은 JavaScript-only이며 위험 없이 __CAPGO_KEEP_0__으로 업데이트할 수 있습니다..
• 플러그인이 추가되거나 제거되거나 버전이 변경되면, 배포판은 native-incompatible — 사용자가 새로운 네이티브 바이너리를 설치한 후에만 적용됩니다.

CLI에서 확인하세요.

bunx @capgo/cli@latest bundle compatibility com.example.app --channel production

CLI은 채널에서 실시간으로 업데이트된 버전과 사용자 컴퓨터에 설치된 버전을 비교하여 각 네이티브 패키지의 상태를 출력합니다.

Package              Local    Remote   Status
@capacitor/core      6.1.2    6.1.2    ✅
@capacitor/share     6.0.0    6.0.0    ✅
@capacitor/camera    6.1.0    —        ❌  not in the live bundle

팁

추가 --text __CAPGO_KEEP_0__에서 스와핑할 수 있는 이모티콘을 교환하세요. OK/FAIL (CI 로그에서 유용합니다), 그리고 --package-json / --node-modules 오른쪽 경로를 찾기 위해 monorepo 내의 경로를 지정합니다.

CI에서 기계가 읽을 수 있는 판결을 받으세요.

pipeline의 경우, bundle releaseType check를 단일 단어로 축소합니다:

bunx @capgo/cli@latest bundle releaseType com.example.app --channel production
# → OTA      safe to ship as a live update
# → native   needs a new app-store build

release pipeline에 이게 게이트를 걸어주세요: ship a live update when it prints OTA그리고 native build를 트리거할 때 it prints native.

사용자에게 불일치 업데이트가 의미하는 바

주의

기본적으로 불일치 감지 기능이 not native-incompatible bundle을 업로드하고 해당 채널의 활성 빌드를 설정하면 Capgo 장치에 전달합니다. (이 기능을 강제 게이트로 변경하려면 --fail-on-incompatible — see 아래에 설명되어 있습니다.) below.)

를 실행하는 장치에서 missing native __CAPGO_KEEP_0__, the missing native code can cause crashes or broken features — even though the update downloaded and applied “successfully.” This is why a live update can be live and delivered yet still break the app for existing users, and why Capgo can warn you when an incompatible bundle goes live.

Capgo의 자동 롤백 JavaScript 오류를 발생시킨 이전 단계에서 잡을 수 있습니다. notifyAppReady() code은 호환성이 맞지 않으면 나중에 충돌하거나 원래대로 충돌할 수 있으므로 배포할 수 있는 네이티브 code 대신에 사용할 수는 있지만, 호환성이 맞지 않은 code은 배포할 수 있는 네이티브 code의 대안이 아니다.

Section titled “호환성이 있는 네이티브 변경 사항을 안전하게 배포하는 방법”

Section titled “새로운 네이티브 빌드 배포 (실제 해결책)”

When a bundle needs new native code, build and submit a new binary to the App Store / Play Store (or rebuild with Capgo Cloud Build). Once users update the binary, the bundle’s native dependencies line up and the live update runs correctly.

라이브 업데이트가 이미 활성화된 불일치 패키지에 대한 롤백

__CAPGO_KEEP_1__ 롤백.

불일치 배포를 방지

두 가지 보완적인 보호 장치가 있습니다. 이 두 가지 보호 장치 모두 실제로 사용자 정의 패키지를 검사합니다.

CI에서 업로드를 실패시킬 수 있습니다 — --fail-on-incompatible

__CAPGO_KEEP_0__ bundle upload 단계에 플래그를 추가하세요. 만약 번들의 사용자 정의 패키지가 채널의 현재 활성화된 버전과 일치하지 않으면 업로드는 0이 아닌 종료 코드로 실패하고 아무것도 배포되지 않습니다. 업로드가 실패하면 PIPELINE이 사용자 정의 패키지를 설치해야 하는 OTA 업데이트를 조용히 배포하는 것을 방지합니다. 터미널 창

bunx @capgo/cli@latest bundle upload --channel production --fail-on-incompatible

Compatible uploads — and cases where the check can’t run (a new channel, or no remote metadata) — pass through unchanged. In an interactive terminal it offers the Capgo Builder native-build flow instead; declining fails. (Can’t be combined with --ignore-metadata-check.)

Tip

When you intentionally channel의 live native 패키지와 다른 버전의 번들(새 플러그인, Capacitor 업그레이드 등)이 필요합니다. --fail-on-incompatible Live Update를 위한 기본 업로드에 대해. 일상적인 OTA CI에서 플래그를 유지하세요. 전체 채널 워크플로우: 자연적 업데이트와 OTA 채널 워크플로.

네이티브 버전에 의해 게이트 전달 metadata + --auto-min-update-version

When you do ship the native build and the bundle together, put the channel on the "Live Update" metadata 라이브 업데이트와 업로드 --auto-min-update-version. Capgo은 업로드마다 호환성 체크를 수행하고, 필요한 경우 code을 업데이트하여 기기에 호환되지 않는 기존 Capgo을 배포하지 않도록 합니다:

# one-time: switch the channel to the metadata strategy
bunx @capgo/cli@latest channel set production com.example.app --disable-auto-update metadata

# from then on, Capgo sets the floor automatically on every upload
bunx @capgo/cli@latest bundle upload --channel production --auto-min-update-version

주의

버전 번호 규칙은 --disable-auto-update major 은 아니며 a substitute — they only block version jumps and never inspect native code, so a native change shipped in a minor or patch release still goes out. Use --fail-on-incompatible 또는 --auto-min-update-version, 원본 패키지를 확인하세요.

See 버전 목표 설정 전체 목표 설정 옵션을 위해

관련

자연 + OTA 워크플로

개발/운영 채널, 유지할 때 --fail-on-incompatible, 그리고 의도적인 네이티브 베이스 라인 배포 방법

자동 OTA 또는 네이티브

Wire bundle releaseType GitHub 액션 또는 GitLab으로 live update vs Capgo 빌드에 CI가 선택

버전 목표 설정

만족하는 버전을 사용하여 채널, semver 규칙 및 메타데이터 전략을 사용하여 호환 가능한 패키지를 전달

롤백

비호환 버전이 출시된 경우 마지막 호환 빌드로 채널을 되돌려야 합니다.

업데이트 유형

적용 시간, 지연 조건 및 버전 차단이 어떻게 함께 작동하는지 설명합니다.

CLI: 버전

버전 호환성, 릴리스 타입 및 업로드 옵션에 대한 참조입니다.

자연 호환성으로부터 계속 진행하세요

버전 타겟팅 컨텍스트: Capgo 솔루션 마케팅 페이지. 역할: 섹션 또는 페이지 제목. 보이는 곳: 페이지 솔루션/버전-타겟팅.astro. 메시지 키 `solutions_version_targeting_title` (솔루션 버전 타겟팅 제목). | 컨텍스트: Capgo 솔루션 마케팅 페이지. 역할: 짧은 UI 레이블 또는 네비게이션 아이템. 보이는 곳: 사이트 헤더, 컴포넌트 SolutionsMegaMenu.astro, 페이지 솔루션/버전-타겟팅.astro. 메시지 키 `solutions_version_targeting` (솔루션 버전 타겟팅). 자연 호환성 버전 타겟팅과 연결하여 라이브 업데이트 안전하게 유지하세요. 버전별 패키지 라우팅을 위해 롤백 비호환 패키지가 배포될 때 복구하기 위해 업데이트 유형 채널 버전 차단을 이해하고, 그리고 Capgo CLI 호환성 및 릴리스 타입 명령에 대한 패키지 참조 페이지 편집