CLI 온보딩 가이드

빠른 개요

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

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

예상 시간: __CAPGO_KEEP_0__의 인터넷 속도와 빌드 시간에 따라 10-20분 (변동 가능)

Tip

__CAPGO_KEEP_0__는 완전히 재개할 수 있는 온보딩을 제공합니다. 언제든지 종료하고 나중에 중단한 곳에서 계속 진행할 수 있습니다.

온보딩 시작

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

npx @capgo/cli@latest init [APIKEY]

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

Capgo onboarding 🛫

온보딩 과정

CLI는 13개의 인터랙티브 스텝을 통해 온보딩을 안내해드립니다.

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

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

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

• 앱을 빌드하고 기기/에뮬레이터에서 실행하세요.
• code에 대한 가시적인 변경을 만들세요 (자동 또는 수동).
• Capgo에 업데이트된 번들을 업로드하세요.
• 실시간으로 장치에 나타나는 라이브 업데이트를 보세요.

Completion (Step 13):

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

13단계 온보딩 프로세스

1단계: 사전 조건 확인

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

확인 대상:

• Xcode (macOS 전용) - iOS 개발을 위한
• Android SDK - 안드로이드 개발을 위해

가능한 결과:

✅ 두 환경 모두 발견됨:

✅ 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

질문에 답할 수 있는 질문:

주의

개발 환경이 발견되지 않으면, 개발 환경을 설치할 것을 묻습니다. 적어도 하나의 플랫폼을 설치한 후 진행하는 것을 추천합니다.

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

Step 3: Production 채널 만들기

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

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

이러한 채널을 생성하고 구성하려면 나중에 수동으로 진행해야 합니다. alternatively,

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

Step 4: Updater Plugin 설치

The CLI will install the @capgo/capacitor-updater plugin compatible with your Capacitor version.

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

버전 호환성:

• Capacitor 5: __CAPGO_KEEP_0__을 설치합니다. @capgo/capacitor-updater v5
• 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 이내에 작동하기 때문입니다. 그렇지 않다면 (표준 모드), 업데이트는 배경에서 다운로드되고 다음 앱 재시작 시 적용됩니다. 즉시 업데이트 옵션은 개발 시 빠른 반복 및 프로덕션 시 крит적 버그 수정에 적합합니다.

YES를 선택하면:

• 업데이트는 앱이 배경화면 상태와 재개시 될 때 즉시 적용됩니다.
• directUpdate: 'always' 그리고 autoSplashscreen: true 설정에 추가될 것입니다
• 당신의 capacitor.config.ts 자동으로 업데이트될 것입니다
• 델타 업데이트 자동으로 활성화될 것입니다 - 이 방법은 업데이트할 때 변경된 파일만 전송하여 전체 배포보다 업데이트가 훨씬 빠릅니다

만약 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를 임포트 후 앱 초기화 전에 추가하세요. 자세한 내용은 App 가이드의 App 추가하기.

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

끝-to-끝 암호화는 업데이트에 추가 보안层를 제공합니다.

🔐 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를 활성화하면 CLI가:

1. __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

온보딩 과정만 영향을 받습니다. 최종 앱은 모든 플랫폼을 지원합니다.

7단계: 플랫폼 선택

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의 업데이트 시스템을 테스트하기 위해 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

자동 모드: The CLI will automatically modify your files to add a visible test banner or change.

수동 모드: 당신이 원하는 대로 변경 (예: 텍스트, 색상, 또는 요소를 추가)합니다.

버전 관리:

❓ 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단계: 번들 업로드

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

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

CLI가 실행됩니다.

npx @capgo/cli@latest bundle upload

팁

델타 업데이트와 직접 업데이트: 4단계에서 직접 업데이트 옵션을 활성화했다면 CLI는 자동으로 델타 업데이트를 활성화할지 여부를 묻습니다. 델타 업데이트는 버전 사이에 변경된 파일만 전송하여 전체 배포본을 다운로드하는 대신, 일반적으로 업데이트 사이에 변경된 파일이 몇 개뿐이므로 다운로드 속도가 훨씬 빠릅니다. 선택 Yes 직접 업데이트와 함께 최상의 경험을 위해.

델타 업데이트를 활성화할지 여부를 묻는 메시지 (직접 업데이트 활성화 시):

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

주의

__CAPGO_KEEP_0__의 경우, 추가 경로를 제공해야 할 수 있습니다. 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?

만약에 Yes, __CAPGO_KEEP_0__에서 장치의 라이브 로그를 보여주며 업데이트 프로세스를 볼 수 있습니다.

13 단계: 완료

Welcome onboard ✈️!

축하합니다! Capgo 라이브 업데이트 설정을 성공적으로 완료했습니다.

__CAPGO_KEEP_0__에 달성한 것들

온보딩을 완료한 후에는:

✅ 앱 등록

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?

Tip

온보딩 프로세스를 안전하게 종료하고 다시 시작할 수 있으므로 로컬로 진행 중인 진행 상황이 저장됩니다.

Troubleshooting

No Development Environment

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

해결 방법:

• iOS 경우: 설치 Xcode (macOS only)
• 안드로이드용: 설치 Android Studio

앱 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으로 업그레이드

다음 단계

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

업데이트 배포

Capgo에서 업데이트를 배포하는 방법을 배운다

업데이트 유형

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

CI/CD 통합

CI/CD를 통해 업데이트 배포를 자동화한다

채널

여러 업데이트 스트림을 관리하는 채널

암호화

업데이트를 암호화하여 종단 간 암호화한다

업데이트 동작

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

도움말

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

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