CLI 온보딩 가이드

빠른 개요

The Capgo CLI는 라이브 업데이트를 위한 Capacitor 앱을 설정하는 인터랙티브 온보딩을 제공합니다. 당신은:

1. ✅ Capgo에 앱을 등록합니다.
2. 🔌 업데이터 플러그인을 설치하고 구성합니다.
3. 🚀 live update을 첫 번째로 배포하세요
4. 📱 장치에서 업데이트를 테스트하세요

예상 시간: 10-20분 (인터넷 속도와 빌드 시간에 따라 다름)

팁

온보딩은 완전히 재개할 수 있습니다 - 언제든지 중단하고 나중에 다시 시작하세요.

온보딩 시작

API 키와 함께 온보딩 명령을 실행하세요:

npx @capgo/cli@latest init [APIKEY]

당신은 welcome 메시지를 볼 것입니다:

Capgo onboarding 🛫

온보딩 과정

CLI는 13 개의 인터랙티브 스텝을 통해 당신을 안내할 것입니다:

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

• 개발 환경을 확인하세요 (Xcode/Android Studio)
• Capgo에 앱을 추가하고 프로덕션 채널을 생성하세요
• __CAPGO_KEEP_0__ @capgo/capacitor-updater plugin
• code
• 선택적으로 종단-to-종단 암호화를 활성화하세요
• 플랫폼을 선택하세요 (iOS 또는 Android)

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

• 앱을 빌드하고 디바이스/에뮬레이터에서 실행하세요
• code에 대한 가시적인 변경을 만들세요 (자동 또는 수동)
• Capgo에 업데이트된 번들을 업로드하세요
• live update가 디바이스에서 실시간으로 나타나세요

완료 (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를 입력할 수 있습니다.

주의사항

App ID는 역 도메인 표기법을 따르야 합니다 (예:) com.example.myapp)

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

채널은 앱 업데이트를 관리하는 데 도움이 됩니다.

❓ 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 ✅")

생산 채널이 생성되고 기본 채널로 설정됩니다. 대부분의 사용자에게 추천되는 옵션입니다.

만약 No를 선택하면:

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

이후에 채널을 수동으로 생성하고 설정해야 합니다. alternatively,

• 채널을 설정하는 방법은: capacitor.config.ts 파일
• JavaScript setChannel() 동적으로 채널을 설정하는 방법
• 이후에 Capgo 웹 콘솔에서 채널을 설정합니다.

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

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

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

__CAPGO_KEEP_0__ 5

• Capacitor 5__CAPGO_KEEP_0__ 6 @capgo/capacitor-updater v6
• Capacitor 7__CAPGO_KEEP_0__ 6 @capgo/capacitor-updater v7
• Capacitor 8: 설치합니다. @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 이내에 업데이트 배포가 가능하기 때문에 무방비적으로 작동합니다. 그렇지 않은 표준 모드에서는 업데이트 다운로드가 배경에서 진행되어 다음 앱 재시작 시 적용됩니다. 즉시 업데이트 기능은 개발 시 빠른 반복 개발 및 프로덕션 시점의 중요 버그 수정에 적합합니다.

Yes를 선택하면:

• 업데이트가 앱이 배경화면과 재개동 시 즉시 적용됩니다.
• autoUpdate: 'always' 그리고 autoSplashscreen: true config에 추가됩니다.
• @capacitor/splash-screen 미비가 없으면 설치됩니다. launchAutoHide: false
• 필요한 경우 capacitor.config.ts 자동으로 업데이트됩니다.
• 델타 업데이트 즉시 적용always, atInstall, onLaunch(') npx @capgo/cli@latest bundle upload --delta 변경된 파일만 다운로드하고 사용자는 전체 zip을 기다리지 않습니다.

만약 "No"를 선택하면

• 업데이트는 표준 동작을 사용합니다 (배경에서 다운로드, 다음 재시작 시 적용)
• Capgo를 사용하여 즉시 업데이트를 활성화하려면 설정을 수정할 수 있습니다. 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단계: 암호화 설정 (선택)

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?

Note

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

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

1. __CAPGO_KEEP_0__을 활성화하면 __CAPGO_KEEP_0__이:
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?

Yes Yes:

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

팁

다른 터미널에서 수동으로 빌드해야 한다면 "No"를 선택하고, 나머지 작업은 계속 진행하세요.

11단계: 배포 패키지 업로드

업데이트된 앱 배포 패키지를 Capgo에 업로드하세요.

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

CLI에서 실행됩니다.

npx @capgo/cli@latest bundle upload

Tip

Delta 업데이트와 즉시 업데이트: If you enabled instant updates in Step 4, the CLI will automatically ask if you want to enable delta updates. Delta updates send only the files that changed between versions instead of the entire bundle. Since usually only a few files change between updates, this makes downloads much faster. 선택 네 최적의 경험을 위해 즉시 업데이트.

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)

주의 필요

For monorepos, you may need to provide additional paths to your project. 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?

만약 네, __CAPGO_KEEP_0__에서 장치에 대한 업데이트 프로세스를 보여주는 실시간 로그를 볼 수 있습니다.

13 단계: 완료

Welcome onboard ✈️!

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

이제 무엇을 accomplished했습니다.

✅ 앱 등록

__CAPGO_KEEP_0__에서 앱이 프로덕션 채널에 등록되었습니다.

애플리케이션은 Capgo에서 프로덕션 채널로 등록되었습니다.

protectedTokens

Capacitor 업데이터 플러그인은 설치 및 구성되었습니다.

✅ Code 통합

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

✅ 업데이트 테스트

live update를 성공적으로 배포하고 받았습니다.

일일 워크플로우

다음 업데이트를 위해 사용하세요:

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

추가 배포 옵션을 보려면 Live Update를 배포하세요..

Onboarding을 다시 시작합니다.

온보딩 프로세스를 중단한 경우 언제든지 다시 시작할 수 있습니다:

npx @capgo/cli@latest init [APIKEY]

You’ll see:

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: 설치 : 설치

앱 ID 이미 사용 중입니다.

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

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

빌드 스크립트 누락

문제: 빌드 스크립트가 package.json.

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

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

자동 주입 실패

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

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

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

CapacitorUpdater.notifyAppReady()

Capacitor 버전이 너무 낮음

문제: Capacitor 버전이 v5 미만입니다.

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

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

다음 단계

다음 단계 섹션

온보딩을 완료한 후 이 주제를 탐색하세요:

한 번만 설정하는 체크리스트

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

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

업데이트 유형

OTA 업데이트의 모든 유형에 대한 참조: 적용 시간, 지연 조건, 버전 차단 및 전달

CI/CD 통합

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

채널

업데이트 채널을 통해 여러 업데이트 스트림을 관리하세요.

암호화

업데이트를 암호화하여 보안하세요.

업데이트 동작

업데이트를 언제, 어떻게 적용할지 직접, 델타 등으로 커스터마이즈하세요.

도움말

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

• 체크하는 문제 해결 가이드
• 디스코드 커뮤니티에 가입하세요 FAQ를 검토하세요
• 문의 지원
• Contact Support

CLI 온보딩 가이드에서 계속

__CAPGO_KEEP_0__ 온보딩 가이드에서 계속 CLI 온보딩 가이드 API를 연결하여 대시보드와 API 운영을 계획하세요. API 개요 API 개요에서 구현 세부 정보를 참조하세요. 소개 소개에서 구현 세부 정보를 참조하세요. API 키 API 키에서 구현 세부 정보를 참조하세요. 장치 for Devices의 구현 세부 사항에 대해 Bundles 패키지