CLI 온보딩 가이드

빠른 개요

Capgo CLI은 Capacitor 앱에 대한 실시간 업데이트를 설정하는 대화형 온보딩을 제공합니다. 당신은:

1. ✅ Capgo에 앱을 등록하세요.
2. 🔌 업데이터 플러그인 설치 및 구성
3. 🚀 첫 번째 라이브 업데이트 배포
4. 📱 기기에서 업데이트를 테스트하세요.

예상 시간: 10~20분(인터넷 속도 및 구축 시간에 따라 다름)

팁

온보딩은 완전히 재개 가능합니다. 언제든지 종료하고 나중에 중단한 부분부터 계속하세요.

온보딩 시작하기

API 키를 사용하여 온보딩 명령을 실행합니다.

npx @capgo/cli@latest init [APIKEY]

환영 메시지가 표시됩니다.

Capgo onboarding 🛫

온보딩 중에 일어나는 일

CLI은 13가지 대화형 단계를 안내합니다.

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

• 개발 환경을 확인하세요. (Xcode/Android Studio)
• Capgo에 앱을 추가하고 제작 채널을 만드세요.
• @capgo/capacitor-updater 플러그인 설치
• 앱에 필요한 코드를 삽입합니다.
• 선택적으로 종단 간 암호화를 활성화합니다.
• 테스트할 플랫폼 선택(iOS 또는 Android)

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

• 앱을 빌드하고 기기/시뮬레이터에서 실행
• 눈에 보이는 코드 변경(자동 또는 수동)
• 업데이트된 번들을 Capgo에 업로드하세요.
• 실시간 업데이트가 기기에 실시간으로 표시되는 것을 확인하세요.

완료(13단계):

• 앱이 실시간 업데이트될 준비가 되었습니다! 🎉

13단계 온보딩 프로세스

1단계: 전제조건 확인

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

확인한 내용:

