앱 스토어 지연 없이 Capacitor 수정 배포하기
아침 8시에 체크아웃 페이지에 CSS 정렬 문제가 생겼습니다. 당황이 시작됩니다 — iOS 릴리스, Android 릴리스, 네이티브 리빌드, 며칠간의 리뷰가 필요합니다. 이제 더 이상 아닙니다.
새로운 웹 번들을 빌드하고, 제어된 Capgo 채널에 푸시하면, 호환되는 기기들이 앱 스토어 리뷰 대기열에 영향을 주지 않고 이를 가져옵니다. CSS, JavaScript, 카피, 에셋 수정은 몇 분 만에 사용자에게 반영할 수 있고, 반면 네이티브 변경 사항은 여전히 일반적인 바이너리 릴리스 경로를 따릅니다.
목차
Live File Update가 적합한 경우
live update는 네이티브 셸은 정상이지만 웹 레이어에 문제가 있을 때 유용합니다. CSS 정렬 문제라면? 스타일시트를 수정하고 웹 에셋을 다시 빌드한 뒤 서명된 번들을 배포하세요. 버그가 발견된 지 1시간 후인 오전 9시, 사용자는 다음 앱 실행 시 수정 사항을 받게 됩니다. Capgo는 업데이터를 통해 번들을 적용하며 네이티브 바이너리는 전혀 건드리지 않습니다.
어떤 경로를 선택할지 판단하는 기준은 다음과 같습니다:
- live update 사용 JavaScript 동작, CSS, 텍스트, 설정 및 호환되는 에셋에 대해.
- 네이티브 릴리스 사용 플러그인 변경, 권한, 네이티브 의존성 또는 OS 레벨 기능에 대해.
- 채널을 통해 테스트 모든 고객에게 수정 사항을 노출하기 전에.
| 릴리스 유형 | 일반적인 용도 | 사용자 영향 |
|---|---|---|
| 네이티브 패키지 | 새로운 네이티브 기능 | 스토어 다운로드 및 심사 |
| Live 웹 번들 | 긴급 호환성 수정 | 앱 시작 시 업데이트 |
네이티브 레이어와 웹 레이어의 호환성을 유지하세요. Live bundle은 설치된 바이너리에 없는 네이티브 API를 안전하게 도입할 수 없습니다. 새 플러그인을 추가하거나 권한을 변경하는 경우 Native build가 필수이며, 이를 피할 수 있는 방법은 없습니다.
단계별 배포 순서를 확인하려면 Capgo 핫픽스 배포 가이드를 읽어보시길 권합니다. 테스트를 마친 수정 사항을, 프로덕션 사용자를 QA 팀으로 쓰지 않고 통제된 릴리스로 옮기는 과정을 안내합니다.
프로덕션에 업데이트를 푸시하기 전에, 먼저 로컬 빌드부터 확실히 잡아두세요. Capgo의 오픈소스 업데이터 플러그인을 설치한 다음, TypeScript 패키지를 추가해 에디터가 업데이터 메서드를 제대로 인식하고 타입 누락 오류가 뜨지 않도록 하세요. Capacitor 프로젝트라면, 해당 로컬 Capacitor 환경 설정 가이드 를 북마크해 두는 것이 좋습니다. 깔끔한 워크스페이스를 준비하는 방법을 안내합니다.
웹 에셋을 예측 가능하게 유지하기
라이브 번들에는 컴파일된 웹 에셋만 들어가며, 직접 수정할 수 있는 소스 파일은 포함되지 않습니다. 빌드 명령이 항상 최종 JavaScript, CSS, HTML 및 호환 에셋을 동일한 위치에 출력하도록 프로젝트를 구성하세요. www 또는 public 네이티브 셸이 참조하는 디렉터리.
실제로는 이렇게 됩니다. 체크아웃 스타일시트를 변경한 뒤 평소처럼 웹 빌드를 실행하고, 출력 디렉터리에서 생성된 파일이 이전 버전을 실제로 대체했는지 확인하세요. 컴파일된 파일을 직접 편집하지 마세요. 다음 빌드에서 조용히 덮어써져 변경 사항을 알아차리지 못한 채 잃게 됩니다.
live update는 웹 빌드에 포함된 것만 전달할 수 있습니다. 수정 사항이 빠져 있다면
www또는public, 기기에서는 이를 받을 수 없습니다.
개발, 스테이징, 프로덕션용 채널을 각각 설정하세요. 개발용 build는 프로덕션 채널을 가리켜서는 안 됩니다. 특히 여러 팀원이 미완성 bundle을 동시에 테스트할 때는 더욱 그렇습니다.
- 개발 깨진 import와 누락된 asset을 미리 잡아냅니다.
- 무대 구성 릴리스와 유사한 설정으로 실제 기기 동작을 검증합니다.
- 프로덕션 승인 및 테스트를 거친 bundle만 제공하며, 실험적인 요소는 없습니다.
배포 전 Bundle 검증하기
무엇이든 업로드하기 전에 짧은 무결성 검사를 실행하세요. 이렇게 하면 사용자에게 전달될 뻔한 대부분의 문제를 잡아냅니다:
- 이전 빌드 결과물을 삭제한 후, 새로 빌드하세요.
- 수정된 파일이 출력 디렉토리에 실제로 존재하는지 확인하세요.
- 변경한 기능뿐만 아니라 네비게이션, 로그인, 오프라인 동작, 네이티브 플러그인 호출 등을 테스트하세요.
- iOS와 Android 테스트 기기 모두에 번들을 설치하세요.
- 나중에 이슈를 재현할 수 있도록 테스트 시 사용한 채널과 번들 버전을 기록해 두세요.
Electron 팀도 동일한 원칙을 적용할 수 있습니다. 렌더러 에셋을 별도로 빌드한 다음, 패키징된 애플리케이션이 의도한 출력 디렉토리를 참조하는지 확인하세요. Capgo의 타입이 지정된 API와 채널 제어 기능은 이 워크플로우를 일관되게 반복할 수 있도록 도와주지만, 실제 호환성 테스트를 대신할 수는 없습니다. 변경 사항에 새로운 네이티브 플러그인이나 권한이 필요한 경우, 라이브 웹 번들로 배포하려 하지 말고 새로운 바이너리를 게시하세요. 업데이터는 네이티브 code을 스스로 수정할 수 없습니다.
Capacitor 및 Electron 앱에서 파일 업데이트를 제대로 처리하는 핵심은 견고한 릴리스 아티팩트입니다. 이미 테스트한 정확한 커밋에서 웹 레이어를 빌드한 다음, 모든 JavaScript, CSS, HTML 및 에셋이 www 또는 public 예상대로 들어 있는지 확인하세요. Electron을 사용하는 경우 렌더러를 별도로 빌드하고, 패키징된 셸이 해당 출력을 가리키는지 검증하세요.
검증 가능한 Bundle 생성하기
업로드를 생각하기도 전에 기존 빌드 산출물을 모두 지우고 프로덕션 빌드를 새로 실행하세요. 커밋 해시, 번들 버전, 대상 채널, 네이티브 앱 버전을 함께 적어 두세요. 나중에 뭔가 맞지 않을 때 이 정보가 몇 시간씩 머리 싸매는 수고를 덜어줍니다.
항상 실제 기기에서 번들을 확인하세요 — 실제 iPhone, Android 폰, Electron 설치 환경에서요. 로그인, 내비게이션, 오프라인 모드, 그리고 방금 업데이트한 파일을 건드리는 모든 네이티브 플러그인을 하나씩 점검하세요. 업데이트 서버에 업로드하는 데 성공했다고 해서, 기기에서 실제로 실행되지 않는다면 아무 소용이 없습니다.
서명은 아티팩트에 암호학적 지문을 부여합니다. 업데이터는 이 서명을 통해 번들이 릴리스 파이프라인을 거치면서 손대지 않은 채 전달되었는지 확인합니다. 서명 자격 증명은 저장소 외부에 완전히 보관하고, 누가 접근할 수 있는지 엄격히 제한하며, 보안 정책에서 요구하는 주기에 맞춰 교체하세요.
서명된 번들은 테스트를 대체할 수 없습니다. 서명은 아티팩트가 어디서 왔고 변조되지 않았다는 것만 증명할 뿐, 앱이 실제로 그 번들과 함께 정상 작동하는지에 대해서는 아무것도 말해주지 않습니다.
전체 그림을 보고 싶다면, 이 글을 읽어보시길 권합니다: Capgo의 엔드투엔드 보안 및 code 서명 가이드.
제어된 채널을 통한 배포
서명된 번들이 준비되면 Capgo에 업로드하고 롤아웃 전략에 맞는 채널에 할당하세요. 앞으로 가장 많이 쓰게 될 채널은 다음과 같습니다:
- 베타 — 내부 직원 및 선별된 테스터용
- 무대 구성 — 실제 사용자가 보기 전에, 프로덕션과 유사한 환경에서 검증하기 위해
- 프로덕션 — 승인된 대상 사용자용
- 고객별 전용 채널 — 테넌트마다 독립적인 업데이트 시점이 필요한 경우
자주 나오는 시나리오가 있습니다. 한 핀테크 팀이 프로덕션에서 결제 라벨 오류를 발견했습니다. 이들은 수정된 web bundle을 내부 채널에 push해 몇 대의 기기에서 결제 과정을 검증한 뒤, 검증된 동일한 아티팩트를 소규모 프로덕션 세그먼트에 먼저 배포하고 점차 확대합니다. 이러한 채널 가드레일 덕분에 급하게 적용한 수정이 대규모 장애로 번지는 일을 막을 수 있습니다.
배포 후에는 대시보드의 집계 상태만 믿지 말고 기기별 logs를 자세히 살펴보세요. 올바른 앱 버전이 bundle을 가져왔는지, 서명이 검증되었는지, 설치가 깔끔하게 끝났는지, 그리고 다음 실행에서 실제로 새 파일이 로드되었는지 확인해야 합니다.
기기에서 불일치가 보고되면 즉시 해당 채널을 중단하고 bundle 버전, native 호환성, 서명 키, 채널 할당을 나란히 비교해 보세요. 테스트 그룹 전체에서 logs가 정상으로 확인된 뒤에만 배포를 확대하고, 롤백을 위해 이전 bundle은 항상 남겨 두세요.
로컬 빌드가 원활하게 돌아간다면, 이제 배포를 CI/CD pipeline에 통합할 차례입니다. 목표는 명확합니다. web assets를 빌드하고, bundle에 서명한 뒤, 테스트 통과 후 자동으로 publish하는 것. 더 이상 수동 upload도, merge 후 파일을 어떻게 업데이트할지 고민할 필요도 없습니다. 프로세스가 알아서 처리해 줍니다.
실제로 실용적인 pipeline은 이렇게 생겼습니다:
- 릴리스 브랜치가 대상 브랜치에 병합될 때 작업을 실행하세요.
- 의존성을 설치하고 클린
www또는publicbuild를 생성하세요. - 단위 테스트, 통합 테스트, 디바이스 스모크 테스트를 포함한 전체 테스트 스위트를 실행하세요.
- CI 시크릿 매니저에 저장된 자격 증명으로 bundle에 서명하세요.
- Capgo의 공개 API를 통해 베타 또는 스테이징 채널로 push하세요.
- 검증이 통과되면 동일한 아티팩트를 그대로 다음 단계로 승격하세요. 다시 build하지 마세요.
다시 강조할 점: 서명 키나 API 토큰을 리포지토리에 커밋하지 마세요. 보호된 환경 변수로 저장하고, 프로덕션 배포는 승인된 브랜치로만 제한하며, bundle 버전, 커밋 해시, 네이티브 앱 버전, 대상 채널과 함께 모든 릴리스를 로그로 남기세요. Capgo의 GitHub Actions 통합 가이드 이 과정을 처음부터 끝까지 설정하는 방법을 안내합니다.
여기서 핵심은 검증이 배포 프로세스의 일부로 유지된다는 점입니다.게시가 끝이 아닙니다. 파이프라인은 대상 기기가 번들을 실제로 수신하고 수락했는지 확인해야 합니다.
Differential Updates로 전송 비용 줄이기
매번 전체 번들을 배포하는 것은 낭비입니다. 특히 릴리스에서 스타일시트나 JavaScript 모듈 몇 개만 바뀌는 경우에는 더욱 그렇습니다. 기기가 변경된 파일만 다운로드하도록 차등 배포를 활성화하세요. 단, 삭제되거나 이름이 바뀐 에셋이 어떻게 처리되는지 반드시 테스트하세요. 그렇지 않으면 프로덕션에서 낭패를 볼 수 있습니다.
제가 본 한 에이전시는 이 문제를 해결하면서 평균 대역폭 비용을 47% 만큼 절감했습니다. 전체 재번들에서 증분 배포로 전환한 뒤였죠. 진정한 이점은 느린 연결 사용자에게 있었고, 다운로드가 줄면서 설치 시간도 눈에 띄게 빨라졌습니다.
또한 배포 범위를 제어하려면 별도 채널을 사용하는 것도 권장합니다:
- 베타 내부 빌드를 진행하고 테스터 피드백을 수집합니다.
- 무대 구성 고객에게 영향을 주지 않고 프로덕션 설정을 그대로 미러링합니다.
- 프로덕션 확장하기 전에 제한된 대상부터 소규모로 시작할 수 있습니다.
- 고객 채널 테넌트별 릴리스를 서로 격리된 상태로 유지합니다.
테스트한 아티팩트를 프로모션하세요. 단계마다 다시 빌드하지 마세요. 환경마다 다시 빌드하면 드리프트가 생기고, 결국 존재해서는 안 될 차이를 디버깅하게 됩니다.
핀테크 앱 같은 경우 흐름은 다음과 같습니다. 먼저 직원들에게 배포한 뒤, 대상 사용자의 5%에게 릴리스하고, 기기별 로그를 점검합니다. 채택률이 양호하고 실패율이 늘지 않을 때만 범위를 확장하세요. 그리고 이전 bundle은 항상 보관해야 합니다. 문제가 생기면 몇 시간이 아니라 몇 분 안에 중단하거나 롤백할 수 있어야 합니다.
bundle을 게시하는 것은 중간 단계일 뿐입니다. 사용자가 실제로 업데이트를 받았는지 확인하려면 Capgo의 기기별 로그를 열어 네이티브 버전, 채널, bundle 버전, 서명 검증, 다운로드 상태, 설치 결과를 확인하세요.
정상적인 롤아웃은 단순히 다운로드 완료가 아니라 설치 후 성공적인 실행이 확인되어야 합니다. 결제 오류 수정의 경우 여러 기기에서 실제 구매 흐름을 테스트한 뒤, 느린 네트워크나 구버전 앱을 쓰는 사용자들의 리포트와 결과를 비교해 보세요.
Update 신호를 명확히 읽기
채택률과 실패 지표를 함께 보세요. 다운로드율이 높은데 실행 실패가 반복되면 번들이 손상된 것이고, 채택률이 낮으면 채널 타겟팅, 오프라인 기기, 업데이터 설정 문제일 수 있습니다.
| 시그널 | 일반적인 의미 |
|---|---|
| 다운로드 완료 | 기기에서 번들을 가져옴 |
| 설치 완료 | 파일이 설치 검사를 통과함 |
| 실행 성공 | 새 파일로 앱이 열림 |
| 롤백됨 | 이전의 검증된 번들로 복구됨 |
다운로드만 보지 말고 성공적인 실행을 추적하세요. 업데이트는 사용자가 앱을 정상적으로 열고 사용할 수 있을 때 비로소 운영 상태가 됩니다.
Capgo의 자동 롤백 보호는 새 번들이 크래시를 유발하거나 시작을 막을 때 안전망 역할을 합니다. 이전 버전을 유지하고, 영향을 받은 채널을 일시 중지한 후, 다른 아티팩트를 배포하기 전에 로그를 조사하세요.
비디오 버전 관리는 라이브 배포 파이프라인에서 파일 업데이트 모니터링 및 롤백 관리와 개념적으로 유사하므로, 팀은 다음 작업을 수행할 때 이 아이디어가 유용할 수 있습니다. 학습 비디오 버전 관리.
릴리스 검증하기
이 짧은 배포 후 체크리스트를 사용하세요:
- 채널 및 앱 버전별 채택률을 확인하세요.
- 다운로드 실패, 서명 오류, 시작 실패를 검토하세요.
- 실제 기기에서 변경된 워크플로우를 테스트하세요.
- 오류 발생 시점을 배포 타임스탬프와 비교하세요.
- 실패가 예상치 않게 증가하면 배포를 일시 중지하세요.
- 최종 번들, 커밋, 롤백 결정을 기록하세요.
더 자세한 안내는 다음을 참고하세요: Capacitor 앱에서 OTA 업데이트를 모니터링하는 방법. 이를 통해 파일 업데이트는 단순한 배포 작업을 넘어 제어 가능한 운영 프로세스로 전환됩니다.
Live Update가 스토어 규정을 준수하나요?
Live Updates는 다음에 가장 적합합니다: JavaScript, CSS, 문구 변경, 설정 조정, 호환 에셋. 이는 네이티브 기능을 추가하거나, 권한을 변경하거나, 스토어 심사를 우회하기 위한 백도어가 아닙니다. 배포 전 항상 앱 카테고리에 따른 Apple 및 Google 정책을 확인하세요.
Differential Updates는 다운로드 용량을 어떻게 줄이나요?
Differential delivery는 전체 웹 번들을 보내는 대신 실제로 변경된 파일만 전송합니다. 예를 들어 결제 페이지의 스타일시트 하나만 수정했다면, 관련 없는 다른 에셋까지 모두 다시 보낼 필요가 없습니다. 이는 전송 속도를 높이고 대역폭 소모를 줄여줍니다.
다만 이름이 변경되거나 삭제된 파일은 주의 깊게 살펴보세요. 이전 버전에서 남아 있는 오래된 에셋은 추적하기 어려운 이상한 버그를 일으킬 수 있습니다.
작은 패치라도 전체 호환성 테스트는 반드시 필요합니다. 다운로드 용량이 작아도 전체 사용자 흐름을 검증해야 하는 건 마찬가지입니다.
기기가 오프라인일 때 어떻게 되나요?
오프라인 기기는 설치된 bundle을 계속 실행할 뿐입니다. 연결이 돌아오면 updater가 할당된 channel을 확인하고 호환되는 최신 release를 가져옵니다. 모든 기기가 즉시 업데이트된다고 가정하지 마세요 — 접속이 불안정한 현장 팀은 한동안 뒤처질 수 있습니다.
Breaking Changes를 어떻게 처리해야 하나요?
native binary와 web bundle은 짝을 이룬다고 생각하세요. 업데이트된 web 파일이 현재 설치된 binary에 없는 native method를 호출한다면, 먼저 새 native release를 배포한 뒤 그 위에 web update를 push해야 합니다.
beta, staging, production용 channel을 각각 운영하세요. 각 기기가 의도한 channel을 실제로 받고 있는지 다시 확인하세요. signature mismatch가 발생하면 보통 변조된 artifact, 잘못된 credential 또는 config 문제를 가리킵니다. 배포를 일시 중지하고, 게시한 내용과 테스트한 내용을 비교한 뒤, 다시 시도하기 전에 device logs를 자세히 살펴보세요.
실제 배포 워크플로우를 확인하려면, Capgo를 살펴보세요 — 서명된 release, channel 제어, differential delivery, rollback 보호 기능을 제공하므로 번거로움 없이 파일을 업데이트할 수 있습니다.
