CLI 온보딩 가이드

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

한눈에 보기

Capgo CLI는 Capacitor 앱에 라이브 업데이트를 설정하는 인터랙티브 온보딩을 제공합니다. 다음을 진행합니다:

✅ Capgo에 앱 등록
🔌 updater 플러그인 설치 및 설정
🚀 첫 번째 live update 배포
📱 기기에서 업데이트 테스트

예상 소요 시간: 10-20분 (인터넷 속도 및 빌드 시간에 따라 달라질 수 있음)

온보딩 시작하기

온보딩 명령어를 API 키로 실행하세요:

npx @capgo/cli@latest init [APIKEY]

다음과 같은 환영 메시지가 표시됩니다:

Capgo onboarding 🛫

온보딩 진행 과정

CLI은 13개의 인터랙티브 단계를 안내합니다:

설정 단계 (1~6단계):

개발 환경 확인 (Xcode/Android Studio)
Capgo에 앱을 추가하고 프로덕션 채널 생성
먼저 @capgo/capacitor-updater 플러그인
앱에 필요한 code 주입
필요 시 종단 간 암호화 활성화
테스트 플랫폼 선택 (iOS 또는 Android)

테스트 단계 (7~12단계):

앱 빌드 후 디바이스/시뮬레이터에서 실행
가시적인 code 변경 사항 생성 (자동 또는 수동)
업데이트된 번들을 Capgo에 업로드
기기에 live update가 실시간으로 나타나는 것을 확인하세요

완료 (13단계):

앱이 Live Update를 사용할 준비가 되었습니다! 🎉

13단계 온보딩 과정

1단계: 사전 요구사항 확인

CLI는 개발 환경에서 필요한 도구가 설치되어 있는지 확인합니다.

확인 항목:

iOS 프로파일링 (macOS 전용) - iOS 개발용
Android SDK 설정 - Android 개발용

가능한 결과:

✅ 두 환경 모두 발견됨:

✅ Xcode detected - iOS development ready
✅ Android SDK detected - Android development ready

⚠️ 환경이 발견되지 않음:

⚠️ Xcode not found
⚠️ Android SDK not found
❌ No development environment detected

📱 To develop mobile apps with Capacitor, you need:
   • For iOS: Xcode (macOS only) - https://developer.apple.com/xcode/
   • For Android: Android Studio - https://developer.android.com/studio

질문할 수 있는 항목:

2단계: 앱 추가하기

CLI가 Capgo에 로그인하게 하고 계정에 앱을 추가합니다.

(spinner) Running: npm @capgo/cli@latest login ***
Login Done ✅

❓ Add {appId} in Capgo?

앱 ID가 이미 사용 중인 경우:

CLI가 다음 대안을 제안합니다:

❌ App ID "com.example.app" is already taken
💡 Here are some suggestions:
   1. com.example.app2
   2. com.example.app3
   3. com.example.app.new
   4. com.example.app.app

❓ What would you like to do?

제안된 ID를 선택하거나 직접 앱 ID를 입력할 수 있습니다.

3단계: 프로덕션 채널 생성

Channel을 사용하면 앱의 다양한 업데이트 스트림을 관리할 수 있습니다.

❓ Create default channel production for {appId} in Capgo?

Yes를 선택하면:

(spinner) Running: npm @capgo/cli@latest channel add production {appId} --default
Channel add Done ✅  (or "Channel already added ✅")

production channel이 생성되고 기본 channel로 설정됩니다. 대부분의 사용자에게 권장되는 옵션입니다.

No를 선택하면:

If you change your mind, run it for yourself with: "npm @capgo/cli@latest channel add production {appId} --default"

나중에 채널을 직접 만들고 설정해야 합니다. 또는 다음 방법을 사용할 수 있습니다:

다음에서 채널을 설정하세요: capacitor.config.ts 파일
JavaScript setChannel() method를 사용하여 채널을 동적으로 설정하세요
나중에 Capgo 웹 콘솔에서 채널을 구성하세요

4단계: Updater Plugin 설치

CLI가 다음을 설치합니다: @capgo/capacitor-updater 사용 중인 Capacitor 버전과 호환되는 plugin.

❓ Automatic Install "@capgo/capacitor-updater" dependency in {appId}?

버전 호환성:

Capacitor 5: 설치 @capgo/capacitor-updater v5
Capacitor 6: 설치 @capgo/capacitor-updater v6
Capacitor 7: 설치 @capgo/capacitor-updater v7
Capacitor 8+: 최신 버전 설치

즉시 업데이트 옵션:

설치 후 다음을 묻습니다:

❓ Do you want to set instant updates in {appId}?
   Read more: https://capgo.app/docs/live-updates/update-behavior/#applying-updates-immediately

Yes를 선택하면:

