CLI 온보딩 가이드

빠른 개요

Capgo CLI은 Capacitor 앱에 대한 실시간 업데이트를 설정하는 인터랙티브 온보딩을 제공합니다.

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

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

팁

온보딩은 완전히 재개할 수 있습니다 - 언제든지 중단하고 나중에 중단한 곳부터 계속할 수 있습니다.

온보딩 시작

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

npx @capgo/cli@latest init [APIKEY]

welcome 메시지를 보실 수 있습니다:

Capgo onboarding 🛫

온보딩 과정

CLI은 13개의 인터랙티브 스텝을 통해 개발 환경을 설정해 드립니다:

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

• 개발 환경을 확인하세요 (Xcode/Android Studio)
• 앱을 Capgo에 추가하고 프로덕션 채널을 생성하세요
• Capgo를 설치하세요. @capgo/capacitor-updater 플러그인
• code을 앱에 필요한 항목으로 주입하세요.
• 선택적으로 종단-to-종단 암호화를 활성화하세요.
• 테스트를 위한 플랫폼을 선택하세요 (iOS 또는 Android).

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

• 앱을 빌드하고 디바이스/시뮬레이터에서 실행하세요.
• code에 대한 가시적인 변경을 만들세요 (자동 또는 수동).
• Capgo에 업데이트된 번들을 업로드하세요.
• 실시간으로 디바이스에서 라이브 업데이트를 볼 수 있습니다.

완료 (13 단계):

• 앱이 라이브 업데이트를 위해 준비되었습니다! 🎉

13 단계 온보딩 프로세스

1 단계: 사전 조건 확인

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

확인되는 항목:

• Xcode (macOS 전용) - iOS 개발을 위한
• Android SDK - Android 개발을 위한

가능한 결과:

✅ 모든 환경이 발견됨

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

⚠️ __CAPGO_KEEP_0__ 환경이 없습니다.:

⚠️ 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)에 따라야 합니다. com.example.myapp)

Step 3: 프로덕션 채널 만들기

클립보드에 복사

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

protectedTokens

걱정하지 마세요! 이것은 온보딩 중에만 로컬 테스트를 위한 것입니다. '생산' 채널을 생성하는 것은 즉시 고객에게 업데이트가 공개되는 것을 의미하지 않습니다. 업데이트를 배포할 때는 언제든지 완전한 제어가 가능합니다. 선택 특정 채널 요구 사항이 없다면 "예"를 선택하세요.

예를 선택하면:

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

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

• 채널을 설정할 수 있습니다. capacitor.config.ts 파일
• 자바스크립트를 사용하여 채널을 동적으로 설정하세요. setChannel() method를 사용하여 채널을 동적으로 설정하세요.
• 이후 Capgo 웹 콘솔에서 채널을 구성하세요.

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

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

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

__CAPGO_KEEP_0__ 5

• : Capacitor 5 버전을 설치합니다.v5 @capgo/capacitor-updater __CAPGO_KEEP_0__ 5
• Capacitor 6: __CAPGO_KEEP_0__을 설치합니다. @capgo/capacitor-updater v6
• Capacitor 7: __CAPGO_KEEP_0__을 설치합니다. @capgo/capacitor-updater v7
• Capacitor 8+: 최신 버전의 __CAPGO_KEEP_0__을 설치합니다.

주의

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 이내에 업데이트 배포가 가능하기 때문에, 즉시 업데이트 옵션을 활성화하면 앱이 배경화면과 재개동 시 업데이트 적용이 즉시 이루어집니다. 일반 모드(standard mode)에서는 업데이트 다운로드가 배경에서 진행되고, 다음 앱 재시작 시 적용됩니다. 즉시 업데이트 옵션은 개발 시 빠른 반복(iteration)과 프로덕션 시점의 крит적 버그 수정에 적합합니다.

Yes를 선택하면:

• 앱이 배경화면과 재개동 시 업데이트 적용이 즉시 이루어지도록 업데이트 구성이 설정됩니다.
• directUpdate: 'always' 그리고 autoSplashscreen: true config에 추가됩니다.
• 자동으로 capacitor.config.ts 자동으로 업데이트 됩니다.
• 델타 업데이트 자동으로 활성화 될 것입니다 - 업데이트가 발생할 때마다 변경된 파일만 전송하여 전체 배포 대신 업데이트를 훨씬 빠르게 만듭니다.

No를 선택하면:

• 업데이트는 표준 동작을 사용합니다 (배경에서 다운로드, 다음 재시작 시 적용)
• 업데이트를 즉시 활성화하려면 항상 __CAPGO_KEEP_0__를 수정할 수 있습니다. 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: Creates 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?

주의

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

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

__CAPGO_KEEP_0__에 업로드하세요.

❓ 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

직접 업데이트(Direct Update)과 함께 Delta 업데이트스: 4단계에서 즉시 업데이트(Direct Update)를 활성화했으면, CLI는 자동으로 delta 업데이트를 활성화할지 여부를 묻습니다. Delta 업데이트는 버전 사이에 변경된 파일만 전송하는 반면 전체 배포본을 전송하는 것입니다. 일반적으로 업데이트 사이에 변경된 파일은 몇 개뿐이므로, 다운로드 속도가 훨씬 빠릅니다. 선택 Yes 즉시 업데이트 경험의 최적화를 위해.

직접 업데이트 활성화 시 delta 업데이트스 요청:

💡 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 업데이터 플러그인이 설치 및 설정되었습니다.

✅ Code 통합 완료

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

✅ 업데이트 테스트 완료

업데이트를 성공적으로 배포하고 라이브 업데이트 수신했습니다.

일일 워크플로우

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

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?

팁

온보딩 프로세스의 진행 상황은 로컬에 저장되므로 안전하게 중단하고 다시 시작할 수 있습니다.

문제 해결

개발 환경이 없습니다

문제: SDK이 iOS 또는 Android에서 발견되지 않습니다.

해결:

• iOS용 경우: 설치 Xcode (macOS 전용)
• Android용 경우: 설치 Android Studio

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

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

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

빌드 스크립트가 없습니다.

문제: __CAPGO_KEEP_0__에 빌드 스크립트가 없습니다. 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으로 업그레이드

다음 단계

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

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

Learn how to deploy updates from the Capgo dashboard

업데이트 유형

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

CI/CD 통합

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

채널

다중 업데이트 스트림을 관리하는 채널

암호화

업데이트를 암호화하여 종단 간 암호화 보안을 제공하세요.

업데이트 동작

업데이트가 적용되는 시점과 방법을 커스터마이즈하세요 (직접, 델타 등)

도움말

도움말

• 확인하세요 문제 해결 가이드
• 디스코드 커뮤니티에 가입하세요 FAQ를 검토하세요
• 지원팀에 연락하세요 페이지 편집
• 이전 개요