Native Compatibility

Capgo 앱의 실시간 업데이트에서 앱의 버전을 업데이트하는 데 사용됩니다. 자바스크립트 번들 즉시 적용되지만, 변경할 수는 없습니다. 자연적인 업데이트 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 native-incompatibleCapgo는 이전 버전의 네이티브 빌드가 실행 중인 기기에서 충돌하거나 비정상적으로 동작할 수 있지만 여전히 Capgo를 통해 배포할 수 있습니다.

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

노트

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

실제로 OTA 또는 네이티브를 선택해야 하는지에 대한 간단한 요약입니다.

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

네이티브 앱 릴리스를 사용하세요. 변경 사항이 플러그인 구성이 저장된 __CAPGO_KEEP_0__ 구성, 네이티브 플러그인 또는 의존성, __CAPGO_KEEP_1__ 자체 또는 iOS/Android 프로젝트 파일을 업데이트합니다. 실제 체크: 변경 사항이 네이티브 프로젝트를 업데이트해야 하는지 여부를 확인하세요. 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 context npx cap copy HTML 텍스트 조각은 더 긴 Capgo UI 문자열 (부모 키 `alternatives_cta_questions`)에서 가져온 것입니다. 페이지/영역: Capacitor 라이브 업데이트 대안 비교 페이지. 역할: 장기 마케팅 또는 법적 문단. 보존: Capgo 제품/브랜드 및 개발자 용어를 정확히. 메시지 키 `alternatives_cta_questions` (대안 CTA 질문). | HTML 텍스트 조각은 더 긴 Capgo UI 문자열 (부모 키 `appflow_cta_questions`)에서 가져온 것입니다. 페이지/영역: Appflow 비교/이동 마케팅 복사본. 역할: 장기 마케팅 또는 법적 문단. 보존: Capgo 제품/브랜드 및 개발자 용어를 정확히. 메시지 키 `appflow_cta_questions` (Appflow CTA 질문). | HTML 텍스트 조각은 더 긴 Capgo UI 문자열 (부모 키 `capwesome_cta_questions`)에서 가져온 것입니다. 페이지/영역: Capawesome 비교 페이지. 역할: 장기 마케팅 또는 법적 문단. 보존: Capgo 제품/브랜드 및 개발자 용어를 정확히. 메시지 키 `capwesome_cta_questions` (Capwesome CTA 질문). | HTML 텍스트 조각은 더 긴 Capgo UI 문자열 (부모 키 `consulting_faq_subtitle`)에서 가져온 것입니다. 페이지/영역: 컨설팅 서비스 페이지. 역할: 섹션 서브 타이틀 또는 태그 라인. 보존: Capgo 제품/브랜드 및 개발자 용어를 정확히. 메시지 키 `consulting_faq_subtitle` (컨설팅 FAQ 서브 타이틀). | 페이지/영역: Appflow 비교/이동 마케팅 복사본. 역할: 짧은 UI 레이블 또는 네비게이션 아이템. 보존: Capgo 제품/브랜드 및 개발자 용어를 정확히. 메시지 키 `appflow_plugins_or` (Appflow 플러그인 또는).

설치된 장치가 사용할 수 있도록 하기 전에, 네이티브로 다루세요.	Ship with Capgo OTA?	__CAPGO_KEEP_0__ OTA로 배포하세요?
왜	HTML, CSS, 앱 JavaScript, 이미지, 폰트 및 기타 웹 빌드 자산	네
__CAPGO_KEEP_0__ 자바스크립트 패키지 변경이 웹 출력에 패키징됩니다.	네	생성된 자바스크립트는 웹 번들에 포함됩니다.
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 native binary users install from the App Store / Play Store. It contains Capacitor, your native plugins, and native configuration.
• The JavaScript bundle (your web app) that Capgo can update over the air.

A live update swaps only the JavaScript layer. If that new JavaScript calls a native plugin or API that isn’t compiled into the installed binary, the call fails at runtime — which can crash the app or silently break a feature. Put simply: Capgo cannot update native code, so a device running the old native build can’t safely run a bundle that was built against new native code.

How Capgo detects compatibility

When you upload a bundle — or run the check manually — Capgo compares the native packages in your local project (your Capacitor/Cordova plugins and their versions) against the native packages recorded for the bundle 현재 채널에서 실시간으로 방송 중입니다.:

• 만약 일치한다면, 변경 사항은 자바스크립트만으로 이루어져 있으며 위성으로부터 안전하게 전송할 수 있습니다..
• 플러그인이 추가되거나 제거되거나 버전이 변경되면, 번들은 자연어 호환성에 위배됩니다. — 사용자가 새로운 네이티브 바이너리를 설치할 때까지 변경 사항은 효과가 없습니다.

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 CI 로그에서 유용한 emoji를 교체하고 OK/FAIL 모노레포에서 올바른 경로를 가리키기 위해 --package-json / --node-modules 기계가 읽을 수 있는 판결을 받기 (CI)

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

