CLI 온보딩 가이드

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

빠른 개요

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

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

예상 시간: 10-20분 (인터넷 속도 및 빌드 시간에 따라 달라집니다.)

온보딩 시작

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

npx @capgo/cli@latest init [APIKEY]

欢迎 메시지를 볼 수 있습니다.

Capgo onboarding 🛫

온보딩 중 발생하는 일

CLI은 13개의 인터랙티브 단계를 통해 안내해드립니다:

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

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

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

앱을 빌드하고 디바이스/시뮬레이터에서 실행하세요.
code에 가시적인 변경을 적용하세요 (자동 또는 수동).
Capgo 업데이트된 번들을 업로드하세요.
실시간으로 장치에서 라이브 업데이트를 확인하세요.

완료 (13 단계):

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

13 단계 온보딩 프로세스

단계 1: 사전 조건 확인

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

확인 대상:

Xcode (macOS 전용) - iOS 개발을 위해
안드로이드 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를 입력할 수 있습니다.

Step 3: 프로덕션 채널 생성

__CAPGO_KEEP_0__을 통해 앱의 다양한 업데이트 스트림을 관리할 수 있습니다.

❓ 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() 메서드를 사용하여 채널을 동적으로 설정
나중에 Capgo 웹 콘솔에서 채널을 구성

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

CLI는 CLI 버전과 호환되는 @capgo/capacitor-updater plugin compatible with your Capacitor version.

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

즉시 업데이트 옵션:

설치 후, 다음 질문에 대해 묻습니다.

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

Yes를 선택하면:

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

만약 No를 선택한다면:

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

5단계: 통합 추가 Code

CLI는 자동으로 code이 필요한 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를 수동으로 메인 애플리케이션 파일에 추가할 수 있습니다.

For 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 후 앱 초기화 전에 넣으세요. 자세한 내용은 App 가이드를 참조하세요. 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?

CLI 암호화를 활성화하면 CLI가:

__CAPGO_KEEP_0__ 암호화 키를 생성합니다.
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"?

무엇이 일어나는가:

프로젝트 유형을 감지합니다
빌드 스크립트를 실행합니다
실행 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: 테스트 변경

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

__CAPGO_KEEP_0__는 자동으로 파일을 수정하여 가시적인 테스트 배너나 변경을 추가합니다. 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

델타 업데이트를 활성화할 것인지 묻는 메시지 (즉시 적용 모드를 활성화한 경우):

💡 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를 선택하면 Yes, you’ll see live logs from your device showing the update process.

13단계: 완료

Welcome onboard ✈️!

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

업데이트를 위해 무엇을 달성했습니까?

After completing the onboarding, you have:

✅ 앱 등록 완료

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?

Troubleshooting

No Development Environment

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

해결 방법:

iOS 경우: 설치 Xcode (macOS only)
안드로이드용: 설치 안드로이드 스튜디오

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

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

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

빌드 스크립트가 누락되었습니다

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

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

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

Auto-Injection Failed

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

해결 방법: code를 __CAPGO_KEEP_1__에 수동으로 추가하세요:

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

CapacitorUpdater.notifyAppReady()

Capacitor 버전이 너무旧합니다.

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

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

다음 단계

Now that you’ve completed onboarding, explore these topics:

업데이트 배포

Capgo에서 업데이트를 배포하는 방법을 배워보세요.

업데이트 유형

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

CI/CD 통합

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

채널

여러 업데이트 스트림을 관리하세요.

암호화

업데이트를 암호화하여 끝에서 끝까지 보안하세요.

업데이트 동작

업데이트가 적용되는 시점과 방법을 맞춤화하세요 (직접, 델타 등)

도움말 받기

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

체크하는 문제 해결 가이드
디스코드 커뮤니티에 가입하세요 FAQ를 검토하세요
지원팀에 연락하세요 지원 받기
지원 센터에 문의하세요 지원 센터에 문의하세요

CLI 온보딩 가이드에서 계속하세요

__CAPGO_KEEP_0__ 온보딩 가이드를 사용 중이라면 CLI 온보딩 가이드 API 온보딩 가이드를 사용하여 대시보드와 API 운영을 계획하고 싶다면 API 개요 API 개요에서 구현 세부 정보를 확인하세요 __CAPGO_KEEP_0__ 소개 __CAPGO_KEEP_0__ 소개에서 구현 세부 정보를 확인하세요 API 키 API 키에서 구현 세부 정보를 확인하세요 __CAPGO_KEEP_0__ 장치 장치에 대한 구현 세부 정보에서 번들 번들에 대한 구현 세부 정보에서