금요일 오후 체크아웃 오류를 발견했습니다. 수정은 이미 Capacitor 웹层에 있습니다. 그러나 앱 스토어 리뷰 창이 3일 동안 닫히지 않습니다. 안드로이드 사용자는 새로운 패키지를 sooner 받을 수 있지만, 자바스크립트 전용 수정을 강제로 모든 고객에게 재설치하는 것은 여전히 비효율적입니다.
OTA 업데이트를 배우는 이유는 실용적입니다. OTA 업데이트를 통해 설치된 바이너리에게 서명된 웹 번들을 전달하고, 배경에서 다운로드하고, 다음 런칭 시 적용할 수 있습니다. 그러나 네이티브 변경은 여전히 스토어 프로세스에 따라 진행됩니다. 업로드하는 파일 자체가 문제가 아니라, 라이브 플릿에서 버전 타겟팅, 서명, 롤아웃 제어, 관찰성, 복구를 동기화하는 것이 어려운 부분입니다.
목차
- CapacitorJS 팀에게 OTA가 중요한 이유
- 설치하기 전에 Capgo 업데이터를 설치하세요
- 첫 번째 OTA 패키지를 안전하게 배송하는 방법
- 채널, 롤아웃, CI/CD 자동화
- 테스트 전략 및 자동 롤백
- 서명, 보안 및 OTA가 변경할 수 없는 것
- 각 릴리스 전에 작업 목록
CapacitorJS 팀에게 OTA가 중요한 이유
Capacitor 앱은 일반적으로 두 개의 릴리스 표면을 포함합니다. 네이티브 바이너리는 플랫폼 셸, 권한, 플러그인, 아이콘, 특권, 및 스토어 검토된 기능을 포함합니다. 웹层는 자바스크립트, CSS, HTML, 라우팅, 복사본, 및 자산을 포함합니다. OTA 업데이트는 두 번째 표면을 대상으로 하므로 팀은 네이티브 셸을 재빌드하지 않고도 플랫폼과 스토어 정책 경계 내에서 변경을 수정할 수 있습니다. Capgo OTA 지침.