이 릴리스 PIPELINE 에 게이트 하세요: ship a live update when it prints OTA그리고 trigger a native build when it prints native.

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

주의

기본적으로 불일치 감지하는 것은 아니요 업로드를 차단하지 않음 — native-incompatible bundle 을 업로드하고 채널의 활성 빌드를 설정하면 Capgo will deliver it 장치에 전달합니다. --fail-on-incompatible 그것을 강제 게이트로 바꾸려면 — see 불일치하는 배포를 방지하세요 아래와 같이.

아직도 기존 바이너리기존 바이너리 code이 누락된 경우에는 충돌이나 기능이 깨지는 문제가 발생할 수 있습니다. — 업데이트 다운로드 및 적용이 "성공적으로" 완료되었음에도 불구하고. 이는 라이브 업데이트가 라이브로 배포될 수 있지만 기존 사용자에게 앱이 깨지는 이유입니다. 그리고 Capgo은 불일치하는 번들을 라이브로 배포할 때 경고할 수 있습니다.

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이 새로운 네이티브 code이 필요할 때, App Store / Play Store로 새로운 바이너리를 제출하거나 Capgo Cloud Build를 재구축하여 새로운 바이너리를 제출하세요. 사용자가 바이너리를 업데이트한 후, bundle의 네이티브 의존성들이 일치하고 live update가 올바르게 작동합니다.

이미 배포 중인 불일치 버전을 되돌리기

채널에 이미 불일치 버전이 활성화되어 있는 경우, 네이티브 빌드가 출시될 때까지 채널을 마지막으로 호환 가능한 빌드로 되돌려서 배포를 중지하세요. 자세한 내용은 Rollbacks.

불일치 배포를 방지하기

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

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

flag를 추가하세요. bundle upload step. 만약 bundle의 네이티브 패키지가 채널의 현재 배포 버전과 일치하지 않으면 업로드는 실패합니다. __CAPGO_KEEP_0__ — 그래서 pipeline은 silent로 OTA 업데이트를 배포하지 못하게 막습니다. 사용자가 네이티브 빌드를 설치할 때까지 업데이트가 적용되지 않기 때문입니다.

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

Compatible 업로드 — 그리고 체크를 실행할 수 없는 경우 (새 채널, 또는 remote 메타데이터가 없을 때) — 그대로 통과합니다. 인터랙티브 터미널에서 Capgo Builder 네이티브 빌드 흐름을 제공합니다; 거부하면 실패합니다. (다른 것과 결합할 수 없습니다) --ignore-metadata-check.)

팁

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

__CAPGO_KEEP_0__ metadata + --auto-min-update-version

업로드 시 업로드 업로드 metadata __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 __CAPGO_KEEP_0__ not 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 or --auto-min-update-versionVersion Targeting

for the full set of targeting options. Related Native + OTA Workflow

Dev/production channels, when to keep

not

a substitute — they only block version jumps and never inspect native __CAPGO_KEEP_0__, so a native change shipped in a minor or patch release still goes out. Use --fail-on-incompatibleor

자동 OTA 또는 네이티브

Wire bundle releaseType GitHub 액션 또는 GitLab으로 CI가 라이브 업데이트 vs Capgo 빌드를 선택하도록 하세요.

버전 대상

페이지/영역: Capgo 솔루션 마케팅 페이지. 역할: 섹션 또는 페이지 제목. 보이는 곳: page solutions/version-targeting.astro. 메시지 키 `solutions_version_targeting_title` (솔루션 버전 대상 제목). | 페이지/영역: Capgo 솔루션 마케팅 페이지. 역할: 짧은 UI 레이블 또는 네비게이션 아이템. 보이는 곳: page solutions/version-targeting.astro. 메시지 키 `solutions_version_targeting` (솔루션 버전 대상).

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

롤백

채널을 마지막으로 호환 가능한 빌드로 되돌리세요. 만약 호환 불가능한 번들이 라이브로 나왔을 때.

업데이트 유형

CLI: bundle

__CAPGO_KEEP_0__: 번들

번들 호환성, 릴리스 타입, 및 업로드 옵션에 대한 참조입니다.

만약 당신이 사용 중이라면 자연적 호환성 live updates를 안전하게 유지하기 위해 버전 대상 설정 페이지/영역: Capgo 솔루션 마케팅 페이지. 역할: 섹션 또는 페이지 제목. 보이는 곳: page solutions/version-targeting.astro. 메시지 키 `solutions_version_targeting_title` (솔루션 버전 대상 제목). | 페이지/영역: Capgo 솔루션 마케팅 페이지. 역할: 짧은 UI 레이블 또는 네비게이션 아이템. 보이는 곳: page solutions/version-targeting.astro. 메시지 키 `solutions_version_targeting` (솔루션 버전 대상). 자연적 버전에 따라 배달할 수 있도록 롤백 불일치한 배달이 나면 복구할 수 있도록 업데이트 유형 Capgo CLI bundle reference __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ 배달 참조