Native 호환성

이 플러그인의 설치 단계와 전체 마크다운 가이드가 포함된 설정 프롬프트를 복사하세요.

Capgo live update는 앱의 JavaScript 번들 을 즉시 교체하지만, 변경할 수 없는 것은 네이티브 영역입니다 — 즉, 설치된 바이너리에 컴파일된 Capacitor/Cordova plugin, native dependency, native project configuration 등입니다. 새 bundle이 설치된 바이너리에 없는 native code를 요구하면, 해당 bundle은 네이티브 비호환: Capgo를 통해 여전히 전달할 수 있지만, 이전 native build를 실행 중인 기기에서는 크래시되거나 오작동할 수 있습니다.

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

요약: OTA인가, Native인가?

Capgo는 생성된 웹 빌드 폴더에서 파일을 전송할 수 있습니다. 변경 사항이 HTML, CSS, JavaScript, 에셋 또는 해당 출력물에 포함된 순수 JavaScript 패키지에만 영향을 미친다면, live update로 배포하세요.

변경 사항이 다음을 업데이트할 때는 네이티브 앱 릴리스를 사용하세요: capacitor.config.ts, Capacitor config에 저장된 플러그인 구성, 네이티브 플러그인 또는 의존성, Capacitor 자체, 또는 iOS/Android 프로젝트 파일. 실용적인 확인 방법: 변경 사항이 다음을 통해 네이티브 프로젝트를 업데이트해야 한다면 npx cap sync 또는 npx cap copy 설치된 기기에서 사용할 수 있게 되기 전까지는 네이티브로 취급하세요.

변경 사항	Capgo OTA와 함께 배포하시겠습니까?	이유
HTML, CSS, 앱 JavaScript, 이미지, 폰트 및 기타 웹 빌드 에셋	지원	런타임에 웹 번들에서 로드됩니다.
웹 결과물에 번들되는 순수 JavaScript 패키지 변경 사항	지원	생성된 JavaScript는 웹 번들의 일부입니다.
`capacitor.config.ts` 변경 사항	아니요	Capacitor 설정은 빌드 시점에 네이티브 앱으로 읽어옵니다.
Capacitor/Cordova 플러그인 추가, 제거 또는 업그레이드	아니요	설치된 네이티브 바이너리에 일치하는 네이티브 code가 포함되어 있어야 합니다.
iOS 또는 Android 프로젝트 파일 변경	아니요	기존 사용자는 스토어에서 새 바이너리를 받아야 합니다.

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

Capgo는 각 하이브리드 런타임용 전용 updater 클라이언트를 제공합니다:

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

네이티브 호환성 검사는 클라이언트 플러그인과 관계없이 적용됩니다. 번들에 기록된 네이티브 의존성을 설치된 바이너리와 비교합니다.

Native 호환성이 중요한 이유

모든 Capacitor 앱은 두 개의 레이어로 구성됩니다:

이 네이티브 바이너리 사용자가 App Store / Play Store에서 설치합니다. Capacitor, 네이티브 플러그인, 네이티브 설정이 포함되어 있습니다.
이 JavaScript 번들 Capgo가 OTA로 업데이트할 수 있는 (웹 앱)입니다.

live update는 JavaScript 레이어만 교체합니다. 만약 새로운 JavaScript가 설치된 바이너리에 컴파일되지 않은 네이티브 플러그인이나 API을 호출하면, 런타임에 호출이 실패하여 앱이 크래시되거나 기능이 조용히 작동하지 않을 수 있습니다. 간단히 말해, Capgo는 네이티브 code를 업데이트할 수 없습니다. 따라서 이전 Native Build를 실행 중인 기기에서는 새로운 네이티브 code를 기준으로 빌드된 번들을 안전하게 실행할 수 없습니다.

Capgo의 호환성 감지 방식

번들을 upload하거나 수동으로 체크를 실행하면, Capgo는 다음을 비교합니다. 네이티브 패키지 로컬 프로젝트의 ( Capacitor/Cordova 플러그인 및 버전)과 번들에 기록된 네이티브 패키지를 비교합니다. 현재 채널에 배포된:

두 정보가 일치하면 변경 사항은 JavaScript 전용이며, OTA로 배포해도 안전합니다..
플러그인이 추가, 삭제 또는 버전이 변경된 경우, 해당 번들은 네이티브 비호환 — 해당 변경 사항은 사용자가 새로운 Native Build를 설치해야만 적용됩니다.

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

이 결과를 기준으로 릴리스 파이프라인을 게이트하세요: 출력되면 live update를 배포하고, OTA출력되면 Native Build를 트리거합니다. native.