OTA 업데이트의 운영 이점은 속도만큼 더 많습니다. 설치된 바이너리는 동기화되지 않습니다. 일부 고객은 이전 네이티브 빌드를 실행하고, 다른 고객은 최근 스토어 버전을 사용하며, 각 바이너리는 웹 번들을 통해 다른 네이티브 API를 사용할 수 있습니다. 지원되지 않는 네이티브 API에 컴파일된 번들은 자바스크립트 diff가 유효하더라도 실패할 수 있습니다. 따라서 OTA는 호환성 시스템이 아닌 릴리스 엔지니어링을 피하는 단축 경로가 아닙니다.
업데이터를 업데이트 PIPELINE으로 다루세요.
생산 환경은 명확한 순서가 필요합니다.
- 네이티브 브리지 설치: 업데이터 패키지를 추가하고 Capacitor을 동기화하여 iOS와 Android가 알 수 있도록 하세요.
- 번들을 서명: 서명 자료를 저장소 외부에 유지하고, 검증을 클라이언트 경로에 포함하세요.
- 채널을 지정: 스테이징, 베타, 프로덕션, 또는 고객별 그룹을 의도적으로 라우팅하세요.
- 자동 배포: CI가 테스트 통과 후에만 빌드, 서명, 업로드, 프로모션을 자동화하세요.
- 사용률 관찰: 채널과 바이너리별로 다운로드, 설치, 부팅, 충돌, 건강 신호를 추적하세요.
- 빠른 롤백: 서버 측에서 알려진 좋은 바이너리를 복원하고 클라이언트 측에서 복구 보호를 유지하세요.
Capgo은 이 워크플로우 중 하나입니다. Capacitor 업데이터와 클라우드 서비스는 서명된 웹 바이너리를 대상 채널에 공개하고 다음 런칭 시 적용하고 버전 및 장치 수준 배포 정보를 노출합니다. 사용 가능성과 릴리즈 내구성을 평가하는 팀은 Capgo 애플리케이션의 앱 사용 가능성을 검토할 수 있습니다. app availability for Capacitor applications.
원래 바이너리를 식별할 수 없다면, 그 바이너리를 프로덕션으로 승격하지 마세요. production으로 배포하는 것을 피하세요.
OTA succeeds when it reduces unnecessary store releases without hiding the boundary between web code and native code. The question isn’t whether your team can push a bundle. It’s whether you can explain who received it, why they were eligible, what happened after launch, and how you’ll restore service when the bundle misbehaves.
Prerequisites 및 Capgo Updater 설치
터미널을 열기 전에 프로젝트와 릴리스 계정의 준비가 완료되었는지 확인하세요. Capacitor 5 또는 6 애플리케이션, Node 18 이상, Apple Developer 및 Google Play Console 계정, 그리고 Capacitor 클라우드 계정과 Capacitor 키가 필요합니다. @capacitor/cli Capgo 5 또는 6 애플리케이션, Node 18 이상, Apple Developer 및 Google Play Console 계정, 그리고 Capgo 클라우드 계정과 Capgo 키가 필요합니다. appId and API key.
__CAPGO_KEEP_0__ 패키지와 네이티브 의존성을 추가합니다.
npm install @capgo/capacitor-updater
npx cap sync
npx @capgo/cli init
npm install 자바스크립트 패키지를 추가하고 네이티브 의존성을 추가합니다. npx cap sync __CAPGO_KEEP_0__를 업데이트합니다.
__CAPGO_KEEP_0__를 업데이트합니다. capacitor.config.ts __CAPGO_KEEP_0__를 업데이트합니다.
const config: CapacitorConfig = {
appId: 'com.example.app',
appName: 'Example',
version: '1.0.0',
autoUpdate: true,
updateUrl: '',
capgo: {
channel: 'staging'
}
}
CLI를 업데이트합니다. appId __CAPGO_KEEP_0__를 업데이트합니다. version __CAPGO_KEEP_0__를 업데이트합니다. autoUpdate __CAPGO_KEEP_0__를 업데이트합니다. updateUrl must point to the service your binary trusts, and the capgo 업데이트 블록은 초기 채널을 식별해야 합니다.
업데이트 전 확인하세요
Run diagnostic command before opening Xcode or Android Studio:
npx @capgo/cli doctor
CLI이 사용 가능하고 프로젝트 설정이 읽을 수 있으며 업데이터 패키지가 감지되고, 필요한 애플리케이션 식별자가 존재하며, 인증이 구성된 계정에 도달할 수 있는지 확인하는 것이 깨끗한 결과입니다. 또한, 네이티브 동기화가 누락되지 않았는지, 앱 식별자가 존재하는지, 업데이터 설정이 유효한지 확인해야 합니다.

