__CAPGO_KEEP_0__

Capgo 라이브 업데이트는 앱의 JavaScript 번들을 즉시 대체하지만 앱의 자연스러운 부분을 변경할 수 없습니다 — 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 Install: Capgo은 여전히 전달 할 수 있지만, 여전히 이전의 네이티브 빌드가 실행 중인 장치에서 충돌하거나 비정상적으로 동작할 수 있습니다.

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

주의

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

TLDR: OTA 또는 네이티브?

Capgo은 생성된 웹 빌드 폴더에서 파일을 전송할 수 있습니다. 변경 사항이 HTML, CSS, JavaScript, 자원, 또는 그 출력에 포함된 순수 자바 스크립트 패키지에만 영향을 미치는 경우 실시간 업데이트로 배포하세요.

네이티브 앱 릴리즈를 사용할 때는 __CAPGO_KEEP_0__ config에 저장된 플러그인 구성, 네이티브 플러그인 또는 의존성, __CAPGO_KEEP_1__ 자체, 또는 iOS/Android 프로젝트 파일을 업데이트하는 경우입니다. 실제 체크: 변경 사항이 네이티브 프로젝트를 업데이트해야 하는 경우(예를 들어, __CAPGO_KEEP_1__을 업그레이드해야 하는 경우)에는 네이티브로 처리하세요. 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 before npx cap copy installed

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

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

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

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

__CAPGO_KEEP_0__의 네이티브 의존성과 설치된 바이너리의 비교에 따라 클라이언트 플러그인에 관계없이 네이티브 호환성 검사 적용

네이티브 호환성의 중요성

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

• 사용자는 앱 스토어 / 플레이 스토어에서 __CAPGO_KEEP_0__를 설치합니다. __CAPGO_KEEP_0__는 네이티브 플러그인 및 네이티브 설정을 포함합니다. Capacitor는 웹 앱 (JavaScript 번들)입니다.
• __CAPGO_KEEP_0__는 오버 더 에어로 웹 앱을 업데이트 할 수 있습니다. 네이티브 바이너리 (your web app) that Capgo can update over the air.

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

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

번들을 업로드하거나 수동으로 확인할 때 Capgo는 local 프로젝트 내의 native 패키지 Capacitor/Cordova 플러그인 및 버전과 현재 채널에 기록된 native 패키지를 비교합니다. native 패키지:

• 호환성이 맞으면 JavaScript-only의 변경은 위공기에서 안전하게 전송할 수 있습니다..
• 플러그인이 추가되거나 제거되거나 버전이 변경된 경우 번들은 native-incompatible — 사용자가 새로운 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

팁

추가 --text Emoji를 교환하기 위해 사용할 수 있습니다.(CI 로그에서 유용합니다.) 및 OK/FAIL 오른쪽 경로를 참조하기 위해 모노레포에서 사용할 수 있습니다. --package-json / --node-modules __CAPGO_KEEP_0__

CI를 위한 기계-readable 판결을 받으세요.

pipeline에 대해 bundle releaseType CI를 위한 판결을 단일 단어로 압축합니다.

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을 제어하세요: OTAlive update를 배포할 때 출력이 나올 때 native.

native build를 트리거할 때 출력이 나올 때

주의하세요!

기본적으로 불일치 감지를 블록하지 않습니다 — 만약 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 기존 native binary를 아직 실행 중인 기기에서 missing native __CAPGO_KEEP_0__ --fail-on-incompatible 은 충돌이나 기능이 깨지는 것을 유발할 수 있습니다 — 업데이트가 다운로드되고 적용된 것처럼 보이지만. 이로 인해 live update가 live이고 배포되었지만 기존 사용자에게 앱이 깨지는 것을 방지하기 위해 __CAPGO_KEEP_1__은 불일치한 배포가 live되었을 때 경고를 제공합니다. __CAPGO_KEEP_0__’s __CAPGO_KEEP_1__’s

__CAPGO_KEEP_0__ __CAPGO_KEEP_1__, 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 자동 롤백 JavaScript 에서 발생한 오류를 잡을 수 있습니다. notifyAppReady() 실행되지만, 호환성이 없는 네이티브 code — 호환성이 없는 네이티브 code 이 나중에 충돌하거나 네이티브로 충돌할 수 있으므로, 이를 피하기 어렵습니다.

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

