자연적인 호환성

__CAPGO_KEEP_0__

Capgo 라이브 업데이트 는 앱의 Note: I've kept the placeholder Capgo as it is, as per the instructions. 자바스크립트 번들 즉시 적용되지만, 변경은 불가능합니다. 자연적인 업데이트 Capacitor 플러그인, Cordova 플러그인, 네이티브 의존성 및 네이티브 프로젝트 구성이 설치된 바이너리에 컴파일된 앱의 일부입니다. 새로운 번들의 경우 설치된 바이너리에서 code이 없을 때 번들은 native-incompatibleCapgo는 여전히 최신 업데이트를 전달할 수 있지만, 여전히 이전 네이티브 빌드를 실행하는 기기에서 충돌하거나 이상한 동작을 하게 될 수 있습니다.

이 페이지는 Capgo이 네이티브 호환성을 감지하는 방법, 사용자에게 호환되지 않는 업데이트란 무엇인지, 그리고 네이티브 변경을 안전하게 배포하는 방법에 대해 설명합니다.

OTA 또는 네이티브 업데이트?

Capgo에서 생성된 웹 빌드 폴더에서 파일을 전송할 수 있습니다. 변경 사항이 HTML, CSS, JavaScript, 자원 또는 그에 포함된 JavaScript 패키지에만 영향을 미치면, OTA로 배포하세요.

네이티브 앱 릴리즈를 사용하세요. 변경 사항이 플러그인 구성, 네이티브 플러그인 또는 의존성, __CAPGO_KEEP_1__ 자체 또는 iOS/Android 프로젝트 파일을 업데이트해야 하는 경우. capacitor.config.ts, plugin configuration stored in Capacitor config, native plugins or dependencies, Capacitor itself, or iOS/Android project files. A practical check: if the change must update the native project through npx cap sync __CAPGO_KEEP_0__ npx cap copy __CAPGO_KEEP_1__

