__CAPGO_KEEP_0__ 호환성

Capgo 실시간 업데이트 즉시, 그러나 그것은 설치된 바이너리에 컴파일 된 Cordova 플러그인, 네이티브 의존성 및 네이티브 프로젝트 구성이 포함된 앱의 원래 부분을 변경할 수 없습니다. 네이티브 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 네이티브-상관: Capgo can still deliver it, but it may crash or misbehave on devices that are still running the older native build.

This page explains how Capgo detects native compatibility, what an incompatible update means for your users, and how to ship native changes safely.

주의

Live updates are limited to JavaScript bundle changes. If you need to update native code — adding or removing a plugin, upgrading Capacitor, or changing native project configuration — you’ll need to submit a new binary build through the usual app-store distribution process.

라이브 업데이트는 JavaScript 배포본 변경에만 제한됩니다. 네이티브 __CAPGO_KEEP_0__을 업데이트해야 하는 경우(플러그인을 추가하거나 제거하거나, __CAPGO_KEEP_1__을 업그레이드하거나, 네이티브 프로젝트 구성 변경)에는 일반적인 앱 스토어 배포 프로세스를 통해 새로운 바이너리 빌드를 제출해야 합니다.

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.

__CAPGO_KEEP_0__ 변경이 native 앱을 업데이트해야 할 때 native 앱 릴리즈를 사용하세요. capacitor.config.tsCapacitor config, native 플러그인 또는 의존성, Capacitor 자체, 또는 iOS/Android 프로젝트 파일에 저장된 플러그인 구성이 있습니다. 실제적인 확인: 변경이 native 프로젝트를 업데이트해야 하는지 여부를 확인하세요. 만약 변경이 native 프로젝트를 업데이트해야 한다면 native로 처리하세요. npx cap sync __CAPGO_KEEP_0__ npx cap copy __CAPGO_KEEP_0__

__CAPGO_KEEP_0__	Capgo	__CAPGO_KEEP_0__
__CAPGO_KEEP_0__	__CAPGO_KEEP_0__	__CAPGO_KEEP_0__
__CAPGO_KEEP_0__	__CAPGO_KEEP_0__	The generated JavaScript is part of the web bundle.
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 데스크톱 앱

클라이언트 플러그인 여하를 구분없이 native 호환성 검사가 적용됩니다. — 이 검사는 배포본의 기록된 네이티브 의존성을 설치된 바이너리와 비교합니다.

네이티브 호환성의 중요성

Every Capacitor app ships in two layers:

• Every __CAPGO_KEEP_0__ 앱은 두 가지 층으로 배포됩니다. The_native 바이너리 사용자는 앱 스토어 / 플레이 스토어에서 설치합니다. 이에는 Capacitor, 네이티브 플러그인, 및 네이티브 설정이 포함됩니다.
• The JavaScript 번들 (웹 앱) Capgo이 오버 더 에어로 업데이트할 수 있습니다.

실시간 업데이트에서 JavaScript层만 교체합니다. 새로운 JavaScript가 네이티브 플러그인 또는 API을 호출하고 설치된 바이너리에 컴파일되지 않은 경우 런타임에서 호출이 실패하고 앱이 충돌하거나默默히 기능이 깨질 수 있습니다. 간단히 말하면: Capgo은 네이티브 code을 업데이트할 수 없으므로, 기존 네이티브 빌드를 실행하는 기기는 새로운 네이티브 code에 대해 빌드된 번들을 안전하게 실행할 수 없습니다.

Capgo이 호환성을 감지하는 방법

번들을 업로드하거나 수동으로 확인할 때 Capgo은 네이티브 패키지 프로젝트 내의 로컬 패키지( Capacitor/Cordova 플러그인 및 버전)와 번들이 현재 채널에 기록된 네이티브 패키지를 비교합니다. 현재 채널에:

• 호환성이 일치하면 변경 사항은 JavaScript-only입니다. __CAPGO_KEEP_0__.
• __CAPGO_KEEP_0__ __CAPGO_KEEP_0__ — __CAPGO_KEEP_0__

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

__CAPGO_KEEP_0__

추가 --text 로 이모티콘을 교환하기 위해 OK/FAIL (CI 로그에서 유용합니다), 그리고 --package-json / --node-modules 모노레포에서 올바른 경로를 가리키기 위해

기계가 읽을 수 있는 판결을 얻으세요 (CI)

pipeline에 대해 bundle releaseType pipeline을 단일 단어로 축소합니다:

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에 게이트하세요: 실시간 업데이트를 배포할 때 출력하면 OTAnative 빌드를 트리거하세요: 출력하면 native.

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

주의

기본적으로 불일치 감지 기능은 업로드를 차단하지 않습니다. — 만약 native-incompatible bundle을 업로드하고 해당 채널의 활성 빌드를 설정하면 __CAPGO_KEEP_0__ 은 block the upload — if you upload a native-incompatible bundle and set it as a channel’s active build, Capgo see 불일치 배포를 차단하는 방법 --fail-on-incompatible below. Prevent incompatible deliveries below.)

