App Store 심사 없이 Capacitor 수정 사항 배포하기
오전 8시에 결제 페이지의 CSS 정렬 문제가 발생했다고 가정해 봅시다. iOS, Android 릴리스와 Native Build, 그리고 며칠간의 심사 대기까지... 이제 그런 패닉은 필요 없습니다.
새 웹 번들을 빌드하여 제어 가능한 Capgo 채널에 푸시하면, 호환되는 기기들이 앱 스토어 심사 없이 즉시 번들을 다운로드합니다. CSS, JavaScript, 문구 및 에셋 수정은 몇 분 안에 사용자에게 전달되며네이티브 변경 사항은 기존의 바이너리 릴리스 경로를 그대로 따릅니다.
목차
Live Update가 필요한 순간
Native Build은 멀쩡하지만 웹 레이어에 수정이 필요한 경우 live update가 효과적입니다. CSS 정렬 문제라면? 스타일시트를 수정하고, 웹 에셋을 다시 빌드한 뒤, 서명된 번들을 배포하세요. 버그가 발견된 지 한 시간 뒤인 오전 9시, 사용자는 앱을 다시 실행하는 것만으로 수정 사항을 적용받습니다. Capgo은 updater를 통해 번들을 적용하며, Native Build에는 전혀 영향을 주지 않습니다.
어떤 방식을 선택할지 결정하는 기준은 다음과 같습니다:
- live update 사용 JavaScript 동작, CSS, 텍스트, 설정 및 호환 가능한 에셋 수정 시.
- Native Release 사용 플러그인 변경, 권한, 네이티브 의존성 또는 OS 레벨 기능 수정 시.
- 채널을 통해 테스트 모든 고객에게 수정 사항을 배포하기 전에 미리 검증하세요.
| 배포 유형 | 주요 용도 | 사용자 영향 |
|---|---|---|
| Native 패키지 | 새로운 Native 기능 | 스토어 심사 및 다운로드 |
| Live 웹 번들 | 긴급 호환성 수정 | 앱 실행 시 업데이트 |
Native 레이어와 웹 레이어의 호환성을 유지하세요. Live 번들로는 현재 설치된 바이너리에 포함되지 않은 Native API를 안전하게 추가할 수 없습니다. 새로운 플러그인을 추가하거나 권한을 변경하려면 반드시 Native Build가 필요하며, 이는 피할 수 없는 과정입니다.
단계별 배포 순서가 궁금하시다면 다음 문서를 읽어보시는 것을 추천합니다. Capgo 핫픽스 배포 가이드. 이 가이드는 실제 운영 환경의 사용자를 QA 팀으로 활용하지 않고도, 검증된 수정 사항을 통제된 방식으로 릴리스하는 과정을 설명합니다.
프로덕션에 업데이트를 배포하기 전에, 먼저 로컬 빌드 환경을 확실히 구축하세요. 먼저 Capgo의 오픈 소스 updater 플러그인을 설치한 다음, TypeScript 패키지를 추가하여 에디터에서 타입 에러 없이 updater 메서드를 인식할 수 있도록 설정하세요. Capacitor 프로젝트의 경우, 로컬 Capacitor 환경 설정 가이드를 북마크해 두는 것을 추천합니다. 깨끗한 워크스페이스를 준비하는 과정을 상세히 안내합니다.
Web Asset의 예측 가능성 유지하기
Live bundle에는 편집 중인 임의의 소스 파일이 아닌, 컴파일된 web asset만 포함되어야 합니다. 빌드 명령을 실행했을 때 최종 JavaScript, CSS, HTML 및 호환 가능한 asset들이 항상 native shell이 참조하는 동일한 www 또는 public 디렉토리에 출력되도록 프로젝트를 구성하세요.
실제 적용 사례는 다음과 같습니다. 체크아웃 스타일시트를 변경한 후, 평소처럼 web build를 실행하고 출력 디렉토리를 확인하여 생성된 파일이 이전 버전을 제대로 대체했는지 확인하세요. 컴파일된 파일을 수동으로 수정하지 마세요. 다음 빌드 시 변경 사항이 인지하지 못한 채 덮어씌워져 사라질 수 있습니다.
live update는 web build에 포함된 내용만 전달할 수 있습니다. 수정 사항이
www또는public기기에서 해당 업데이트를 받을 수 없습니다.
개발(development), 스테이징(staging), 운영(production)을 위한 별도의 채널을 설정하세요. 특히 여러 팀원이 미완성된 bundle을 동시에 테스트하는 경우, 개발용 build가 운영 채널을 가리키지 않도록 주의해야 합니다.
- 개발 문제가 있는 import나 누락된 asset을 사전에 잡아냅니다.
- Staging 릴리스와 유사한 설정으로 실제 기기 동작을 검증합니다.
- Production 검증이 완료된 bundle만 배포하며, 실험적인 코드는 포함하지 않습니다.
배포 전 Bundle 검증하기
업로드 전 짧은 무결성 검사를 실행하세요. 이를 통해 사용자에게 전달될 수 있는 대부분의 문제를 미리 방지할 수 있습니다:
- 이전 빌드 결과물을 삭제한 후, 새로 빌드하세요.
- 수정된 파일이 출력 디렉토리에 실제로 존재하는지 확인하세요.
- 변경한 기능뿐만 아니라 네비게이션, 로그인, 오프라인 동작, 네이티브 플러그인 호출 등을 테스트하세요.
- iOS와 Android 테스트 기기 모두에 번들을 설치하세요.
- 나중에 이슈를 재현할 수 있도록 테스트 시 사용한 채널과 번들 버전을 기록해 두세요.
Electron 팀도 동일한 원칙을 적용할 수 있습니다. 렌더러 에셋을 별도로 빌드한 다음, 패키징된 애플리케이션이 의도한 출력 디렉토리를 참조하는지 확인하세요. Capgo의 타입이 지정된 API와 채널 제어 기능은 이 워크플로우를 일관되게 반복하기 쉽게 만들어 주지만, 실제 호환성 테스트를 대신할 수는 없습니다. 변경 사항에 새로운 네이티브 플러그인이나 권한이 필요한 경우, 라이브 웹 번들로 배포하려 하지 말고 새로운 바이너리를 게시하세요. 업데이트 도구는 네이티브 code을 스스로 수정할 수 없습니다.
Capacitor 및 Electron 앱에서 파일 업데이트를 정확하게 수행하는 핵심은 단 하나, 바로 견고한 릴리스 아티팩트입니다. 이미 테스트를 마친 정확한 커밋에서 웹 레이어를 빌드한 다음, 모든 JavaScript, CSS, HTML 및 에셋이 다음 위치에 있는지 다시 한번 확인하세요. www 또는 public 예상대로 있는지 확인하세요. Electron을 사용하는 경우 렌더러를 별도로 빌드하고, 패키징된 셸이 해당 출력 위치를 가리키고 있는지 검증하세요.
검증 가능한 번들 생성하기
업로드를 시작하기 전에 기존의 빌드 결과물을 모두 삭제하고 프로덕션 빌드를 새로 실행하세요. 이때 커밋 해시, bundle 버전, 대상 channel, 그리고 native app 버전을 함께 기록해 두어야 합니다. 이 정보들은 나중에 버전 불일치 문제가 발생했을 때 삽질 시간을 획기적으로 줄여줍니다.
항상 실제 기기(iPhone, Android 또는 Electron 환경)에서 bundle을 확인하세요. 로그인, 네비게이션, 오프라인 모드, 그리고 방금 업데이트한 파일과 연관된 모든 native plugin을 직접 테스트해야 합니다. 업데이트 서버에 업로드에 성공했다고 해서 끝이 아닙니다. 기기에서 실제로 정상 작동하는지가 핵심입니다.
Signing은 아티팩트에 암호화된 지문을 부여합니다. Updater는 이 서명을 통해 bundle이 release pipeline을 거치며 변조되지 않았음을 확인합니다. Signing 자격 증명은 레포지토리 외부에 완전히 분리하여 저장하고, 접근 권한을 엄격히 제한하며, 보안 정책에 따라 주기적으로 교체하세요.
Signed bundle이 테스트를 대신할 수는 없습니다. Signing은 아티팩트의 출처와 변조 여부를 증명할 뿐, 앱이 실제로 잘 작동할지는 보장하지 않습니다.
더 자세한 내용이 궁금하다면 다음 가이드를 읽어보세요. Capgo의 end-to-end 보안 및 code signing 가이드.
제어된 Channel을 통한 배포
Signed bundle이 준비되면 Capgo에 업로드하고, 배포 전략에 맞는 channel을 할당하세요. 주로 사용하게 될 channel은 다음과 같습니다:
- Beta — 내부 직원 및 선정된 테스터용
- Staging — 실제 사용자가 확인하기 전, 운영 환경과 유사한 환경에서 검증하기 위해
- Production — 승인된 대상 사용자용
- 고객별 전용 채널 — 테넌트마다 독립적인 업데이트 시점이 필요한 경우
자주 발생하는 시나리오가 있습니다. 한 핀테크 팀이 운영 환경에서 결제 라벨 오류를 발견했습니다. 이들은 수정된 web bundle을 내부 채널에 푸시하여 몇 대의 기기에서 결제 과정을 검증한 뒤, 검증된 동일한 아티팩트를 소규모 운영 세그먼트에 먼저 배포하고 점진적으로 확대합니다. 이러한 채널 가드레일 덕분에 급하게 적용한 수정 사항이 대규모 장애로 이어지는 것을 방지할 수 있습니다.
배포 후에는 대시보드의 요약 상태만 믿지 말고 기기별 로그를 자세히 살펴보세요. 올바른 앱 버전이 bundle을 가져왔는지, 서명이 유효한지, 설치가 깔끔하게 완료되었는지, 그리고 다음 실행 시 실제로 새 파일이 로드되었는지 확인해야 합니다.
기기에서 불일치 보고가 발생하면 즉시 해당 채널을 중단하고 bundle 버전, native 호환성, 서명 키, 채널 할당 상태를 대조해 보세요. 테스트 그룹의 로그가 모두 정상인 것을 확인한 후에만 배포를 확대하고, 롤백을 위해 이전 bundle을 항상 보관해 두어야 합니다.
로컬 빌드가 원활하게 돌아간다면, 이제 배포를 CI/CD pipeline에 통합할 차례입니다. 목표는 명확합니다. 웹 에셋을 빌드하고, bundle에 서명한 뒤, 테스트 통과 후 자동으로 배포하는 것입니다. 더 이상 수동으로 upload할 필요도, 머지 후 파일을 어떻게 업데이트할지 고민할 필요도 없습니다. 프로세스가 알아서 처리해 줍니다.
실제 파이프라인은 다음과 같이 구성됩니다:
- release 브랜치가 target 브랜치로 머지될 때 작업을 실행합니다.
- 의존성을 설치하고 깨끗한 상태에서
www또는publicbuild를 생성합니다. - 단위 테스트, 통합 테스트, 디바이스 smoke 테스트를 포함한 전체 테스트 스위트를 실행합니다.
- CI secret manager에 저장된 인증 정보를 사용하여 bundle에 서명합니다.
- Capgo의 공개 API을 통해 beta 또는 staging 채널로 push합니다.
- 검증이 완료되면 동일한 artifact를 그대로 다음 단계로 프로모션합니다. 다시 빌드하지 마세요.
다시 한번 강조하지만, 서명 키나 API token을 레포지토리에 커밋하지 마세요. 보호된 환경 변수로 저장하고, 프로덕션 배포는 승인된 브랜치로만 제한하며, bundle 버전, commit hash, native app 버전, 대상 채널과 함께 모든 릴리스를 로그로 남기세요. Capgo의 GitHub Actions 통합 가이드에서 이 과정을 처음부터 끝까지 단계별로 안내합니다.
여기서 핵심은 검증 단계가 배포 프로세스의 일부로 유지되어야 한다는 점입니다.게시가 끝이 아닙니다. 파이프라인을 통해 대상 기기가 번들을 실제로 수신하고 수락했는지 확인해야 합니다.
차분 업데이트(Differential Updates)로 전송 비용 절감하기
매번 전체 번들을 배포하는 것은 낭비입니다. 특히 스타일시트나 몇 개의 JavaScript 모듈만 변경된 경우라면 더욱 그렇습니다. 차분 배포를 활성화하여 기기가 변경된 파일만 다운로드하도록 하세요. 다만, 삭제되거나 이름이 변경된 에셋이 어떻게 처리되는지 반드시 테스트해야 합니다. 그렇지 않으면 프로덕션 환경에서 당황스러운 상황을 겪을 수 있습니다.
제가 본 한 에이전시는 전체 재빌드 방식에서 증분 배포 방식으로 전환한 후 평균 대역폭 비용을 47% 만큼 절감했습니다. 진정한 이점은 연결 속도가 느린 사용자들에게 돌아갔으며, 다운로드 크기가 작아지면서 설치 시간도 눈에 띄게 빨라졌습니다.
노출 범위를 제어하기 위해 별도의 채널을 사용하는 것도 권장합니다:
- Beta 채널은 내부 빌드를 배포하고 테스터의 피드백을 수집합니다.
- Staging 채널은 고객에게 영향을 주지 않고 운영 환경 설정을 그대로 미러링합니다.
- Production 확장하기 전에 제한된 사용자 그룹을 대상으로 작게 시작하세요.
- 고객 채널 테넌트별 릴리스를 서로 격리된 상태로 유지합니다.
테스트 완료된 아티팩트를 프로모션하세요. 단계마다 다시 빌드하지 마세요. 환경마다 다시 빌드하면 설정 드리프트가 발생하며, 존재해서는 안 될 차이점 때문에 디버깅을 해야 하는 상황이 생깁니다.
핀테크 앱 같은 경우, 다음과 같은 흐름이 적절합니다. 먼저 직원들에게 배포한 뒤, 대상 사용자의 5%에게 릴리스하고, 기기별 로그를 점검합니다. 채택률이 안정적이고 실패율이 일정하게 유지될 때만 범위를 확장하세요. 또한 이전 bundle을 항상 보관해야 합니다. 문제가 생기면 몇 시간이 아니라 몇 분 안에 중단하거나 롤백할 수 있어야 합니다.
bundle을 게시하는 것은 중간 단계일 뿐입니다. 사용자가 실제로 업데이트를 받았는지 확인하려면, Capgo의 기기별 로그를 열어 native 버전, channel, bundle 버전, signature validation, download 상태 및 설치 결과를 확인하세요.
정상적인 롤아웃은 단순히 download 완료가 아니라, 설치 후 성공적인 실행이 확인되어야 합니다. 결제 오류 수정의 경우, 여러 기기에서 실제 구매 흐름을 테스트한 뒤, 느린 네트워크나 구버전 앱을 사용하는 사용자들의 리포트와 결과를 비교해 보세요.
업데이트 시그널을 명확하게 확인하기
채택률과 실패 지표를 함께 보세요. 다운로드율은 높은데 실행 실패가 반복되면 번들이 손상된 것이고, 채택률이 낮으면 채널 타겟팅, 오프라인 기기, 업데이터 설정 문제일 수 있습니다.
| 신호 | 일반적인 의미 |
|---|---|
| 다운로드됨 | 기기에서 번들을 가져옴 |
| 설치됨 | 파일 설치 검사 통과 |
| 실행 성공 | 새 파일로 앱이 열림 |
| 롤백됨 | 이전의 정상 작동 번들로 복원됨 |
다운로드만 보지 말고 성공적인 실행을 추적하세요. 업데이트는 사용자가 앱을 정상적으로 열고 사용할 수 있을 때 비로소 완료된 것입니다.
Capgo의 자동 롤백 보호 기능은 새 번들이 크래시를 유발하거나 실행을 방해할 때 안전망 역할을 합니다. 이전 버전을 유지하고, 해당 채널을 일시 중지한 뒤, 로그를 조사하여 원인을 파악한 후 다른 아티팩트를 배포하세요.
비디오 버전 관리 개념은 라이브 배포 파이프라인에서 파일 업데이트를 모니터링하고 롤백을 관리하는 방식과 유사하므로, 팀에서 다음과 같은 상황일 때 유용할 수 있습니다. 교육용 비디오 버전을 관리할 때.
릴리스 검증
다음 릴리스 후 체크리스트를 활용하세요:
- 채널 및 앱 버전별 적용 여부를 확인합니다.
- 다운로드 실패, 서명 오류, 실행 실패 사례를 검토합니다.
- 실제 기기에서 변경된 워크플로우를 테스트합니다.
- 에러 발생 시점과 릴리스 타임스탬프를 비교합니다.
- 실패율이 예상치 못하게 증가하면 배포를 일시 중지합니다.
- 최종 번들, 커밋 및 롤백 결정 사항을 기록합니다.
더 자세한 가이드는 다음을 참고하세요: Capacitor 앱에서 OTA 업데이트를 모니터링하는 방법. 이를 통해 파일 업데이트를 단순한 배포 작업이 아닌, 제어 가능한 운영 프로세스로 전환할 수 있습니다.
Live Updates는 스토어 규정을 준수하나요?
Live Updates는 다음 작업에 가장 적합합니다: JavaScript, CSS, 카피 변경, 설정 수정 및 호환 가능한 에셋. 이는 네이티브 기능을 추가하거나, 권한을 변경하거나, 스토어 심사를 우회하기 위한 백도어가 아닙니다. 배포 전 항상 해당 앱 카테고리에 대한 Apple 및 Google의 정책을 확인하세요.
Differential Updates는 어떻게 다운로드 용량을 줄이나요?
Differential delivery는 전체 웹 번들을 보내는 대신 실제로 변경된 파일만 전송합니다. 예를 들어 결제 페이지의 스타일시트 하나만 수정했다면, 관련 없는 다른 에셋까지 모두 다시 보낼 필요가 없습니다. 이는 전송 속도를 높이고 대역폭 소모를 줄여줍니다.
다만, 파일 이름 변경이나 삭제된 파일은 주의해야 합니다. 이전 버전의 오래된 에셋이 남아 있으면 추적하기 어려운 기묘한 버그가 발생할 수 있습니다.
작은 패치라도 전체 호환성 테스트가 필요합니다. 다운로드 용량이 작아졌다고 해서 전체 사용자 흐름(user flow)을 검증해야 하는 필요성이 사라지는 것은 아닙니다.
기기가 오프라인 상태일 때는 어떻게 되나요?
오프라인 기기는 현재 설치된 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 오류가 발생하면 보통 아티팩트 변조, 잘못된 자격 증명 또는 설정 문제인 경우가 많습니다. 배포를 중단하고, 테스트한 내용과 실제 게시된 내용을 비교한 뒤, 다시 시도하기 전에 device logs를 면밀히 분석하세요.
실무적인 배포 워크플로우를 위해, Capgo를 살펴보세요 — 서명된 release, channel 제어, 차등 배포(differential delivery), rollback 보호 기능을 제공하여 번거로움 없이 파일을 업데이트할 수 있습니다.
