CLI 온보딩 가이드

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

빠른 개요

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

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

예상 시간: 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)
Copy to clipboard

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

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

완료 (13 단계):

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

13 단계 온보딩 프로세스

1 단계: 사전 조건 확인

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

What’s checked:

Xcode (macOS only) - iOS 개발을 위해
Android SDK - Android 개발을 위해

Possible outcomes:

✅ 두 환경 모두 발견:

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

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

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 웹 콘솔에서 채널을 구성합니다.

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

CLI을 설치합니다. @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 자동으로 업데이트됩니다.
Delta 업데이트 변경된 파일만 전송하여 전체 패키지를 다운로드하지 않아 업데이트가 훨씬 빠르게 진행됩니다.

No를 선택하면:

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

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

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

CapacitorUpdater.notifyAppReady()

code을 임포트 후 애플리케이션 초기화 전에 추가합니다. 자세한 내용은 Add an App 가이드를 참조하세요. 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가:

암호화 키를 생성합니다.
Capacitor 설정을 동기화할 것을 제안합니다.

Step 7: 플랫폼 선택

Section titled “Step 7: Select Platform”

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

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

다음과 같이 볼 수 있습니다:

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

다음 단계

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

한 번의 설정

CI, 채널 및 델타 업로드를 오랜 기간 동안 안정성을 위해 한 번에 구성하세요.

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

Learn how to deploy updates from the Capgo dashboard

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

CI/CD 통합

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

protectedTokens

채널

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

암호화

업데이트를 암호화하여 end-to-end 암호화

업데이트 동작

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

도움말

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

Check the 트러블 슈팅 가이드
Capgo 커뮤니티에 가입하세요 디스코드 커뮤니티
리뷰를 확인하세요 FAQ
연락처 지원

CLI 온보딩 가이드에서 계속

__CAPGO_KEEP_0__ 온보딩 가이드를 사용하여 CLI 온보딩 가이드를 사용하여 대시보드와 CLI 운영을 계획하고 있으시다면 API 온보딩 가이드와 연결하세요 API 개요 API 개요의 구현 세부 정보 소개 소개에서 구현 세부 정보를 위해 API 키 API 키에서 구현 세부 정보를 위해 장치 장치에서 구현 세부 정보를 위해 배포 구현 세부 정보를 위해 배포에서