호환되지 않는 업데이트가 사용자에게 미치는 영향

아직 이전 버전의 네이티브 바이너리를 실행 중인 기기에서는업데이트가 “성공적으로” 다운로드되고 적용되었더라도 누락된 네이티브 code 때문에 앱이 충돌하거나 기능이 깨질 수 있습니다. 이것이 live update이(가) 라이브 상태로 배포되어도 기존 사용자에게 앱 장애를 일으킬 수 있는 이유이며, 호환되지 않는 번들이 라이브될 때 Capgo이(가) 경고해 주는 이유이기도 합니다.

Capgo의 자동 롤백 발생하기 전의 JavaScript 에러를 포착할 수는 있지만, notifyAppReady() 호환되는 Native code를 배포하는 것을 대신할 수는 없습니다. 호환되지 않아 나중에 앱이 종료되거나 Native 레벨에서 크래시가 발생하는 상황은 감지하지 못할 수 있습니다.

Native 변경 사항을 안전하게 배포하는 방법

새 Native Build 배포 (근본적인 해결책)

Bundle에 새로운 Native code가 필요한 경우, App Store / Play Store에 새 바이너리를 빌드하여 제출하세요 (또는 Capgo Cloud Build로 재빌드). 사용자가 바이너리를 업데이트하면 Bundle의 Native 의존성이 일치하게 되어 live update가 정상적으로 실행됩니다.

호환되지 않는 번들이 이미 배포된 경우 롤백하기

채널에 호환되지 않는 Bundle이 이미 활성화되어 있다면, Native Build가 출시될 때까지 해당 Bundle 배포를 중단할 수 있도록 채널을 마지막 호환 빌드로 되돌리세요. 자세한 내용은 롤백.

호환되지 않는 배포 방지하기

네이티브 패키지를 검사하는 두 가지 상호 보완적인 가드 장치가 있습니다:

CI에서 upload 실패 처리 — --fail-on-incompatible

다음 항목에 플래그를 추가하세요: bundle upload 단계. 번들의 네이티브 패키지가 채널의 현재 라이브 버전과 일치하지 않으면, upload가 0이 아닌 종료 코드로 실패하며 아무것도 배포되지 않습니다. — 즉, 사용자가 Native Build를 설치하기 전까지는 적용될 수 없는 OTA 업데이트를 실수로 배포하는 것을 파이프라인 단계에서 차단합니다:

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

호환되는 upload 및 검사를 실행할 수 없는 경우(새 채널 또는 원격 메타데이터 없음)는 그대로 통과합니다. 대화형 터미널에서는 대신 Capgo Builder의 native-build 흐름을 제안하며, 거절 시 실패합니다. (다음과 함께 사용할 수 없음: --ignore-metadata-check.)

네이티브 버전별 배포 제어 — metadata + --auto-min-update-version

사용자가 반드시 네이티브 빌드와 번들을 함께 배포하고, 채널을 metadata strategy and upload with --auto-min-update-version. Capgo는 모든 업로드 시 호환성 검사를 수행합니다. 번들에 새로운 네이티브 code이 필요한 경우 업데이트 floor를 높여, 일치하는 Native Build를 설치하지 않은 기기에는 업데이트가 전달되지 않도록 합니다.

# 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

자세한 내용은 버전 타겟팅 전체 타겟팅 옵션을 확인하려면.

Native + OTA 워크플로우

Dev/production 채널, 유지 시점, --fail-on-incompatible의도적인 Native Build 배포 방법.

자동 OTA 또는 Native

연동 bundle releaseType 하여 GitHub Actions 또는 GitLab과 연결하면 CI가 live update 대신 Capgo Build를 선택합니다.

버전 타겟팅

채널, semver 규칙, 메타데이터 전략을 사용하여 호환 가능한 번들만 배포하세요.

롤백

호환되지 않는 번들이 배포된 경우, 채널을 마지막 호환 가능한 빌드로 되돌립니다.

업데이트 유형

타이밍, 지연 조건 및 버전 차단 기능이 함께 작동하는 방식입니다.

CLI: 번들

bundle 호환성, releaseType 및 upload 옵션에 대한 참조입니다.

Native Compatibility에서 계속하기

사용 중이라면 Native 호환성 Live Update를 안전하게 유지하려면 다음을 연결하세요. 버전 타겟팅 네이티브 버전별로 번들을 라우팅하려면, 롤백 호환되지 않는 번들이 배포됐을 때 복구하려면, 업데이트 유형 채널 버전 차단 방식과 Capgo CLI 번들 레퍼런스를 이해하려면, compatibility 및 releaseType 명령어에 대한 내용을 확인하세요.