CLI 온보딩 가이드

이 플러그인에 대한 설치 단계와 전체 마크다운 가이드를 포함한 설정 프롬프트를 복사하십시오.

빠른 개요

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

✅ Capgo에 앱을 등록합니다.
🔌 업데이트러 플러그인을 설치하고 구성합니다.
🚀 첫 번째 실시간 업데이트를 배포합니다.
📱 __CAPGO_KEEP_0__ 기기에서 업데이트 테스트해 보세요

추정 시간: 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 __CAPGO_KEEP_0__을 앱에 주입하세요
Inject the required code into your app
테스트를 위한 플랫폼을 선택하세요 (iOS 또는 Android)
__CAPGO_KEEP_0__

테스트 단계 (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

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

⚠️ 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를 입력할 수 있습니다.

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

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

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 웹 콘솔에서 채널을 나중에 구성

Step 4: Updater 플러그인 설치

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

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

버전 호환성:

Capacitor 5: v5를 설치합니다. @capgo/capacitor-updater v5
Capacitor 6: v6를 설치합니다. @capgo/capacitor-updater v6
Capacitor 7: v7를 설치합니다. @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

If you select Yes:

업데이트는 앱이 백그라운드 상태일 때 재개동 시 즉시 적용됩니다.
autoUpdate: 'always' 그리고 autoSplashscreen: true 설정에 추가됩니다.
Your capacitor.config.ts 자동으로 업데이트됩니다.
델타 업데이트 자동으로 활성화됩니다 - 이 방법은 업데이트된 파일만 전송하여 전체 배포물 대신 변경된 파일만 전송하여 업데이트가 훨씬 빠릅니다.

If you select No:

업데이트는 표준 동작을 사용합니다 (배경에서 다운로드, 다음 재시작 시 적용)
업데이트를 즉시 활성화할 수 있습니다. 항상 수정하여 capacitor.config.ts

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

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

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

CapacitorUpdater.notifyAppReady()

code은 임포트 후 앱 초기화 전에 위치해야 합니다. 자세한 내용은 앱 추가하기 지침서 Step 6: 암호화 설정(선택).

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

__CAPGO_KEEP_0__ 키를 생성합니다.
Capacitor 구성이 동기화되도록 제안합니다.

Step 7: 플랫폼 선택

Choose which platform to test with during onboarding.

📱 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.

Step 9: 기기에서 실행

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

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

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

업데이트 시스템을 테스트하기 위해 __CAPGO_KEEP_0__의 변경을 확인하세요.

Now it’s time to test Capgo’s update system by making a visible change.

🎯 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단계: 패키지 업로드

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

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

CLI이 실행 중입니다:

npx @capgo/cli@latest bundle upload

Delta updates prompt (if an instant apply mode is enabled):

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

Yes를 선택하면 당신의 장치에서 업데이트 프로세스를 실시간으로 보여주는 로그가 표시됩니다.13단계: 완료

제목이 '13단계: 완료'인 섹션

Welcome onboard ✈️!

Capgo 라이브 업데이트 설정이 성공적으로 완료되었습니다.

성공적으로 완료한 것

온보딩을 완료한 후에, 다음을 완료했습니다.

✅ 앱 등록

Capgo에 앱이 등록되었습니다. (생산 채널)

✅ 플러그인 설치

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

✅ Code 통합

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

✅ 업데이트 테스트

__CAPGO_KEEP_0__

일상 작업 흐름

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

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

다른 배포 옵션을 보려면 실시간 업데이트 배포.

온보딩 다시 시작

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

npx @capgo/cli@latest init [APIKEY]

__CAPGO_KEEP_1__

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

__CAPGO_KEEP_6__

__CAPGO_KEEP_8__

__CAPGO_KEEP_10__ Neither Xcode nor Android SDK is detected.

해결:

iOS용: 설치 Xcode (macOS만)
Android용: 설치 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 이상으로 업그레이드하세요.

다음 단계

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

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

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

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

Learn how to deploy updates from the Capgo dashboard

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

CI/CD 통합

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

protectedTokens

채널

다중 업데이트 스트림을 관리하는 채널을 사용하세요

암호화

업데이트를 암호화하여 안전하게 유지하세요

업데이트 동작

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

도움말

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

Check the 문제 해결 가이드
참여하세요 디스코드 커뮤니티
리뷰를 확인하세요 FAQ
연락처 지원

CLI 온보딩 가이드에서 계속

__CAPGO_KEEP_0__ 온보딩 가이드를 사용하여 대시보드와 __CAPGO_KEEP_0__ 운영을 계획하고 있다면, __CAPGO_KEEP_0__ 온보딩 가이드를 __CAPGO_KEEP_0__ 개요와 연결하세요. CLI 온보딩 가이드를 사용하여 대시보드와 CLI 운영을 계획하고 있다면, CLI 개요를 연결하세요. API 온보딩 가이드를 사용하여 대시보드와 API 운영을 계획하고 있다면, API 개요를 연결하세요. API 온보딩 가이드를 사용하여 대시보드와 API 운영을 계획하고 있다면, API 개요를 연결하세요. API 온보딩 가이드를 사용하여 대시보드와 API 운영을 계획하고 있다면, API 개요를 연결하세요. __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ 구현 세부 정보에 대한 API 키 for the implementation detail in API Keys, 장치 구현 세부 정보에 대한 장치 번들 구현 세부 정보에 대한 번들