새로운 네이티브 빌드 (실제 해결책)를 배포합니다.

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

이미 활성화된 채널에 호환되지 않는 배포본이 이미 존재하는 경우, 호환되는 마지막 빌드로 채널을 되돌려서 호환되지 않는 배포본을 제공하지 않도록 하세요.

호환되지 않는 배포본이 이미 활성화된 채널에 존재하는 경우, 네이티브 빌드가 출시될 때까지 호환되지 않는 배포본을 제공하지 않도록 하세요. 롤백.

불일치 배포를 방지하세요

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

CI에서 업로드를 실패하세요 — --fail-on-incompatible

Add the flag to your bundle upload 단계. 만약 번들의 네이티브 패키지가 채널의 현재-live 버전과 일치하지 않으면 업로드는 0이 아닌 종료 코드로 실패하고 아무것도 배포되지 않습니다. — 그래서 pipeline은 사용자가 네이티브 빌드를 설치하기 전까지 효과가 나타나지 않는 OTA 업데이트를 조용히 배포하는 것을 막아줍니다. 터미널 창

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

호환되는 업로드 — 그리고 검사가 실행되지 않는 경우 (새 채널 또는 원격 메타데이터가 없을 때) —는 그대로 통과합니다. 인터랙티브 터미널에서 Capgo 빌더 네이티브 빌드 흐름을 제안합니다; 거부하면 실패합니다. (네이티브 버전으로 게이트를 열 수 없습니다.) --ignore-metadata-check.)

네이티브 버전으로 게이트를 열세요 metadata + --auto-min-update-version

When you do, native build and bundle are shipped together, put the channel on the strategy and upload with. __CAPGO_KEEP_0__ native build compatibility check is performed on every upload, and when a bundle needs new native __CAPGO_KEEP_1__, the update floor is raised so devices that haven’t installed the matching native build don’t receive it. Terminal 창 metadata 복사 --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

아니

__CAPGO_KEEP_0__는 업로드마다 native build의 호환성 체크를 수행하고, bundle이 새로운 native __CAPGO_KEEP_1__를 필요로 할 때, 호환되지 않은 native build를 설치하지 않은 기기들이 업데이트를 받지 못하도록 업데이트 바닥을 높입니다. --disable-auto-update major __CAPGO_KEEP_0__는 업로드마다 native build의 호환성 체크를 수행하고, bundle이 새로운 native __CAPGO_KEEP_1__를 필요로 할 때, 호환되지 않은 native build를 설치하지 않은 기기들이 업데이트를 받지 못하도록 업데이트 바닥을 높입니다. __CAPGO_KEEP_0__는 업로드마다 native build의 호환성 체크를 수행하고, bundle이 새로운 native __CAPGO_KEEP_1__를 필요로 할 때, 호환되지 않은 native build를 설치하지 않은 기기들이 업데이트를 받지 못하도록 업데이트 바닥을 높입니다. 대체 — 그들은 버전 업데이트만 차단하고 원시 code를 검사하지 않기 때문에, 소수 또는 패치 릴리스에 원시 변경이 포함되어도 여전히 배포된다. 사용 --fail-on-incompatible 또는 --auto-min-update-version,

이러한 원시 패키지를 확인하는 See 버전 목표

전체 목표 옵션을 보려면

Section titled “Related”

버전 목표

만족하는 버블만 전달하는 채널, semver 규칙 및 메타데이터 전략을 사용하여.

롤백

업데이트 유형

타이밍, 지연 조건 및 버전 차단이 함께 작동하는 방법

CLI: 번들

번들 호환성, releaseType 및 업로드 옵션에 대한 참조

네이티브 호환성에서 계속

네이티브 호환성을 사용 중이라면 네이티브 호환성을 사용하여 실시간 업데이트 보안을 유지하고 버전 대상 설정 버전을 기반으로 번들을 라우팅하기 위해 롤백 버전 대상 설정 불일치한 배포를 받았을 때 복원하기 위해 업데이트 유형 채널 버전 차단을 이해하고, Capgo CLI 배포 참조 호환성 및 releaseType 명령에 대한