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_1__ @capgo/capacitor-updater __CAPGO_KEEP_1__
code
선택적으로 종단-to-종단 암호화를 활성화하세요
테스트 플랫폼을 선택하세요 (iOS 또는 Android)

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

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

완료 (13 단계):

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

13 단계 온보딩 프로세스

1 단계: 사전 조건 확인

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

확인하는 항목:

Xcode (macOS only) - 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"

이미지

이미지를 선택한 경우: capacitor.config.ts 동적으로 채널을 설정하기 위해 JavaScript
메소드를 사용하십시오. setChannel() __CAPGO_KEEP_0__ 웹 콘솔에서 나중에 채널을 구성하십시오.
Configure channels later from the Capgo web console

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

The CLI will install the @capgo/capacitor-updater Capacitor 버전과 호환되는 플러그인입니다.

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

버전 호환성:

Capacitor 5: __CAPGO_KEEP_0__ v5 설치 @capgo/capacitor-updater v5
Capacitor 6: __CAPGO_KEEP_0__ v6 설치 @capgo/capacitor-updater v6
Capacitor 7: __CAPGO_KEEP_0__ 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

Yes를 선택하면:

앱이 백그라운드에 있을 때 재개되면 업데이트가 즉시 적용되며, 업데이트가 재개될 때 업데이트가 자동으로 적용됩니다.
autoUpdate: 'always' 그리고 autoSplashscreen: true config에 추가됩니다.
Your capacitor.config.ts 자동으로 업데이트됩니다.
델타 업데이트 자동으로 활성화됩니다 - 업데이트가 이루어질 때 변경된 파일만 전송되기 때문에 업데이트가 훨씬 빠릅니다.

No를 선택하면:

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

Step 5: Add Integration 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
기타 프레임워크: 메인 진입 파일에 추가

If auto-injection fails, you can add the code manually to your main application file:

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 추가 가이드의 App 추가 가이드의 6단계: 암호화 설정(선택사항).

6단계: 암호화 설정(선택사항) 섹션입니다.

__CAPGO_KEEP_0__의 업데이트에 대한 끝에서 끝까지 암호화는 추가 보안層을 제공합니다.

🔐 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가 다음을 수행합니다.

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

Step 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

Step 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

자동 모드: 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 업데이트가 즉시 적용 모드가 활성화된 경우 (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

For instant updates:

🔄 IMPORTANT: Background your app (swipe up/press home button) and then reopen it
⏱️  The update should be downloaded and applied automatically

For standard updates:

📱 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 logs:

❓ Monitor Capgo logs to verify the update worked?

If you select __CAPGO_KEEP_1__, you’ll see live logs from your device showing the update process.

you’ll see live logs from your device showing the update process.

Welcome onboard ✈️!

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

성공했습니다!

__CAPGO_KEEP_0__에 앱을 등록하고 프로덕션 채널을 설정했습니다.

__CAPGO_KEEP_0__ 업데이터 플러그인을 설치 및 설정했습니다.

Capgo 통합을 앱에 추가했습니다.

__CAPGO_KEEP_0__ 업데이트를 성공적으로 배포 및 수신했습니다.

Capacitor에 등록된 앱

Code에 앱을 등록하고 프로덕션 채널을 설정했습니다.

code 업데이터 플러그인을 설치 및 설정했습니다.

__CAPGO_KEEP_0__ 통합을 앱에 추가했습니다.

__CAPGO_KEEP_0__ 업데이트를 성공적으로 배포 및 수신했습니다.

일상 작업 흐름

다음 업데이트를 위해 사용하십시오.

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

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

온보딩 다시 시작

온보딩 프로세스를 종료한 경우 언제든 다시 시작하실 수 있습니다.

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용: 설치 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 이상으로 업그레이드하세요:

다음 단계

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

업데이트 배포

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

업데이트 유형

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

CI/CD 통합

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

채널

다중 업데이트 스트림을 관리하세요.

암호화

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

__CAPGO_KEEP_1__

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

__CAPGO_KEEP_3__

__CAPGO_KEEP_5__

__CAPGO_KEEP_6__ __CAPGO_KEEP_7__
__CAPGO_KEEP_8__ __CAPGO_KEEP_9__
__CAPGO_KEEP_10__ __CAPGO_KEEP_11__
__CAPGO_KEEP_0__ __CAPGO_KEEP_0__

CLI

__CAPGO_KEEP_0__ CLI API API API __CAPGO_KEEP_0__ __CAPGO_KEEP_0__ API 구현 세부 정보에 대한 API 키에 대해 기기 구현 세부 정보에 대한 기기, 및 구현 세부 정보에 대한 번들 페이지 편집