앱이 백그라운드로 전환된 후 다시 열릴 때 즉시 적용되도록 업데이트가 구성됩니다
autoUpdate: 'always' 및 autoSplashscreen: true 설정 파일에 추가됩니다
@capacitor/splash-screen 누락 시 다음과 함께 설치됩니다 launchAutoHide: false
여러분의 capacitor.config.ts 자동으로 업데이트됩니다
델타 업데이트 활성화된 상태로 유지됩니다. 즉시 적용(always, atInstall, onLaunch)은 다음을 계속 사용해야 합니다 npx @capgo/cli@latest bundle upload --delta 변경된 파일만 다운로드되어 사용자가 전체 zip을 기다리지 않도록 합니다

No를 선택하면:

업데이트는 표준 동작(백그라운드 다운로드, 다음 재시작 시 적용)을 사용합니다
언제든 다음을 수정하여 즉시 업데이트를 활성화할 수 있습니다 capacitor.config.ts

5단계: Code 연동 추가

CLI가 메인 애플리케이션 파일에 필요한 code을 자동으로 주입합니다.

❓ Automatic Add "CapacitorUpdater.notifyAppReady()" code and import in {appId}?

추가되는 항목:

import { CapacitorUpdater } from '@capgo/capacitor-updater'

CapacitorUpdater.notifyAppReady()

프로젝트 유형 감지:

Nuxt.js: 생성 plugins/capacitorUpdater.client.ts
기타 프레임워크: 메인 엔트리 파일에 추가

자동 주입이 실패하는 경우, 메인 애플리케이션 파일에 code를 직접 추가할 수 있습니다:

Nuxt.js의 경우: 생성 plugins/capacitorUpdater.client.ts:

import { CapacitorUpdater } from '@capgo/capacitor-updater'

export default defineNuxtPlugin(() => {
  CapacitorUpdater.notifyAppReady()
})

다른 프레임워크의 경우: 메인 엔트리 파일에 추가하세요 (예: main.ts, index.js, App.tsx):

import { CapacitorUpdater } from '@capgo/capacitor-updater'

CapacitorUpdater.notifyAppReady()

이 code를 import 문 뒤, 앱 초기화 코드 앞에 배치하세요. 자세한 내용은 다음을 참고하세요: 앱 추가 가이드.

6단계: 암호화 설정 (선택 사항)

종단간 암호화는 업데이트에 추가 보안 계층을 더합니다.

🔐 End-to-end encryption
   ✅ Use this for: Banking, healthcare, or apps with legal encryption requirements
   ⚠️  Note: Makes debugging harder - skip if you don't need it

❓ Enable end-to-end encryption for {appId} updates?

암호화를 활성화하면 CLI가 다음 작업을 수행합니다:

암호화 키 생성
Capacitor 설정 동기화 제안

7단계: 플랫폼 선택

온보딩 과정에서 테스트할 플랫폼을 선택하세요.

📱 Platform selection for onboarding
   This is just for testing during onboarding - your app will work on all platforms

❓ Which platform do you want to test with during this onboarding?
   Options:
   - iOS
   - Android

8단계: 프로젝트 빌드

CLI가 앱을 빌드하고 Capacitor과 동기화합니다.

❓ Automatic build {appId} with "npm run build"?

어떤 일이 일어나나요:

프로젝트 유형 감지
빌드 스크립트 실행
실행 npx cap sync {platform}

빌드 스크립트가 없는 경우:

빌드를 건너뛸지, 아니면 빌드 스크립트를 추가할지 묻습니다. package.json.

9단계: 디바이스에서 실행

디바이스 또는 시뮬레이터에서 앱의 초기 버전을 테스트합니다.

❓ Run {appId} on {PLATFORM} device now to test the initial version?

다음 항목을 선택하면 지원:

(spinner) Running: npx cap run {platform}
(device picker appears)
App started ✅
📱 Your app should now be running on your {platform} device with Capgo integrated
🔄 This is your baseline version - we'll create an update next

10단계: 테스트 변경 사항 만들기

이제 눈에 띄는 변경 사항을 만들어 Capgo의 업데이트 시스템을 테스트할 차례입니다.

🎯 Now let's test Capgo by making a visible change and deploying an update!

❓ How would you like to test the update?
   Options:
   - Auto: Let Capgo CLI make a visible change for you
   - Manual: I'll make changes myself

자동 모드: CLI이 파일을 자동으로 수정해 눈에 보이는 테스트 배너나 변경 사항을 추가합니다.

수동 모드: 직접 변경합니다(예: 텍스트, 색상 변경 또는 요소 추가).

버전 처리:

❓ How do you want to handle the version for this update?
   Options:
   - Auto: Bump patch version ({currentVersion} → {nextVersion})
   - Manual: I'll provide the version number

변경 사항 포함 빌드:

❓ Build {appId} with changes before uploading?

11단계: Bundle 업로드

업데이트된 앱 번들을 Capgo에 업로드하세요.

❓ Upload the updated {appId} bundle (v{version}) to Capgo?

CLI가 실행합니다:

npx @capgo/cli@latest bundle upload