iOS 기기와 안드로이드 기기에 첫 번째 네이티브 빌드를 설치하고 네트워크 접근이 가능한 상태로 실행한 후 종료하고 다시 시작한 후 업데이터가 정상적인 시작 경로를 영향받지 않고 체크할 수 있는지 확인하세요. Capacitor 업데이터 설치 프로세스 프로젝트 설정을 기대하는 플러그인 설정과 비교할 때 유용합니다.
OTA 업데이트로 첫 번째 패키지를 안전하게 배포하세요
첫 번째 번들에 대한 테스트로 다루고, 기능 출시로 다루지 말고. artifact를 준비하기 전에 서명 키를 생성하거나 회전하세요.
npx @capgo/cli key create
개인 키를 비밀 관리 도구에 넣으십시오. 그것을 커밋하지 마십시오, 프로젝트 아카이브에 저장하지 마십시오, 또는 CI 출력에서 노출하지 마십시오. 네이티브 신뢰 경로는 공개 검증 자료가 필요합니다. 개인 키에 접근할 수 있는 것은 서명 작업만입니다.
자바스크립트 측 버전을 package.json 또는 웹 릴리스 메타데이터에서 변경하십시오. 웹 전용修정의 경우 원본 버전 필드를 변경하지 않도록 하십시오. OTA 번들에서는 설치된 바이너리에서 선언된 기능을 변경하거나 원본 code를 추가할 수 없습니다. 따라서 원본 버전을 변경하는 대신 호환성을 개선하는 것이 아니라 호환성을 숨기게 됩니다.
위치한 채널에 서명된 아티팩트를 업로드하십시오:
npx @capgo/cli bundle upload --channel production
성공적인 업로드는 서버가 요청을 수락했음을 확인합니다. 명령어 출력을 읽고 번들 식별자, 대상 네이티브 버전 제약조건, 서명된 체크섬, 채널 assignments을 확인하십시오. 이 필드는 아티팩트를 식별하고 설치된 바이너리가 업데이트를 받을 수 있는지 여부를 보여줍니다.
릴리스 게이트로 대시보드를 읽으십시오
번들 상세보기 화면은 네 가지 릴리스 질문을 해결해야 합니다:
- 최소 네이티브 버전: 이 번들을 실행할 수 있는 가장 오래된 바이너리는 무엇인가요?
- 최대 네이티브 버전: 이번 번들을 받을 수 있는 더 새로운 바이너리는 무엇인가요?
- 채널: 이 아티팩트를 발견할 수 있는 대상은 누구인가요?
- 배포율: 수락 가능한 대상 중 몇 명이 해당 업데이트를 받을 수 있는지?
생산 환경 노출을 시작할 때 5%, 그 후 확장에 필요한 증거를 정의하세요. 다운로드 및 설치 성공, 정상적인 холод 시작, 충돌 없는 세션, 변경된 흐름에서 JavaScript 오류를 확인하세요. artifact 식별성과 전달 제어를 함께 Capgo 대시보드에서 표시하세요.

디바이스 경로를 연습하기 위해 디버그 빌드를 사용하세요. getCurrent() 활성 배포본을 보고 notifyAppReady() 새로운 배포본이 건강한 상태에 도달했는지 확인합니다:
import { CapacitorUpdater } from '@capgo/capacitor-updater'
const current = await CapacitorUpdater.getCurrent()
console.log(current)
await CapacitorUpdater.notifyAppReady()
앱이 초기화되면 충분히 진행된 후에만 준비 상태를 호출하세요. 준비 상태를 확인하지 못하면 자동 복구는 다음 холод 시작 시 배포본을 실패로 표시할 수 있습니다. 이 안전 장치로 생산 사용자 보호가 가능하지만, 테스트가 완료되지 않은 경우 배포 문제로 오인할 수 있습니다. 테스트 디바이스의 활성 배포본과 시작 결과를 기록하세요.
채널, 롤아웃, CI/CD 자동화
채널은 배포본과 설치된 디바이스 사이의 라우팅層입니다. 또한 릴리즈 게이트입니다. 스테이징 채널은 알려진 네이티브 바이너리에 포인팅되어야 하며, 베타 채널은 제어된 코호트를 제공해야 하며, 생산 채널은 이전 채널이 스모크 테스트를 통과한 후에만 이동해야 합니다.
명시적인 이름을 사용하여 스테이징 경로를 생성하세요.
npx @capgo/cli channel create staging
npx @capgo/cli bundle assign <bundle-id> --channel staging
테스트 기기에서 사용하는 네이티브 버전으로 채널을 핀하세요. 테스터들은 프로덕션에서 지원하는 동일한 바이너리를 실행해야 하며, 로컬 개발 빌드에 추가 플러그인이나 다른 구성으로 실행하지 마세요. 스모크 스위트가 통과되면 테스트된 아티팩트를 승격하세요. 두 번째, 약간 다른 배포본을 업로드하는 대신.
채널 맵은 capgo.config.json and be reviewed like application code. Keep channel names stable, identify the intended native compatibility range, and make production promotion an explicit CI action. For teams managing feature exposure alongside delivery exposure, these 채널 이름은 안정적이어야 하며, 네이티브 호환성 범위가 명확해야 하며, 프로덕션 승격은 명시적인 CI 작업으로 처리되어야 합니다. 기능 노출과 배포 노출을 관리하는 팀에게는 기능 플래그 관리 팁
이러한 기능 플래그 관리 팁은 배포 권한과 사용자에게 노출되는 활성화 권한을 분리하는 데 유용한 방법을 제공합니다.
실용적인 GitHub 액션 디자인은 두 가지 경로를 가지고 있습니다.
- 실용적인 Actions 디자인은 두 가지 경로를 가집니다:
- Pull requests: 웹层를 빌드하고, 제한된 프리뷰 자격증명을 사용하여 서명하고, 임시 프리뷰 채널에 게시하세요. Pull request가 닫히면 채널을 삭제하거나 만료하세요.
Tagged main releases:
npx @capgo/cli bundle promote <bundle-id> \
--to-channel production \
--percent 5
노출을 의도적으로 단계별로 증가시키십시오. 25%, 50%, 및 100%CI 승인 또는 모니터링된 작업이 각 단계 사이에 있으면 됩니다. 백분율과 명령은 안전성을 증명하는 것이 아닙니다. 빌드가 통과되면 번들에 문법적 오류가 없다는 것을 알려줍니다. 그러나 특정 네이티브 바이너리, persisted local state, 느린 네트워크, 또는 이전 세션에서 재개된 기기에서 어떻게 동작하는지 알려주지 않습니다.
릴리즈 경계: 웹 번들이 바이너리 호환성 윈도우에 속합니다. 채널은 설치된 앱이 포함하지 않는 네이티브 API를 참조하는 code을 제공하는 구멍으로 절대 변하지 않아야 합니다.
테스트 플라이트와 안드로이드 내부 트랙 빌드를 일관되게 유지하려면 각 번들을 정확히 네이티브 버전으로 빌드한 버전과 연결하세요. 네이티브 빌드가 변경되면 새로운 호환성 대상 번들을 게시하거나 새로운 채널 매핑을 생성하세요. __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ Actions 통합 가이드는 정책을 반복 가능한 워크플로우 단계로 번역하는 데 도움이 될 수 있습니다. Capgo GitHub 액션 통합 가이드 테스트 전략 및 자동 롤백

