네이티브 호환성

Capgo 라이브 업데이트로 Capgo 앱의 JavaScript 번들 즉시 대체되지만 __CAPGO_KEEP_0__/Cordova 플러그인, 네이티브 의존성 및 네이티브 프로젝트 구성이 컴파일된 설치 바이너리에 포함되어 있기 때문에 네이티브 부분을 변경할 수 없습니다. 새로운 번들이 설치된 바이너리에서 __CAPGO_KEEP_1__을 갖지 않는 경우 번들은 네이티브-상관 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_KEEP_0__: Capgo can still deliver it, but it may crash or misbehave on devices that are still running the older native build.

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

주의

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

네이티브 호환성의 중요성

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

• The 네이티브 바이너리 사용자는 앱 스토어 / 플레이 스토어에서 설치합니다. 이 바이너리는 Capacitor, 네이티브 플러그인, 그리고 네이티브 구성이 포함되어 있습니다.
• The 자바스크립트 번들 (Capgo)이 업데이트할 수 있는 웹 앱입니다.

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

Capgo이 호환성 검사를 어떻게 하는지

배포할 패키지를 업로드하거나 수동으로 검사할 때, Capgo은 native 패키지 프로젝트 내의 로컬 패키지 (Capacitor/Cordova 플러그인 및 버전)와 현재 채널에 기록된 native 패키지:

• 일치하면 JavaScript-only의 변경이 안전하게 OTA로 배포할 수 있습니다. 플러그인이 추가되거나 제거되거나 버전이 변경된 경우, 패키지는.
• native-incompatible __CAPGO_KEEP_0__이 호환성 검사를 어떻게 하는지 — 사용자가 새로운 네이티브 바이너리를 설치한 후에만 적용됩니다.

Check from the CLI

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

The 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 Emoji를 바꾸기 위해 사용할 수 있습니다. OK/FAIL (CI 로그에서 유용합니다), --package-json / --node-modules __CAPGO_KEEP_0__

__CAPGO_KEEP_0__

파이프라인의 경우 bundle releaseType __CAPGO_KEEP_0__

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

이 출력이 나올 때 live 업데이트를 배포하고, native 빌드를 트리거하세요. OTA사용자에게 불일치 업데이트가 의미하는 바 native.

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

주의

기본적으로 불일치 감지를 하지 않습니다 업로드하는 native-incompatible 배포본을 채널의 활성 빌드로 설정하고 Capgo 그 채널의 기기에 전달합니다. (이것을 강제 게이트로 바꾸려면 — --fail-on-incompatible see 불일치 배포를 방지하는 방법 아래에 있습니다.)

기존의 native __CAPGO_KEEP_0__가 누락된 기기에서 오래된 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’s __CAPGO_KEEP_0__의 자동 롤백 __CAPGO_KEEP_0__이 던진 자바스크립트 오류를 catch할 수 있지만, __CAPGO_KEEP_0__이 호환되지 않은 경우에는 __CAPGO_KEEP_0__이 충돌하는 경우를 대비하지 못한다. notifyAppReady() code 호환성은 배포 후에만 확인할 수 있으므로, 호환되지 않은 code이 배포된 후에 충돌하는 경우를 대비하지 못한다.

안정적인 네이티브 변경 배포 방법

실제 해결책인 새로운 네이티브 빌드를 배포하라

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

호환되지 않은 배포가 이미 활성화된 채널이 있는 경우, 호환되지 않은 채널을 마지막으로 호환된 빌드로 되돌려서, 네이티브 빌드가 출시될 때까지 배포를 중지한다.

참고 롤백.

불일치 배포를 방지

두 개의 보완적인 보안 장치가 있습니다. 두 장치 모두 실제로 네이티브 패키지를 검사합니다.

CI에서 업로드를 실패하십시오 — --fail-on-incompatible

플래그를 bundle upload 단계에 추가하십시오. 만약 번들의 네이티브 패키지가 채널의 현재-live 버전과 일치하지 않으면 업로드는 0이 아닌 종료 코드로 실패하고 아무것도 배포되지 않습니다. 터미널 창 클립보드에 복사

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.)

원본 버전으로 패키지를 전달하세요 — metadata + --auto-min-update-version

당신이 할 때 자연스러운 버전 빌드와 번들을 함께 배포할 때, 채널을 전략에 추가하고 __CAPGO_KEEP_0__ 업로드하세요. 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

버전 번호 규칙들처럼

are --disable-auto-update major are 대체품이 아니며 — 버전 업그레이드만 차단하고 원시 __CAPGO_KEEP_0__를 검사하지 않기 때문에, 소수점 또는 패치 릴리즈에 포함된 원시 변경 사항은 여전히 배포됩니다. 사용 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 버전 목표 버전 목표

버전 목표

버전 목표

버전 목표

롤백

__CAPGO_KEEP_0__: 배포

업데이트 타입

__CAPGO_KEEP_0__: 배포 시간 및 버전 차단

CLI: 배포

__CAPGO_KEEP_0__: 배포 호환성, 배포 유형, 업로드 옵션

__CAPGO_KEEP_0__: 네이티브 호환성

__CAPGO_KEEP_0__: 네이티브 호환성을 사용 중이라면 __CAPGO_KEEP_0__: 네이티브 호환성을 사용하여 실시간 업데이트 보안을 유지하고 __CAPGO_KEEP_0__: 버전 목표 설정을 사용하여 네이티브 버전에 따라 배포를 라우팅하세요. __CAPGO_KEEP_0__: 버전 목표 설정을 사용하여 네이티브 버전에 따라 배포를 라우팅하세요. __CAPGO_KEEP_0__: 네이티브 호환성을 사용 중이라면 롤백 불일치 배포 시 복구를 위해, 업데이트 유형 채널 버전 차단을 이해하고, Capgo CLI 호환성 및 릴리스 타입 명령에 대한 배포 참조. 페이지 편집