페이지 복사 옵션

이 플러그인의 설치 단계와 전체 마크다운 가이드를 포함한 설정 프롬프트를 복사합니다.

이 가이드는 사용자의 네이티브 앱 버전에 따라 최신 호환 가능한 번들을 자동으로 제공하는 방법을 설명합니다. 이것은 Ionic AppFlow의 접근 방식과 유사합니다.이것은 단순화된 업데이트 관리 및 빠른 롤아웃을 제공하며 호환성 문제를 방지합니다.

Overview

Capgo의 버전 대상 시스템은 다음과 같은 기능을 제공합니다.

자동으로 사용자에게 호환 가능한 업데이트를 제공합니다. 사용자의 네이티브 앱 버전에 따라 호환 가능한 업데이트를 제공합니다.
인종 불일치 앱 버전에 도달하는 깨진 변경 사항을 방지합니다. 다중 앱 버전 관리
__CAPGO_KEEP_0__'s version targeting system allows you to: 복잡한 논리를 사용하지 않고 동시에
업데이트를 원활하게 배포하세요 특정 사용자 그룹에게

버전 대상 설정의 중요성 (AppFlow 사용자에게 특히)

버전 대상 설정에 익숙한 경우 Ionic AppFlow, 사용자에게만 호환 가능한 업데이트만 제공할 수 있도록 보장하는 것이 중요하다는 것을 아실 것입니다. AppFlow는 라이브 업데이트 번들을 네이티브 앱 버전과 자동으로 매칭하여, 호환되지 않는 자바스크립트가 더 오래된 네이티브 code에 전달되는 것을 방지했습니다.

Capgo는 동일한 안전 보장 기능을 제공합니다, 추가 기능도 제공합니다:

버전 매칭에 더 세밀한 제어
다중 전략 (채널, semver, 네이티브 제약 조건)
버전 분포에 대한 더 나은 시각
API과 CLI은 대시보드 관리와 함께 제어합니다.

이 접근 방식은 특히 유용합니다.

사용자가 앱의 다른 주요 버전 (예: v1.x, v2.x, v3.x)에 있습니다.
브레이킹 변경을 출시하는 동안 뒤로compatibility를 유지해야 하는 경우
새로운 번들을 사용하여 더 오래된 네이티브 code를 깨뜨리지 않도록 원치 않는 경우
사용자를 하나의 버전에서 다른 버전으로 점진적으로 마이그레이션하는 경우
AppFlow에서 마이그레이션하고자 하는 경우 업데이트 안전성을 유지하고 싶은 경우

How It Works

Capgo은 사용자와 호환 가능한 업데이트를 매치하기 위해 다중 층 구조를 사용합니다.

원본 버전 제한: 불일치한 원본 버전의 네이티브 버전으로 배달되는 것을 방지합니다
채널 기반 라우팅: 앱 버전을 다르게 업데이트하는 채널로 라우팅합니다
Semantic 버전 제어: 메이저/마이너/패치 경계를 넘어 업데이트를 자동으로 차단합니다
기기 기반 오버라이드: 특정 기기 또는 사용자 그룹을 대상으로 합니다

버전 일치 흐름

graph TD
    A[User Opens App] --> B{Check Device Override}
    B -->|Override Set| C[Use Override Channel]
    B -->|No Override| D{Check defaultChannel in App}
    D -->|Has defaultChannel| E[Use App's defaultChannel]
    D -->|No defaultChannel| F[Use Cloud Default Channel]
    C --> G{Check Version Constraints}
    E --> G
    F --> G
    G -->|Compatible| H[Deliver Update]
    G -->|Incompatible| I[Skip Update]

전략 1: 채널 기반 버전 라우팅

이것은 권장하는 방법 파괴적인 변경 사항과 주요 버전 업데이트를 관리하는 데 사용되는

AppFlow의 전달 모델과 유사합니다.

Section titled “예시 시나리오” App v1.x production (100,000 명의 사용자) →
채널 App v2.x v2 (50,000 명의 사용자와 파괴적인 변경 사항) →
App v3.x (10,000 beta 사용자) → v3 채널

구현

1단계: 각 주요 버전의 채널을 구성하십시오.

// capacitor.config.ts for version 1.x builds
import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example App',
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      defaultChannel: 'production', // or omit for default
    }
  }
};

