버전 대상 설정

이 플러그인의 설치 단계와 전체 마크다운 가이드를 포함한 설정 명령어를 복사하세요.

이 가이드는 사용자의 네이티브 앱 버전에 따라 최신 호환 가능한 번들을 자동으로 제공하는 방법을 설명합니다. Ionic AppFlow의 접근 방식과 유사하게. 이로써 업데이트 관리가 단순화되고 빠른 배포가 가능하며 호환성 문제를 예방할 수 있습니다.

개요

Capgo’s version targeting system allows you to:

사용자의 네이티브 앱 버전에 따라 브레이킹 변경을 예방
Prevent breaking changes 일치하지 않는 앱 버전까지
여러 앱 버전 관리 복잡한 논리를 사용하지 않고 동시에
업데이트를 안전하게 배포 특정 사용자 그룹으로

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

Ionic AppFlow 을 이미 알고 있다면이해할 것입니다. AppFlow는 live update 패키지를 native 앱 버전과 자동으로 매칭하여, 더 이상 사용되지 않는 native code에 불일치하는 JavaScript가 전달되는 것을 방지했습니다.

Capgo은 동일한 안전 보장 보장을 제공하며, 추가 기능도 제공합니다.__CAPGO_KEEP_0__

버전 일치에 대한 더 세분화된 제어
다중 전략 (채널, semver, 네이티브 제약)
버전 분포에 대한 더 나은 시야
API 및 CLI 관리와 함께 대시보드 관리

이 접근 방식은 특히 다음과 같은 경우에 유용합니다.

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

이것은 어떻게 작동하는지

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

네이티브 버전 제약 조건: 호환되지 않는 네이티브 버전으로 배달되는 번들을 방지합니다
채널 기반 라우팅: 앱 버전을 다르게 업데이트하는 채널로 라우팅합니다
의미적 버전 제어: 메이저/마이너/패치 경계를 넘는 업데이트를 자동으로 차단합니다
장치 수준 오버라이드: 특정 장치 또는 사용자 그룹을 대상으로합니다

버전 매칭 흐름

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의 전달 모델과 유사합니다.

예시 시나리오 App v1.x production (100,000 명의 사용자) →
채널 (50,000 사용자와 버그 수정) → v2 채널
App v3.x (10,000 베타 사용자) → 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: 'atBackground',
      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: 'atBackground',
      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: 'atBackground',
      defaultChannel: 'v3', // Routes v3 users automatically
    }
  }
};

Step 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

Step 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

장점

code 변경 없이 - 채널 라우팅이 자동으로 발생합니다.
명확한 분리 - 각 버전이 독립된 업데이트 PIPELINE을 가집니다.
flexible 타겟팅 - 특정 버전 그룹에 업데이트를 푸시합니다.
안전한 롤아웃 - 불일치 버전에 도달하는 브레이킹 변경이 없습니다.

Strategy 2: 의미적 버전 제어

Capgo의 내장 의미적 버전 제어를 사용하여 버전 경계를 넘는 업데이트를 방지하세요.

주요 버전을 넘는 업데이트를 자동으로 비활성화하세요.

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

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

__CAPGO_KEEP_0__의 앱 버전을 사용하는 사용자는 1.2.3 업데이트를 1.9.9
__CAPGO_KEEP_1__까지 받을 수 있습니다. __CAPGO_KEEP_0__의 사용자는 __CAPGO_KEEP_2__ 버전을 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

3. 네이티브 버전 제약

세밀한 제어 옵션

원본 버전 지연 조건 사용

배포할 때 원본 버전을 지정할 수 있습니다.

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

사용 사례

터미널 창

# 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. 자동으로 다운그레이드 방지 전략

현재 네이티브 버전보다 이전 버전의 패키지를 사용자에게 제공하지 않도록 방지합니다.

채널 설정에서 활성화

Capgo 대시보드에서:

Go to 채널 → 채널을 선택하세요
활성화 “자연어 다운그레이드 자동화 비활성화”
변경 사항 저장

또는 CLI를 통해:

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

예시

사용자의 기기: Native 버전 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 대시보드에서:

로 이동하세요 기기 → 기기를 찾으세요
클릭 채널 설정 또는 버전 설정
특정 채널 또는 버전으로 오버라이드
기기에서 오버라이드된 소스에서 업데이트를 받습니다.

완전한 AppFlow-Style 워크플로우

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: 'atBackground',
      defaultChannel: 'production',
    }
  }
};

2. 애플리케이션 버전 2.0.0에서 발생하는 변경 사항

# 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: 'atBackground',
      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 대시보드를 사용하여 추적:

버전 v1과 v2의 사용자 수
버전별 패키지 채택률
버전별 오류 또는 충돌

5. 오래된 버전 폐기

버전 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() call
defaultChannel in capacitor.config.ts
기본 채널 (클라우드 설정) - 가장 낮은 우선순위

Best Practices

1. Always Set defaultChannel for Major Versions

// ✅ 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. Use Semantic Versioning

# ✅ 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. 버전 분포를 모니터링하세요

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

사용자가 최신 네이티브 버전으로 업그레이드하고 있나요?
오래된 버전이 여전히 높은 트래픽을 받고 있나요?
오래된 채널을 deprecated 해야 하나요?

Ionic AppFlow와의 비교

Ionic AppFlow에서 팀이 이주하는 경우, __CAPGO_KEEP_0__의 버전 대상 설정은 어떻게 비교되나요? 기능, here’s how Capgo’s version targeting compares:

__CAPGO_KEEP_0__	버전 기반 라우팅	Capgo
버전	원본 버전 기반 자동	원본 버전을 통해 자동 `defaultChannel` + 여러 전략
의미 버전	기본 지원	advanced with `--disable-auto-update` (major/minor/patch)
원본 버전 제약	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에서 마이그레이션

Ionic AppFlow에서 이동하는 경우 Ionic AppFlow버전을 대상으로하는 작업은 Capgo에서 매우 유사하며, 향상된 유연성을 제공합니다.

개념 매핑

AppFlow Concept	Capgo 개념	주석
배포 채널	Capgo 채널	같은 개념, 더 강력
원본 버전 잠금	`--native-version` __CAPGO_KEEP_0__	더 세부적인 제어
채널 우선순위	채널 우선순위 (override → cloud → default)	더 투명한 우선순위
배포 대상	채널 + semver 제어	여러 전략이 사용 가능
프로덕션 채널	`production` 채널 (또는 임의의 이름)	가변적인 이름
Git 기반 배포	CLI branch에서 업로드하는 번들	같은 워크플로우
자동 버전 일치	`defaultChannel` + 버전 제약	여러 전략을 지원하는 강화

AppFlow 사용자들을 위한 주요 차이점

더 많은 제어: Capgo은 여러 전략 (채널, semver, 네이티브 버전) 을 결합할 수 있습니다.
더 나은 시각화: 버전 분포 및 호환성 문제를 보여주는 대시보드
API 접근: 버전 대상 지정에 대한 완전한 프로그래밍적 제어
자체 호스팅: 동일한 버전 로직을 사용하여 자신의 업데이트 서버를 실행하는 옵션

업그레이드 단계

앱 플로우 채널을 __CAPGO_KEEP_0__ 채널에 맵핑하세요 (일반적으로 1:1) to Capgo channels (usually 1:1)
버전 defaultChannel 버전 capacitor.config.ts 버전 규칙을 구성
세미버저 버전 규칙 버전 경계에서 자동 차단을 원하신다면
버전별로 업로드할 번들 사용 --native-version 기호
버전 분포를 모니터링 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()
  }
}

버전 간 A/B 테스트

// 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 provides multiple strategies for version-specific update delivery:

채널 기반 라우팅: 자동 버전 분리 defaultChannel
Semantic Versioning: 메이저/마이너/패치 버전 간 업데이트를 방지
네이티브 버전 제약: 번들에 대한 최소 네이티브 버전 요구
다운그레이드 방지: 최신 네이티브 버전으로 전달되는 것을 방지
디바이스 오버라이드: 테스트 및 목표 설정을 위한 수동 제어

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

특정 기능에 대한 자세한 내용:

변경 사항 안내 - 세부 채널 버전 관리 전략
채널 관리 - 채널 구성 참조
업데이트 동작 - 네이티브 버전 지연 및 조건