__CAPGO_KEEP_0__	Ship with Capgo OTA?	__CAPGO_KEEP_0__ OTA로 배포할까요?
왜	HTML, CSS, 앱 JavaScript, 이미지, 폰트 및 기타 웹 빌드 자원	네
자바스크립트 패키지 변경이 웹 출력에 패키징됩니다.	네	생성된 자바스크립트는 웹 번들에 포함됩니다.
`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, native 플러그인 및 native 설정이 포함되어 있습니다.
The 자바스크립트 번들 (Capgo에서 업데이트할 수 있는) 웹 앱

실시간 업데이트에서는 자바스크립트层만 교체합니다. 새로운 자바스크립트가 설치된 바이너리 내에 컴파일되지 않은 native 플러그인이나 API을 호출하면 런타임에 호출이 실패할 수 있습니다. 이는 앱이 충돌하거나 silent하게 기능이 깨질 수 있습니다. 간단히 말해 Capgo은 native code를 업데이트할 수 없으므로, 기존 바이너리 설치된 기기에서 새로운 native code를 컴파일한 번들을 실행하는 것은 안전하지 않습니다.

How Capgo detects compatibility

bundle을 업로드하거나 수동으로 확인할 때 Capgo은 native 패키지 local 프로젝트 내의 native 패키지 (Capacitor/Cordova 플러그인 및 버전)와 bundle에 기록된 native 패키지를 비교합니다. 현재 채널에서 실시간으로 방송 중입니다.:

만약 일치하면, 변경 사항은 자바스크립트만으로 이루어져 있으며 위성으로 공급할 수 있는 안전한 변경 사항입니다..
플러그인이 추가되거나 제거되거나 버전이 변경되면, 번들은 자연어 호환 불가능합니다. — 사용자가 새로운 네이티브 바이너리를 설치할 때까지 변경 사항이 적용되지 않습니다.

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

기계가 읽을 수 있는 판결 (CI) - 섹션

판단을 단일 단어로 축소합니다: bundle releaseType 터미널 창

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

이 릴리스 PIPELINE 에 게이트 하세요: ship a live update when it prints OTA그리고 trigger a native build when it prints native.

사용자에게 불일치 업데이트의 의미

아직도 기존 바이너리, 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이 누락된 경우에는 Capgo이 충돌하거나 기능이 깨질 수 있습니다. — 업데이트 다운로드 및 적용이 "성공적으로" 완료되었음에도 불구하고. 이 때문에 live update가 live이고 배포되었음에도 불구하고 기존 사용자에게 앱이 깨질 수 있으며, __CAPGO_KEEP_1__은 불일치하는 번들을 live할 때 경고할 수 있습니다. __CAPGO_KEEP_0__의 자동 롤백 notifyAppReady() code이 실행되기 전에 발생한 자바스크립트 오류를 잡아낼 수 있지만, code이 호환되지 않은 경우에는 code이 충돌하거나 natively 충돌할 수 있으므로, code이 호환되지 않은 경우에는 자동 롤백이 이를 감지하지 못할 수 있습니다.

안전하게 네이티브 변경 사항을 배포하는 방법

새로운 네이티브 빌드를 배포하세요 (실제 해결책)

bundle이 새로운 네이티브 code이 필요할 때, App Store / Play Store로 새로운 바이너리를 제출하거나 Capgo Cloud Build를 사용하여 다시 빌드하세요. 사용자가 바이너리를 업데이트한 후, bundle의 네이티브 의존성들이 정렬되고, live update가 올바르게 작동합니다.

이미 배포 중인 불일치 버전을 되돌리기

채널에 이미 불일치 버전이 활성화되어 있는 경우, 네이티브 빌드가 출시될 때까지 채널을 마지막으로 호환 가능한 빌드로 되돌려서 배포를 중지하세요. 자세한 내용은 Rollbacks.

불일치 배포를 방지하기

네이티브 패키지를 검사하는 두 가지 보완적인 장치:

CI에서 업로드를 실패시킬 것 — --fail-on-incompatible

flag를 추가하여 bundle upload step. 만약 bundle의 네이티브 패키지가 채널의 현재 배포 버전과 일치하지 않으면 업로드 __CAPGO_KEEP_0__ — 그래서 pipeline은 사용자가 네이티브 빌드를 설치할 때까지 OTA 업데이트가 작동하지 않도록 silentyly 업로드하는 것을 막습니다.

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

Compatible 업로드 — 그리고 check가 실행되지 않는 경우 (새 채널, 또는 remote metadata가 없을 때) — 그대로 통과합니다. 인터랙티브 터미널에서 Capgo Builder native-build flow 대신 제공합니다; 거부하면 실패합니다. (Native + OTA Channel Workflow와 함께 사용할 수 없습니다.) --ignore-metadata-check.)

자연 버전으로 게이트 전달 — metadata + --auto-min-update-version

당신이 할 때 자연 빌드와 번들을 함께 보내면 채널을 전략에 두고 metadata 와 함께 업로드하세요. --auto-min-update-version Capgo 업로드마다 호환성 체크를 하고, 번들이 새로운 자연 code이 필요할 때 업데이트를 높여서 아직 매칭된 자연 빌드를 설치하지 않은 기기들이 업데이트를 받지 않도록 합니다:

# 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

or 버전 업데이트를 위한 대안을 사용하세요. See

관련 --fail-on-incompatibleNative + OTA Workflow

Auto OTA or Native

Wire bundle releaseType GitHub 액션 또는 GitLab으로 CI가 실시간 업데이트 vs Capgo 빌드 를 선택하도록 하세요.

버전 목표

만족하는 버전 패키지만 채널, semver 규칙 및 메타데이터 전략을 사용하여 전달합니다.

롤백

채널을 불일치 패키지로 실시간 업데이트가 나간 후 마지막으로 호환 가능한 빌드로 되돌리세요.

업데이트 유형

CLI: bundle

__CAPGO_KEEP_0__: 패키지

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

Native Compatibility을 사용 중이라면 Native Compatibility live updates를 안전하게 유지하기 위해 Native Compatibility을 연결하세요 버전 대상 설정 native 버전에 따라 배포 패키지를 라우팅하세요 롤백 불일치한 배포 패키지가 출시될 때 복구하세요 업데이트 유형 채널 버전 차단을 이해하고 Capgo CLI bundle reference __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ 배포 패키지 참조