export default config;

// capacitor.config.ts for version 2.x builds
const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example App',
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      defaultChannel: 'v2', // Routes v2 users automatically
    }
  }
};

// capacitor.config.ts for version 3.x builds
const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example App',
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      defaultChannel: 'v3', // Routes v3 users automatically
    }
  }
};

2단계: 채널 생성하십시오.

# Create channels for each major version
npx @capgo/cli channel create production
npx @capgo/cli channel create v2
npx @capgo/cli channel create v3

# Enable self-assignment so apps can switch channels
npx @capgo/cli channel set production --self-assign
npx @capgo/cli channel set v2 --self-assign
npx @capgo/cli channel set v3 --self-assign

3단계: 버전별 패키지 업로드

# For v1.x users (from v1-maintenance branch)
git checkout v1-maintenance
npm run build
npx @capgo/cli bundle upload --channel production

# For v2.x users (from v2-maintenance or main branch)
git checkout main
npm run build
npx @capgo/cli bundle upload --channel v2

# For v3.x users (from beta/v3 branch)
git checkout beta
npm run build
npx @capgo/cli bundle upload --channel v3

장점

Zero code 변경 - 채널 라우팅이 자동으로 발생합니다.
분명한 구분 - 각 버전에는 자신의 업데이트 PIPELINE이 있습니다.
가변적인 목표 - 특정 버전 그룹으로 업데이트를 푸시합니다.
안전한 롤아웃 - 불일치 버전에 도달하는 변경 사항은 없습니다.

Strategy 2: 의미 있는 버전 제어

Capgo의 내장 의미 있는 버전 제어가 버전 경계를 넘지 않는 업데이트를 방지하는 데 사용됩니다.

__CAPGO_KEEP_0__의 주요 버전을 넘어 업데이트를 비활성화합니다.

# Create a channel that blocks major version updates
npx @capgo/cli channel create stable --disable-auto-update major

이 설정은 다음과 같습니다.

앱 버전의 사용자 1.2.3 __CAPGO_KEEP_0__까지의 업데이트를 받습니다. 1.9.9
사용자는 NOT 버전 2.0.0 자동으로
이전의 네이티브 code에서 깨지는 변경 사항을 막습니다.

세부 조정 옵션

# Block minor version updates (1.2.x won't get 1.3.0)
npx @capgo/cli channel set stable --disable-auto-update minor

# Block patch updates (1.2.3 won't get 1.2.4)
npx @capgo/cli channel set stable --disable-auto-update patch

# Allow all updates
npx @capgo/cli channel set stable --disable-auto-update none

Bundle에 대한 최소 네이티브 버전 요구 사항을 지정하여 불일치하는 장치로 배포를 방지합니다.

Semantic Versioning Required

When uploading a bundle, you can specify a minimum native version:

# This bundle requires native version 2.0.0 or higher
npx @capgo/cli bundle upload \
  --channel production \
  --native-version "2.0.0"

Use Cases

New Native Plugin Required

# Bundle needs Camera plugin added in v2.0.0
npx @capgo/cli bundle upload --native-version "2.0.0"

네이티브 API 변경 사항

# Bundle uses new Capacitor 6 APIs
npx @capgo/cli bundle upload --native-version "3.0.0"

점진적인 마이그레이션

# Test bundle only on latest native version
npx @capgo/cli bundle upload \
  --channel beta \
  --native-version "2.5.0"

전략 4: 자동 다운그레이드 방지

사용자가 현재 네이티브 버전보다 이전 버전의 패키지를 받는 것을 방지합니다.

채널 설정에서 활성화

In the Capgo dashboard:

__CAPGO_KEEP_0__ 대시보드로 이동 채널 → 채널을 선택하세요
활성화 “네이티브 하위 버전의 자동 다운그레이드를 비활성화하세요”
변경 사항 저장

또는 CLI:를 통해

npx @capgo/cli channel set production --disable-downgrade

예시

사용자의 기기: 네이티브 버전 1.2.5
채널 번들: 버전 1.2.3
결과: 업데이트가 차단되었습니다 (다운그레이드가 될 것입니다)

다음과 같은 경우 유용합니다:

사용자가 앱 스토어에서 최신 버전을 수동으로 설치했습니다
사용자가 항상 최신 보안 패치를 보장받기를 원할 때
회귀 버그를 방지하기 위해

전략 5: 기기 수준 타겟팅

특정 버전을 테스트하기 위해 강제로 버전을 지정합니다.

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

// Force beta testers to use v3 channel
async function assignBetaTesters() {
  const deviceId = await CapacitorUpdater.getDeviceId()

  // Check if user is beta tester
  if (isBetaTester(userId)) {
    await CapacitorUpdater.setChannel({ channel: 'v3' })
  }
}

대시보드 장치 우선순위

Capgo 대시보드에서:

바로 가기 장치 → 장치 찾기
클릭 채널 설정 또는 버전 설정
특정 채널 또는 패키지 버전으로 우선순위 설정
장치가 overridden 원천에서 업데이트를 받습니다

완전한 AppFlow-Style 워크플로우

전체 전략을 combining하는 완전한 예제입니다.

1. 초기 설정 (App v1.0.0)

# Create production channel with semver controls
npx @capgo/cli channel create production \
  --disable-auto-update major \
  --disable-downgrade

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      defaultChannel: 'production',
    }
  }
};

2. App v2.0.0에서 발생하는 Breaking Change

# Create v2 channel for new version
npx @capgo/cli channel create v2 \
  --disable-auto-update major \
  --disable-downgrade \
  --self-assign

# Create git branch for v1 maintenance
git checkout -b v1-maintenance
git push origin v1-maintenance

// capacitor.config.ts for v2.0.0
const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      defaultChannel: 'v2', // New users get v2 channel
    }
  }
};

3. 두 버전 모두에 업데이트를 푸시하라

# Update v1.x users (bug fix)
git checkout v1-maintenance
# Make changes
npx @capgo/cli bundle upload \
  --channel production \
  --native-version "1.0.0"

# Update v2.x users (new feature)
git checkout main
# Make changes
npx @capgo/cli bundle upload \
  --channel v2 \
  --native-version "2.0.0"

4. 버전 분포를 모니터링하라

Capgo 대시보드를 사용하여 다음을 추적하라:

How many users are on v1 vs v2
버전 v1과 v2의 사용자 수
버전별 Bundle 사용률

버전별 오류 또는 충돌 횟수

버전 v1 사용률이 임계값 이하로 떨어질 때:

# Stop uploading to production channel
# Optional: Delete v1 maintenance branch
git branch -d v1-maintenance

# Move all remaining users to default
# (They'll need to update via app store)

채널 우선순위

여러 채널 설정이 존재할 때, Capgo은 다음의 우선순위를 사용합니다:

장치 오버라이드 (대시보드 또는 API) - 가장 높은 우선순위
클라우드 오버라이드 via setChannel() 호출
기본 채널 capacitor.config.ts에서
기본 채널 (클라우드 설정) - 가장 낮은 우선순위

최선의 방법

1. 메인 버전의 경우 defaultChannel을 항상 설정하세요.

// ✅ Good: Each major version has explicit channel
// v1.x → production
// v2.x → v2
// v3.x → v3

// ❌ Bad: Relying on dynamic channel switching
// All versions → production, switch manually

2. 의미론적 버전 관리를 사용하세요.

# ✅ Good
1.0.0 → 1.0.1 → 1.1.0 → 2.0.0

# ❌ Bad
1.0 → 1.1 → 2 → 2.5