On __CAPGO_KEEP_0__가 아직 지원되는 기기에서 실행 중인 경우, __CAPGO_KEEP_0__이 누락된 경우 충돌이나 기능이 깨지는 문제가 발생할 수 있습니다. — 업데이트 다운로드 및 적용이 “성공적으로” 완료되었음에도 불구하고. 이로 인해 live update가 live update가 될 수 있지만 기존 사용자에게 앱이 깨지는 문제가 발생할 수 있으며, __CAPGO_KEEP_1__은 불일치한 번들을 live update할 때 경고할 수 있습니다. __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의 자동 롤백 애플리케이션의 충돌을 방지하기 위해 notifyAppReady() runs, but it isn’t a substitute for shipping compatible native code — a mismatch that crashes later, or crashes natively, can slip past it.

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

bundle가 새로운 네이티브 __CAPGO_KEEP_0__이 필요할 때, App Store / Play Store에 새로운 바이너리 빌드를 제출하거나 __CAPGO_KEEP_1__ Cloud Build를 사용하여 다시 빌드하세요. 사용자가 바이너리를 업데이트한 후, 번들의 네이티브 의존성을 일치시키고 live update가 올바르게 실행됩니다.

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_0__ 만약에 현재 활성화된 채널에 불일치하는 번들이 이미 존재한다면, 채널을 마지막으로 호환 가능한 빌드로 되돌려서 번들이 배포되지 않도록 하세요. 자세히 보기

__CAPGO_KEEP_0__ 만약에 현재 활성화된 채널에 불일치하는 번들이 이미 존재한다면, 채널을 마지막으로 호환 가능한 빌드로 되돌려서 번들이 배포되지 않도록 하세요. 자세히 보기 __CAPGO_KEEP_1__.

__CAPGO_KEEP_2__

__CAPGO_KEEP_0__ 불일치하는 배포를 방지하는 두 가지 보안 장치가 있습니다. 두 장치 모두 실제로 네이티브 패키지를 검사합니다.

__CAPGO_KEEP_3__ CI에서 업로드를 실패시켜 — --fail-on-incompatible

__CAPGO_KEEP_4__에 플래그를 추가하세요. 만약에 번들의 네이티브 패키지가 채널의 현재 활성화된 버전과 일치하지 않는다면, 업로드는 0이 아닌 값을 반환하고 배포되지 않습니다 — 따라서 pipeline은 조용히 OTA 업데이트를 배포하는 것을 막아줍니다. 업데이트가 적용될 수 있는 사용자가 네이티브 빌드를 설치할 때까지. bundle upload __CAPGO_KEEP_5__ — 따라서 pipeline은 조용히 OTA 업데이트를 배포하는 것을 막아줍니다. 업데이트가 적용될 수 있는 사용자가 네이티브 빌드를 설치할 때까지. __CAPGO_KEEP_6__ — 따라서 pipeline은 조용히 OTA 업데이트를 배포하는 것을 막아줍니다. 업데이트가 적용될 수 있는 사용자가 네이티브 빌드를 설치할 때까지. __CAPGO_KEEP_7__

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

호환 가능한 업로드 — 및 확인이 실행되지 않는 경우 (새 채널 또는 원격 메타데이터가 없는 경우) — 변경되지 않습니다. 인터랙티브 터미널에서 Capgo 빌더 네이티브 빌드 플로우를 제공합니다; 거부는 실패합니다. ( combination 할 수 없습니다. --ignore-metadata-check.)

네이티브 버전으로 게이트 전달 — metadata + --auto-min-update-version

당신이 네이티브 빌드와 번들을 함께 배송할 때 채널을 전략과 업로드 metadata . __CAPGO_KEEP_0__ 업로드마다 호환성 확인을 실행하고, 번들이 새로운 네이티브 __CAPGO_KEEP_1__이 필요할 때 업데이트를 높여서 네이티브 빌드와 일치하지 않는 장치가 업데이트를 받지 않도록 합니다: --auto-min-update-version. Capgo runs the compatibility check on every upload and, when a bundle needs new native code, raises the update floor so devices that haven’t installed the matching native build don’t receive it:

# 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 처럼 아니라 버전 번호를 점프하는 것을 막는 것만으로는 충분하지 않습니다. native code를 검사하지 않기 때문에, minor 또는 patch 릴리스에 native 변경 사항이 포함되어도 배포됩니다. 사용하는 --fail-on-incompatible 또는 --auto-min-update-version,

를 사용하여 native 패키지를 확인합니다. 자세한 내용은 버전 대상 설정

을 참조하세요.

Auto OTA 또는 Native

Wire bundle releaseType GitHub 액션 또는 GitLab으로 CI가 실시간 업데이트 vs Capgo 빌드.

버전 대상 설정

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

롤백

비호환 버전 패키지가 실시간으로 배포된 경우 마지막 호환 빌드로 채널을 되돌립니다.

업데이트 유형

타이밍, 지연 조건 및 버전 차단이 함께 작동하는 방법에 대한 설명입니다.

CLI: 패키지

호환성, releaseType, 업로드 옵션에 대한 참조입니다.

네이티브 호환성에서 계속합니다

자연스러운 호환성을 사용 중이라면 자연스러운 호환성 실시간 업데이트 보안을 위해 연결하세요. 버전 대상 설정 자연스러운 버전에 따라 번들을 라우팅하세요. 롤백 불일치한 번들이 배포될 때 복구하세요. 업데이트 유형 채널 버전 차단을 이해하고, Capgo CLI 호환성 및 releaseType 명령에 대한 번들 참조