CLI 온보딩 가이드

이 플러그인을 설치하는 방법과 전체 마크다운 가이드를 포함한 설치 명령어를 복사합니다.

빠른 개요

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

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

예상 시간: 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__
Inject the required code into your app
선택적으로 종단 간 암호화 활성화
테스트를 위한 플랫폼을 선택하세요 (iOS 또는 Android)

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

앱을 빌드하고 디바이스/에뮬레이터에서 실행하세요
code에서 업데이트된 번들을 업로드하세요
Capgo에서 실시간으로 디바이스에서 업데이트를 확인하세요
완료 (13 단계):

앱이 실시간 업데이트를 위한 준비가 완료되었습니다! 🎉

13 단계 온보딩 프로세스

13 단계 온보딩 프로세스 섹션

13 단계 온보딩 프로세스

The CLI checks your development environment to ensure you have the necessary tools installed.

확인되는 항목:

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

질문에 답할 수 있는 질문들:

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

3단계: 프로덕션 채널 만들기

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

❓ Create default channel production for {appId} in Capgo?

If you select Yes:

(spinner) Running: npm @capgo/cli@latest channel add production {appId} --default
Channel add Done ✅  (or "Channel already added ✅")

A production __CAPGO_KEEP_0__ will be created and set as default. This is the recommended option for most users.

If you select No:

If you change your mind, run it for yourself with: "npm @capgo/cli@latest channel add production {appId} --default"

You’ll need to create and configure __CAPGO_KEEP_0__s manually later. Alternatively, you can:

Set the __CAPGO_KEEP_0__ in your capacitor.config.ts file
Use the JavaScript setChannel() method to dynamically set the __CAPGO_KEEP_0__
Configure Capgos later from the Capgo web console

Step 4: Updater Plugin 설치

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

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

호환성:

Capacitor 5: Capgo 5 버전을 설치합니다. @capgo/capacitor-updater __CAPGO_KEEP_0__ 6
Capacitor 6Copy to clipboard @capgo/capacitor-updater Version compatibility:
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 config에 추가됩니다.
Your capacitor.config.ts 자동으로 업데이트됩니다.
Delta updates 자동으로 활성화되며, 이 기능은 업데이트 중 변경된 파일만 전송하여 전체 패키지보다 업데이트가 훨씬 빠릅니다.

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를 당신의 임포트 후에 앱 초기화 전에 넣어주세요. 더 많은 정보를 위해서는 애플리케이션 추가 안내서.

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가:

암호화 키를 생성합니다.
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단계: 프로젝트 빌드

The CLI will build your app and sync it with 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단계: 테스트 변경

이제 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

자동 모드: 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

델타 업데이트 알림 (즉시 적용 모드가 활성화된 경우):

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

만약에 네, 당신은 실제로 장치에서 업데이트 프로세스를 보여주는 로그를 볼 수 있습니다.

13단계: 완료

Welcome onboard ✈️!

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

이제 무엇을 했는지

온보딩을 완료한 후에:

✅ 앱 등록

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?

문제 해결

개발 환경이 없습니다

문제: 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 대시보드에서 업데이트 배포 방법을 학습하세요

업데이트 유형

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

CI/CD 통합

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

채널

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

암호화

업데이트를 암호화하여 보안하세요

업데이트 동작

업데이트를 언제, 어떻게 적용할지 직접, 델타 등으로 커스터마이즈하세요

도움말

체크해 보세요

체크해 보세요 문제 해결 가이드
Capgo 커뮤니티에 가입하세요 디스코드 커뮤니티
리뷰 FAQ
문의 지원

CLI 온보딩 가이드에서 계속

__CAPGO_KEEP_0__ 온보딩 가이드를 사용하여 대시보드와 __CAPGO_KEEP_0__ 운영을 계획하고 있다면 CLI 온보딩 가이드와 연결하세요 API 온보딩 가이드와 연결하세요 API 개요 API 구현 세부 정보를 위한 소개 소개 구현 세부 정보를 위한 API 키 API 키 구현 세부 정보를 위한 장치 장치 구현 세부 정보를 위한, 패키지 패키지 구현 세부 정보를 위한.