3. 별도의 branch를 유지하세요.

# ✅ Good: Separate branches per major version
main (v3.x)
v2-maintenance (v2.x)
v1-maintenance (v1.x)

# ❌ Bad: Single branch for all versions

4. 배포 전 테스트

# Test on beta channel first
npx @capgo/cli bundle upload --channel beta

# Monitor for issues, then promote to production
npx @capgo/cli bundle upload --channel production

5. 버전 분포 모니터링

정기적으로 대시보드를 확인하세요:

사용자가 최신 네이티브 버전으로 업그레이드하고 있는지 확인하세요.
고래 버전이 여전히 높은 트래픽을 받고 있는지 확인하세요.
누구에게도 폐지할 필요가 있는 이전 채널이 있나요?

아이오닉 앱 플로우와의 비교

아이오닉 앱 플로우에서 팀이 이주하는 경우 아이오닉 앱 플로우, Capgo의 버전 대상 설정과 비교:

기능	아이오닉 앱 플로우	Capgo
버전 기반 라우팅	자연스럽게 native 버전에 따라 자동	자연스럽게 native 버전에 따라 자동 `defaultChannel` + 여러 전략
의미 버전 관리	기본 지원	고급에 `--disable-auto-update` (주/부/정)
자연어 버전 제약	AppFlow 대시보드에서 수동 설정	내장 `--native-version` CLI
채널 관리	웹 UI + CLI	웹 UI + CLI + API
기기 오버라이드	기기 수준 제한된 제어	대시보드(API)를 통해 완전한 제어
다운그레이드 예방	예	__CAPGO_KEEP_0__를 통해 `--disable-downgrade`
다중 버전 유지	수동 브랜치/채널 관리	채널 우선 순위로 자동화
자체 호스팅	아니오	예 (완전한 제어)
버전 분석	기본	버전별 세부 메트릭

‘문제 해결’ 섹션

‘사용자가 업데이트를 받지 못하는 경우’ 섹션

다음 사항을 확인하세요:

채널 assignments: 장치가 올바른 채널에 연결되어 있는지 확인하세요

const channel = await CapacitorUpdater.getChannel()
console.log('Current channel:', channel)

버전 제한: 번들의 네이티브 버전 요구 사항이 있는지 확인하세요
- 대시보드 → 번들 → '네이티브 버전' 열거를 확인하세요
Semver 설정: 채널의 disable-auto-update 설정
터미널 창
```
npx @capgo/cli channel list
```
장치 우선순위: 장치가 수동 우선순위를 가지고 있는지 확인합니다.
- 대시보드 → 장치 → 장치 검색 → 채널/버전 확인

잘못된 버전으로 패키지 전달

기본 채널 확인: 올바른 채널이 설정되어 있는지 확인합니다. capacitor.config.ts
패키지 업로드 확인: 올바르게 업로드 된 패키지를 확인합니다.
네이티브 버전 확인: 올바르게 사용되었는지 확인합니다. --native-version 네이티브 버전 확인 플래그 사용 여부

기존 버전에 영향을 미치는 변경 사항

즉시 수정: 영향을 받은 기기들을 안전한 번들로 설정합니다.
- 대시보드 → 기기 → bulk 선택 → 버전 설정
장기적인 수정: 버전별 채널을 생성하고 별도의 branch를 유지합니다.
예방: 업데이트를 롤아웃하기 전에 대표적인 기기에서 테스트를 항상 합니다.

Ionic AppFlow에서 마이그레이션

Capgo로 마이그레이션하는 경우 Ionic AppFlow버전 Capgo에서 Capgo 버전을 대상으로 하는 기능은 Capgo에서 Capgo의 유연성을 향상된 형태로 작동합니다.

개념 매핑