세 가지 테스트 계층을 사용하십시오.
__CAPGO_KEEP_0__ __CAPGO_KEEP_1__ Actions 통합 가이드
__CAPGO_KEEP_0__
- CI 패키지 테스트: 단위 테스트, 타입 체크, 린팅, 그리고 프로덕션 웹 빌드를 실행합니다. 변경된 체크아웃, 인증, 네비게이션, 그리고 영구 저장 경로를 실행하는 대신 컴파일을 중단하지 않습니다.
- 개인 장치 채널: 이전 네이티브 바이너리를 실행하는 물리 장치에 개인 채널을 시드합니다. 양쪽 플랫폼, 깨끗한 설치, 업그레이드 설치, 그리고 대표적인 저장된 상태를 다룹니다.
- 프로덕션 카나리: 작은 적격 조사를 시작하고, 연결된 크래시 리포팅, 그리고 자바스크립트 오류 알림을 활성화합니다. 시작 실패를 급박하게 다루는 이유는 영향을 받은 사용자가 오류를 보고하는 code에 도달하지 못할 수 있기 때문입니다.
The Capacitor OTA 테스트 가이드 __CAPGO_KEEP_0__ OTA 테스트 가이드는 테스트 메커니즘을 설명합니다. 작동 규칙은 간단합니다: 업데이트를 보호하는 네이티브 바이너리와 테스트하는 업데이트를 비교합니다.
서버와 클라이언트를 분리하여 복구합니다
서버 측 롤백은 새로운 다운로드를 중단합니다:
npx @capgo/cli channel set production --bundle <previous-id>
이것은 다음으로 발견되는 장치의 종류를 변경합니다. 다운로드나 활성화된 장치에 있는 패키지를 지우지 않기 때문에, 클라이언트도 복구 제어가 필요합니다. 업데이터를 구성하여 알려진 좋은 대체물과 정의된 시작 실패 조건 후에 복구하도록 합니다.
신뢰할 수 있는 복구 경로는 다음과 같습니다:
- 다운로드 실패 추적: 네트워크 문제와 유효하지 않은 아티팩트를 구분하십시오.
- 설치 실패 추적: 압축 해제, 검증 및 파일 시스템 문제를 감지하십시오.
- 부팅 건강 추적: 활성화 후 앱이 사용 가능한 상태에 도달하는지 확인하십시오.
- 자동으로 이전에 알려진 좋은 버전으로 되돌아가십시오. 수동으로 상승시키십시오:
- 지원 및 엔지니어링을 위해 장치와 버전 식별자를 보존하십시오. fleet 규모에서 작은 실패율은 여전히 큰 지원 부담을 유발합니다.
A small failure rate still creates a significant support load at fleet scale. 99.95%의 OTA 업데이트 성공률은 여전히 1,000,000 대기 중 1,000 대의 장치 실패를 의미합니다.따라서 IoT 대규모 장치군의 OTA 테스트 벤치마크에 따르면. 동일한 출처는 30분 이내의 롤백, 0.1% 미만의 충돌률 및 98%의 장치가 지원 범위 내에 있는지 확인합니다. 이러한 벤치마크를 예시로만 사용하십시오. 앱의 위험과 사용자 영향에 따라 오류 배지치를 설정하십시오.
인증, 보안, OTA가 변경할 수 없는 것
unsigned 업데이트는 배송 엔드포인트가 공급 chain 공격 표면이 됩니다. TLS는 연결을 보호하지만, 클라이언트는 다운로드한 아티팩트가 인증된 릴리즈 프로세스에서 왔으며, 전송 중에 대체되거나 변경되지 않았는지 확인해야 합니다.
업데이터 도구를 사용하여 Ed25519 키 pairs를 생성하십시오. 개인 키는 CI secret에 저장하고, 공개 검증 키는 앱 빌드 중에 네이티브 바이너리에 임베드하십시오. 클라이언트는 활성화 전에 모든 번들을 확인하십시오. 환경 및 권한 범위에 따라 CLI 토큰을 제한하고, 업로드 및 프로모션 로그를 유지하고, 프로덕션 액션에 대해 강력한 인증을 요구하십시오.
기존 키 회전을 호환성 마이그레이션으로 대체하는 것처럼 다루세요. 새로운 키를 생성하고, 현재 키와 새로운 키를 모두 신뢰하는 네이티브 빌드를 배포한 후, 새로운 개인 키로 릴리스를 서명하세요. 호환성 있는 네이티브 바이너리들이 새로운 키를 채택한 후에만 이전 키를 제거하세요. 이전 키를 너무 일찍 제거하면 더 오래된 바이너리들이 유효한 업데이트를 수용할 수 없습니다. 새로운 키를 무한정 신뢰하는 것은 회전을 무력화합니다.
릴리스 계획의 경계를 그으세요.
OTA는 웹-layer 변경 사항을 처리합니다. 설치된 바이너리에서 부재하는 기능에 의존하는 변경 사항은 네이티브 릴리스가 필요합니다:
| 분류 | OTA를 통해 배포 | 네이티브 릴리스가 필요 |
|---|---|---|
| 애플리케이션 동작 | JavaScript 논리, 라우팅, 유효성 검사, 상태 처리 | 네이티브 플러그인 구현 |
| 표현 | CSS, HTML, 복사본, 테마 토큰, 호환 가능한 이미지 자산 | 애플리케이션 아이콘 및 스플래시 리소스 |
| 플랫폼 접근 | 기존 Capacitor 웹 레이어 호출을 바이너리 내에 이미 있는 기능에 대해 | 새로운 권한, 특권, 또는 네이티브 API |
| 설정 | 호환되는 웹 설정 및 원격 콘텐츠 규칙 | Info.plist, AndroidManifest.xml, 서명 식별 |
| 스토어 메타데이터 | None이 스토어 검토 동작이나 버전 메타데이터를 변경하지 않는 | 스토어 정책에敏感한 메타데이터 및 버전 번호 변경 |
The Capacitor 업데이터 code 서명 문서 은 검증 모델에 대한 설명입니다. 버전 위조 또는 키 위협에 대한 감사 로그, 인증서 검증, TLS, 엄격한 접근 제어 및 버전 위조 또는 키 위협에 대한 조사 프로세스를 적용하여 실제로 작동합니다.
호환성 목표는 여전히 중요합니다. 설치된 네이티브 인구가 점진적으로 변하기 때문입니다. 애플은 모바일 장치의 66%가 iOS 26을 사용하고 있습니다. 그리고 최근 4년 동안 소개된 장치의 74%가 iOS 26을 사용하고 있습니다.iOS 26은 모바일 장치의 79%를 차지하는 것으로 나중에 사이클에서 보고되었습니다.이러한 통계는 다르며 장치 인구를 다룹니다. 실무 결론은 일관적입니다: 성숙한 플랫폼은 모든 장치를 한 번에 업데이트하지 않습니다. 네이티브 버전과 기능성에 따라 배ंडल을 assign하세요. 한 번에 모든 장치에 OTA artifact를 가정하지 마십시오. 운영 체크리스트릴리스 체크리스트를 한 페이지로 유지하고 저장소나 runbook에 저장하세요. 릴리스마다 업데이트하세요. 실제 실패 후 추가된 제어가 다음 재발을 방지합니다.
업로드하기 전에
업로드하기 전에
업로드하기 전에
- 확인 가능성: bundle이 정확한 네이티브 바이너리와 사용하지 않는 플러그인 API를 사용하지 않는지 확인합니다.
- 아티팩트 확인: clean workspace에서 빌드하고 생성된 파일을 검사한 후 원하는 웹 버전을 확인합니다.
- 인증 보호: CI가 예상한 비밀과 키를 가지고 있는지 확인하고 로그가 개인 정보를 노출하지 못하는지 확인합니다.
- 채널 유효성: 배포 전, 베타, 및 운영 채널 매핑을 검토한 후 배포 패키지를 assign합니다.
- 복구 보존: 이전의 알려진 좋은 배포 패키지를 기록하고 fallback 경로가 작동하는지 확인합니다.
- 물리적 스모크 테스트: 대표적인 장치에서 시작, 로그인, 체크아웃, 탐색, 영속성, 업데이트 준비를 테스트합니다.
광고 기간 동안
Release to 한정된 집단에 먼저, 그리고 사용자 영향과 관련된 신호를 관찰하세요:
- Crash-free sessions: 이전 버전과 비교하여 결과를 확인하고 regession을 조사하세요.
- 자바스크립트 오류율: 오류를 버전, 네이티브 버전, 플랫폼, 기능 경로로 그룹화하세요.
- cold-start behavior: 활성화가 시작 시간이나 사용자가 빈 화면에 남아 있는지 확인하세요.
- 기능 커버리지: 원격으로 활성화된 기능이 받는 바이너리와 일치하는지 확인하세요.
- OTA 업데이트를 위한 도입과 실패: 업데이트를 확인하지 않은 적합한 장치와 업데이트를 확인했지만 실패한 장치를 분리하세요.
30분간의 첫 번째 포스트-프로모션 관찰 창을 유지하고 30분 노출을 확장하기 전에.
중요 경로가 깨지면, 이전 버블로 프로덕션 채널을 되돌려서 로그를 보존하고, 수정이 다른 OTA 버블이나 새로운 네이티브 릴리스에 속하는지 결정하세요. 배송 일일 규율:
Treat this checklist as shared operational code. Capgo can provide signed bundle delivery, channel targeting, rollout controls, update history, and device-level observability. Your team still owns compatibility policy and the decision to promote.
이 체크리스트를 공유 운영 Capgo으로 다루세요. __CAPGO_KEEP_1__은 서명된 버블 전달, 채널 대상 설정, 롤아웃 제어, 업데이트 기록, 장치 수준 관찰성을 제공할 수 있습니다. 팀은 호환성 정책과 프로모션 결정을 여전히 소유합니다. Capgo __CAPGO_KEEP_0__