Delta 업데이트 프롬프트(즉시 적용 모드가 활성화된 경우):

💡 Instant updates are enabled in your config
   Delta updates send only changed files instead of the full bundle

❓ Enable delta updates for this upload? (Recommended with instant updates)

성공:

✅ Update v{version} uploaded successfully!
🎉 Your updated bundle is now available on Capgo

12단계: 기기에서 업데이트 테스트

이제 업데이트가 실제로 작동하는지 확인해 보세요!

🧪 Time to test the Capgo update system!
📱 Go to your device where the app is running

즉시 업데이트를 위해:

🔄 IMPORTANT: Background your app (swipe up/press home button) and then reopen it
⏱️  The update should be downloaded and applied automatically

표준 업데이트를 위해:

📱 With standard updates, you will need to:
   1. Background the app (swipe up/press home button) to start download
   2. Wait a few seconds for download to complete
   3. Background and foreground again to see the update

로그 모니터링:

❓ Monitor Capgo logs to verify the update worked?

을(를) 선택하면 지원기기의 업데이트 과정을 보여주는 실시간 로그를 확인할 수 있습니다.

13단계: 완료

Welcome onboard ✈️!

축하합니다! 앱에 Capgo 라이브 업데이트를 성공적으로 설정했습니다.

완료한 작업

온보딩을 완료하면 다음을 갖추게 됩니다:

✅ 앱 등록 완료

앱이 프로덕션 채널과 함께 Capgo에 등록되었습니다

✅ 플러그인 설치 완료

Capacitor Updater 플러그인이 설치 및 설정되었습니다

✅ Code 통합 완료

앱에 code 통합이 추가되었습니다

✅ 업데이트 테스트 완료

배포를 성공적으로 완료하고 live update을(를) 받았습니다

일일 워크플로우

이후 업데이트에는 다음을 사용하세요:

npm run build
npx @capgo/cli@latest bundle upload --channel=production

추가 배포 옵션은 다음을 참고하세요 Live Update 배포.

온보딩 재개

온보딩 과정을 종료해도 언제든 이어서 진행할 수 있습니다:

npx @capgo/cli@latest init [APIKEY]

다음과 같은 내용을 확인합니다:

You have already got to the step {stepNumber}/13 in the previous session
❓ Would you like to continue from where you left off?

문제 해결

개발 환경 없음

문제: Xcode 또는 Android SDK이(가) 감지되지 않았습니다.

해결 방법:

iOS의 경우: 설치하기 iOS 프로파일링 (macOS 전용)
Android의 경우: 설치하기 디버깅하기

이미 사용 중인 App ID

문제: 이미 등록된 App ID입니다.

해결 방법: 제안된 대안 중 하나를 선택하거나 역도메인 표기법으로 사용자 지정 앱 ID를 입력하세요.

Build Script 없음

문제: 다음 경로에서 build script를 찾을 수 없습니다: package.json.

해결 방법: 다음 위치에 build script를 추가하세요: package.json:

{
  "scripts": {
    "build": "your-build-command"
  }
}

Auto-Injection 실패

문제: CLI은(는) code 통합을 자동으로 주입할 수 없습니다.

해결 방법: 메인 파일에 code를 수동으로 추가하세요:

import { CapacitorUpdater } from '@capgo/capacitor-updater'

CapacitorUpdater.notifyAppReady()

Capacitor 버전이 너무 낮음

문제: 현재 Capacitor 버전이 v5보다 낮습니다.

해결 방법: Capacitor를 v5 이상으로 업그레이드하세요:

다음 단계

온보딩을 완료했으니 다음 주제들을 살펴보세요:

최초 1회 설정 체크리스트

채널, CI, 델타 업로드를 한 번만 설정해 장기적인 안정성을 확보하세요

업데이트 배포

Capgo 대시보드에서 업데이트를 배포하는 방법을 알아보세요

업데이트 유형

모든 OTA 업데이트 유형 레퍼런스: 적용 시점, 지연 조건, 버전 차단, 전달

CI/CD 통합

CI/CD로 업데이트 배포를 자동화하세요

채널

채널로 여러 업데이트 스트림 관리

암호화

종단 간 암호화로 업데이트 보호

업데이트 동작

업데이트 적용 시점 및 방식 커스터마이징 (direct, delta 등)

도움 받기

온보딩 중 문제가 발생하면:

앱 통합의 문제 해결 가이드
커뮤니티에 Discord 커뮤니티
다음을 참고하세요: 자주 묻는 질문
문의하기 지원

CLI 온보딩 가이드에서 계속 진행하기

사용 중이라면 CLI 온보딩 가이드 대시보드 및 API 운영을 계획하려면, 이를 다음과 연결하세요 API 개요 구현 세부 사항은 API 개요에서 소개 구현 세부 사항은 소개에서 API 키 구현 세부 사항은 API 키에서 기기 구현 세부 사항은 기기에서, 그리고 번들 Bundles의 구현 세부 사항은