네이티브 호환성

앱의 Capgo live update를 대체합니다. 자바스크립트 번들 즉시 적용되지만 변경할 수는 없습니다 네이티브 불일치 : Capacitor는 여전히 네이티브 code를 제공할 수 있지만 더 오래된 네이티브 빌드가 실행 중인 장치에서 충돌하거나 비정상적으로 동작할 수 있습니다. native-incompatible: Capgo는 이전 네이티브 빌드가 실행 중인 기기에서 충돌하거나 비정상적으로 동작할 수 있지만 여전히 Capgo를 제공할 수 있습니다.

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

Note

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.

Section titled “TLDR: OTA or native?”

Capgo는 웹 빌드 폴더에서 파일을 전송할 수 있습니다. 변경 사항이 HTML, CSS, JavaScript, 자산 또는 웹 출력에 포함된 순수 자바 스크립트 패키지에만 영향을 주면 live update로 배포하세요.

변경 사항이 네이티브 앱 릴리즈를 업데이트하는 경우 사용하세요. capacitor.config.ts변경 사항이 플러그인 구성이 저장된 Capacitor config, 네이티브 플러그인 또는 의존성, Capacitor 자체 또는 iOS/Android 프로젝트 파일을 업데이트하는 경우 네이티브 앱 릴리즈를 사용하세요. npx cap sync or npx cap copy 네이티브 앱 릴리즈를 사용하세요.

Change	Capgo OTA로 배포할까요?	Why
왜	Yes	네
네이티브 앱 릴리즈로 처리하세요.	네	웹 번들에 포함된 자바스크립트입니다.
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을 설치합니다. 이에는 Capacitor의 원생 플러그인 및 원생 설정이 포함됩니다.
• The __CAPGO_KEEP_0__ 자바스크립트 번들 (Capgo의 웹 앱) 이 Capgo에서 오버 더 에어로 업데이트할 수 있습니다.

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

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

Capgo이 업로드한 번들 또는 수동으로 확인할 때 Capgo은 Capgo의 __CAPGO_KEEP_0__ 패키지 Capacitor 프로젝트의 로컬 패키지 (Capacitor/Cordova 플러그인 및 버전)와 Capacitor의 현재 채널에서 기록된 Capacitor 패키지를 비교합니다. __CAPGO_KEEP_0__ 패키지:

• JavaScript-only 변경이면, 위성으로 안전하게 전송할 수 있습니다..
• 플러그인이 추가, 제거, 또는 버전이 변경된 경우, 네이티브 불일치 — 사용자가 새로운 네이티브 바이너리를 설치한 후에만 적용됩니다.

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

Tip

추가 --text Live Update OK/FAIL Live Update --package-json / --node-modules Live Update

Live Update

Live Update bundle releaseType Live Update

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 Update: release pipeline을 이_gate 하기 위해 ship a live update when it prints OTALive Update native.

Live Update

Live Update

Live Update Live Update 업로드를 차단하세요 — native-incompatible bundle을 업로드하고 채널의 활성 빌드로 설정하면 Capgo Live Update Live Update --fail-on-incompatible Live Update Live Update 아래와 같이.

기존에 설치된 기기에서 여전히 구 버전의 네이티브 바이너리 를 실행 중인 경우, 다운로드 및 적용이 성공적으로 완료되었음에도 불구하고 code의 누락이 앱이 충돌하거나 기능이 깨지는 문제를 일으킬 수 있습니다. 이로 인해 live update가 실시간으로 전송되고도 기존 사용자가 앱이 깨지는 문제가 발생할 수 있으며, Capgo가 불합리한 패키지가 실시간으로 전송될 때 경고를 표시할 수 있습니다.

Capgo의 자동 롤백 은 자바스크립트 에러가 발생하기 전에 notifyAppReady() 실행되기 전에 잡을 수 있지만, 네이티브 code의 불일치로 인한 충돌이 나중에 발생하거나 네이티브로 충돌하는 문제는 이를 피할 수 없습니다.

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

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

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

이미 배포 중인 불일치 배포가 있는 경우 되돌리기

이미 배포 중인 불일치 배포가 있는 채널의 경우, 마지막으로 호환 가능한 빌드를 되돌려서 배포를 중단하고 네이티브 빌드가 출시될 때까지 배포를 중지하세요. 자세히 보기 되돌리기.

불일치 배포를 방지하기

네이티브 패키지를 검사하는 두 가지 보안 장치가 있습니다.

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

__CAPGO_KEEP_1__에 플래그를 추가하세요. 배포의 네이티브 패키지가 채널의 현재 배포 버전과 일치하지 않으면 업로드는 0이 아닌 값을 반환하고 배포되지 않습니다. bundle upload 불일치 배포를 방지하기 불일치 배포를 방지하기 — 그래서 pipeline은 사용자가 네이티브 빌드를 설치할 때까지 작동하지 않는 OTA 업데이트에 대한 침묵된 배포를 막습니다:

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

상관 없는 업로드 — 그리고 체크가 실행되지 않는 경우 (새 채널 또는 remote 메타데이터가 없을 때) — 변경되지 않습니다. 인터랙티브 터미널에서 Capgo Builder 네이티브 빌드 흐름을 제공합니다; 거부는 실패합니다. (새 채널과 함께 결합할 수 없습니다) --ignore-metadata-check.)

팁

당신이 의도적으로 channel의 live native 패키지와 다른 bundle이 필요합니다. (새 플러그인, Capacitor 업그레이드 등) --fail-on-incompatible bundle이 채널의 네이티브 라이브 패키지와 다를 때 (새 플러그인, __CAPGO_KEEP_0__ 업그레이드 등), omit 일상적인 OTA CI에서 플래그를 유지하세요. 전체 채널 워크플로우:.

네이티브 + OTA 채널 워크플로우: 네이티브 버전에 의해 게이트로 배달합니다 — metadata + --auto-min-update-version

When you do native build과 bundle을 함께 배포하고, 채널을 설정합니다. 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

Caution

Live Update 버전 번호 규칙과 같이 --disable-auto-update major are not 대체 — 그들은 버전 업데이트만 차단하고 원시 code를 검사하지 않기 때문에, 소수 또는 패치 릴리스에 포함된 원시 변경 사항은 여전히 배포된다. 사용 --fail-on-incompatible 또는 --auto-min-update-version또는

See See 버전 목표

Related

관련

원시 + OTA 워크플로 --fail-on-incompatible개발/운영 채널, 유지할 때

자동 OTA 또는 원시

Wire bundle releaseType into GitHub 액션 또는 GitLab에서 CI가 live update 대신 Capgo 빌드를 선택합니다.

버전 목표

일관된 버전을만들기 위해 채널, semver 규칙, 메타데이터 전략을 사용하세요.

롤백

채널을 마지막으로 호환 가능한 빌드로 되돌리세요.

업데이트 유형

타이밍, 지연 조건, 버전 차단이 어떻게 함께 작동하는지 설명합니다.

CLI

배포 옵션, 릴리스 타입, 버전 호환성에 대한 참조입니다.

자연 호환성에서 계속하세요

사용 중인 경우 자연적 호환성 실시간 업데이트 안전을 유지하기 위해 Native Compatibility를 사용하여 버전 대상 설정 버전 대상 자연적 버전을 기준으로 번들 라우팅 롤백 불일치한 번들이 배포될 때 복구 업데이트 유형 채널 버전 차단을 이해하고 Capgo CLI 호환성 및 릴리스 타입 명령에 대한 번들 참조 호환성 및 릴리스 타입 명령에 대한 번들 참조