• Xcode (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는 역도메인 표기법(예: com.example.myapp)을 따라야 합니다.

3단계: 제작 채널 생성

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

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

팁

걱정하지 마세요! 이는 온보딩 중 로컬 테스트를 위한 것입니다. “프로덕션” 채널을 만든다고 해서 업데이트가 고객에게 즉시 제공된다는 의미는 아닙니다. 업데이트 배포 시기를 완전히 제어할 수 있습니다. 특정 채널 요구사항이 없으면 예를 선택하세요.

예를 선택한 경우:

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

프로덕션 채널이 생성되고 기본값으로 설정됩니다. 이는 대부분의 사용자에게 권장되는 옵션입니다.

아니요를 선택하는 경우:

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

나중에 채널을 수동으로 만들고 구성해야 합니다. 또는 다음을 수행할 수 있습니다.

• capacitor.config.ts 파일에 채널을 설정하세요.
• JavaScript setChannel() 메서드를 사용하여 채널을 동적으로 설정합니다.
• Configure channels later from the Capgo web console

4단계: 업데이터 플러그인 설치

CLI은 Capacitor 버전과 호환되는 @capgo/capacitor-updater 플러그인을 설치합니다.

❓ 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+: 최신 버전 설치

주의

Capgo은 Capacitor v5 이상만 지원합니다. 이전 버전을 사용하는 경우 먼저 업그레이드해야 합니다.

즉시 업데이트 옵션:

설치 후 다음과 같은 질문이 표시됩니다.

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

팁

즉시 업데이트란 무엇입니까? 즉시 업데이트를 활성화하면 앱이 백그라운드에서 다시 열릴 때 즉시 업데이트를 적용합니다. Capgo는 300ms 이내에 전세계에 업데이트를 배포할 수 있기 때문에 원활하게 작동합니다. 이 기능이 없으면(표준 모드) 업데이트가 백그라운드에서 다운로드되고 다음에 앱을 다시 시작할 때 적용됩니다. 즉각적인 업데이트는 개발 중 더 빠른 반복과 프로덕션의 중요한 버그 수정에 적합합니다.

예를 선택한 경우:

• 앱이 백그라운드에서 다시 열리면 즉시 업데이트가 적용되도록 구성됩니다.
• directUpdate: 'always' 및 autoSplashscreen: true이 구성에 추가됩니다.
• capacitor.config.ts이 자동으로 업데이트됩니다.
• 델타 업데이트가 자동으로 활성화됩니다. 이는 전체 번들 대신 업데이트 간에 변경된 파일만 전송하므로 업데이트 속도가 훨씬 빨라집니다.

아니요를 선택하는 경우:

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

5단계: 통합 코드 추가

CLI는 필수 코드를 기본 애플리케이션 파일에 자동으로 삽입합니다.

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

추가되는 내용:

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

CapacitorUpdater.notifyAppReady()

프로젝트 유형 감지:

• Nuxt.js: plugins/capacitorUpdater.client.ts 생성
• Other frameworks: Adds to your main entry file

팁

자동 삽입에 실패하는 경우 기본 애플리케이션 파일에 코드를 수동으로 추가할 수 있습니다.

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()

가져온 후와 앱 초기화 전에 이 코드를 배치하세요. 자세한 내용은 앱 추가 가이드를 참조하세요.

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?

참고

암호화는 Capacitor v6 이상에서만 사용할 수 있습니다.

암호화를 활성화하면 CLI은 다음을 수행합니다.

1. 암호화 키 생성
2. 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"?

발생하는 상황:

1. 프로젝트 유형 감지
2. 빌드 스크립트를 실행합니다.
3. 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

Step 10: Make a Test Change

이제 눈에 띄는 변경을 적용하여 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단계: 번들 업로드

업데이트된 App Bundle을 Capgo에 업로드하세요.

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

The CLI runs:

npx @capgo/cli@latest bundle upload

팁

직접 업데이트를 통한 델타 업데이트: 4단계에서 즉시 업데이트(직접 업데이트)를 활성화한 경우 CLI는 델타 업데이트를 활성화할지 자동으로 묻습니다. 델타 업데이트는 전체 번들 대신 버전 간에 변경된 파일만 보냅니다. 일반적으로 업데이트 간에는 몇 개의 파일만 변경되므로 다운로드 속도가 훨씬 빨라집니다. 즉각적인 업데이트를 통해 최상의 경험을 얻으려면 예를 선택하세요.

델타 업데이트 프롬프트(직접 업데이트가 활성화된 경우):

💡 Direct Update (instant updates) is enabled in your config
   Delta updates send only changed files instead of the full bundle

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

주의

단일 저장소의 경우 package.json 및 node_modules에 대한 추가 경로를 제공해야 할 수도 있습니다.

성공:

✅ 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 업데이트 프로그램 플러그인이 설치 및 구성되었습니다.

✅ 코드 통합

통합 코드가 앱에 추가되었습니다.

✅ 업데이트 테스트됨

성공적으로 배포하고 실시간 업데이트를 받았습니다.

일일 작업 흐름

후속 업데이트의 경우 다음을 사용하십시오.

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

자세한 배포 옵션은 라이브 업데이트 배포를 참조하세요.

온보딩 재개

온보딩 프로세스를 종료하면 언제든지 재개할 수 있습니다.

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의 경우: Xcode 설치(macOS에만 해당)
• Android의 경우: Android Studio를 설치합니다.

앱 ID가 이미 사용되었습니다.

문제: 앱 ID가 이미 등록되어 있습니다.

해결책: 제안된 대안 중 하나를 선택하거나 역도메인 표기법으로 맞춤 앱 ID를 입력하세요.

빌드 스크립트 누락

문제: package.json에 빌드 스크립트가 없습니다.

해결책: package.json에 빌드 스크립트를 추가하세요.

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

자동 삽입 실패

문제: CLI는 통합 코드를 자동으로 삽입할 수 없습니다.

해결책: 기본 파일에 코드를 수동으로 추가하세요.

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

CapacitorUpdater.notifyAppReady()

Capacitor 버전이 너무 오래됨

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

해결책: Capacitor을 v5 이상으로 업그레이드하세요.

• Capacitor 5로 업그레이드 중
• Capacitor 6으로 업그레이드 중
• Capacitor 7로 업그레이드 중

다음 단계

이제 온보딩을 완료했으므로 다음 주제를 살펴보세요.

업데이트 배포

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

업데이트 유형

모든 OTA 업데이트 유형 참조: 적용 시기, 지연 조건, 버전 차단, 전달

CI/CD 통합

CI/CD를 사용하여 업데이트 배포 자동화

Channels

채널을 통해 여러 업데이트 스트림 관리

Encryption

엔드투엔드 암호화로 업데이트를 보호하세요

업데이트 동작

업데이트 적용 시기 및 방법 사용자 정의(직접, 델타 등)

도움 받기

온보딩 중에 문제가 발생하는 경우:

• 문제 해결 가이드를 확인하세요.
• Discord 커뮤니티에 가입하세요
• FAQ를 검토하세요.
• 지원팀에 문의하세요.