AppFlow 개념	Capgo 개념	메모
배포 채널	Capgo 채널	같은 개념, 더 강력한 기능
네이티브 버전 잠금	`--native-version` __CAPGO_KEEP_0__	__CAPGO_KEEP_0__
채널 우선순위	채널 우선순위 (override → 클라우드 → 기본)	더 투명한 우선순위
배포 대상	채널 + semver 제어	여러 전략이 사용 가능합니다.
프로덕션 채널	`production` 채널 (또는任意 이름)	flexible 이름
Git 기반 배포	CLI branch에서 채널 업로드	동일한 워크플로우
자동 버전 일치	`defaultChannel` + 버전 제약	다중 전략을 지원하는 강화

AppFlow 사용자용 주요 차이점

더욱 많은 제어: Capgo은 여러 전략 (채널, semver, 네이티브 버전)이 결합될 수 있는 여러 전략을 제공합니다.
더 나은 시야: 버전 분포 및 호환성 문제를 보여주는 대시보드
API Access: 프로그램적 제어를 통해 버전 목표에 대한 전체 제어
자체 호스팅: 자체 업데이트 서버를 실행하는 옵션과 동일한 버전 로직

이동 단계

AppFlow 채널을 __CAPGO_KEEP_0__ 채널로 맵핑하세요 (일반적으로 1:1) to Capgo channels (usually 1:1)
에서 defaultChannel 각 주요 버전 capacitor.config.ts semver 규칙을 구성
자동으로 버전 경계에서 차단하고 싶다면 버전별로 업로드 된 패키지
버전별로 업로드 된 패키지 __CAPGO_KEEP_0__ 사용을 위해 --native-version __CAPGO_KEEP_0__ 플래그
버전 분포를 모니터링하는 버전 Capgo 대시보드에서

고급 패턴

버전별 점진적인 롤아웃

// Gradually migrate v1 users to v2
async function migrateUsers() {
  const deviceId = await CapacitorUpdater.getDeviceId()
  const rolloutPercentage = 10 // Start with 10%

  // Hash device ID to get deterministic percentage
  const hash = hashCode(deviceId) % 100

  if (hash < rolloutPercentage) {
    // User is in rollout group - migrate to v2
    await CapacitorUpdater.setChannel({ channel: 'v2' })
  }
}

버전별 특징 플래그

// Enable features based on native version
async function checkFeatureAvailability() {
  const info = await CapacitorUpdater.getDeviceId()
  const nativeVersion = info.nativeVersion

  if (compareVersions(nativeVersion, '2.0.0') >= 0) {
    // Enable features requiring v2.0.0+
    enableNewCameraFeature()
  }
}

버전별 테스트

// Run A/B tests within same native version
async function assignABTest() {
  const nativeVersion = await getNativeVersion()

  if (nativeVersion.startsWith('2.')) {
    // Only A/B test on v2 users
    const variant = Math.random() < 0.5 ? 'v2-test-a' : 'v2-test-b'
    await CapacitorUpdater.setChannel({ channel: variant })
  }
}

총 요약

Capgo는 여러 가지 버전별 업데이트 전달 전략을 제공합니다.

채널 기반 라우팅__CAPGO_KEEP_0__: 버전을 자동으로 분리합니다. defaultChannel
Semantic Versioning: 업데이트가 메이저/마이너/패치 버전 경계를 넘어서지 않도록 방지합니다.
Native Version Constraints: 번들에 대한 최소 네이티브 버전을 요구합니다.
Auto-Downgrade Prevention: 새로운 네이티브 버전으로 업그레이드된 후에 이전 버전의 번들을 전달하지 않도록 방지합니다.
Device Overrides: 테스트 및 대상 설정을 위해 수동 제어

이러한 전략을结合하면 AppFlow-style 자동 업데이트 전달과 더 많은 유연성과 제어가 가능합니다. 앱의 버전 관리 및 배포 워크플로에 가장 적합한 방법을 선택하세요.

자세한 정보는 특정 기능에 대한 문서를 참조하세요:

Breaking Changes Guide - 세부적인 채널 버전 관리 전략
채널 관리 - 채널 구성 참조
업데이트 동작 - 네이티브 버전 지연 및 조건