버전 타겟팅

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

이 가이드는 사용자의 Native Build 버전에 맞춰 최신 호환 번들을 자동으로 배포하는 방법을 설명합니다. Ionic AppFlow의 방식과 유사하게 이를 통해 호환성 문제를 방지하면서 업데이트 관리를 간소화하고 더 빠르게 배포할 수 있습니다.

개요

Capgo의 버전 타겟팅 시스템을 통해 다음을 수행할 수 있습니다:

호환 가능한 업데이트 자동 배포 사용자의 네이티브 앱 버전에 따라
Breaking Change 방지 호환되지 않는 앱 버전으로의 배포 차단
여러 앱 버전 동시 관리 복잡한 로직 없이도 간편하게
업데이트를 매끄럽게 배포하세요 특정 사용자 세그먼트를 대상으로

버전 타겟팅이 중요한 이유 (특히 AppFlow 사용자라면)

만약 다음 서비스에 익숙하시다면 Ionic AppFlow, 사용자가 호환 가능한 업데이트만 받도록 보장하는 것이 얼마나 중요한지 잘 알고 계실 겁니다. AppFlow는 live update 번들을 네이티브 앱 버전과 자동으로 매칭하여, 구버전 네이티브 code에 호환되지 않는 JavaScript가 전달되는 것을 방지했습니다.

Capgo 역시 동일한 안전성을 보장하며, 다음과 같은 추가 기능을 제공합니다:

더 세밀한 버전 매칭 제어
다양한 전략 지원 (channels, semver, native constraints)
버전 배포 현황에 대한 가시성 확보
API와 CLI은 대시보드 관리와 함께 제어됩니다

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

앱의 주요 버전이 여러 개로 나뉘어 있는 경우 (예: v1.x, v2.x, v3.x)
Breaking change를 배포하면서 하위 호환성을 유지해야 하는 경우
새로운 번들이 이전 버전의 Native code를 깨뜨리는 것을 방지하고 싶은 경우
사용자를 한 버전에서 다른 버전으로 점진적으로 마이그레이션하는 경우
AppFlow에서 마이그레이션 중이며 동일한 수준의 업데이트 안정성을 유지하고 싶은 경우

작동 원리

Capgo는 사용자에게 호환되는 업데이트를 매칭하기 위해 다층적인 접근 방식을 사용합니다:

Native 버전 제약 조건: 호환되지 않는 Native Build 버전으로 번들이 배포되는 것을 방지합니다
채널 기반 라우팅: 앱 버전에 따라 서로 다른 업데이트 채널로 라우팅합니다
Semantic Versioning 제어: Major/Minor/Patch 경계를 넘는 업데이트를 자동으로 차단합니다
디바이스 레벨 오버라이드: 특정 디바이스 또는 사용자 그룹을 타겟팅합니다

버전 매칭 플로우

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

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

이것은 권장되는 방식입니다 breaking changes 및 메이저 버전 업데이트를 관리하는 데 적합합니다. AppFlow의 배포 모델과 유사합니다.

예시 시나리오

앱 v1.x (사용자 100,000명) → production 채널로 이동
앱 v2.x (breaking changes 포함 사용자 50,000명) → v2 채널로 이동
앱 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
    }
  }
};

2단계: 채널 생성

# Create channels for each major version
npx @capgo/cli channel add production
npx @capgo/cli channel add v2
npx @capgo/cli channel add 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단계: 버전별 번들 upload

# 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 수정 불필요 - 채널 라우팅이 자동으로 수행됩니다
명확한 분리 - 각 버전마다 고유한 업데이트 파이프라인을 가집니다
유연한 타겟팅 - 특정 버전 그룹에 업데이트를 푸시합니다
안전한 롤아웃 - Breaking changes가 호환되지 않는 버전에 전달되지 않습니다

전략 2: Semantic Versioning 제어

Capgo의 내장 semantic versioning 제어 기능을 사용하여 버전 경계를 넘는 업데이트를 방지하세요.

메이저 버전 간 자동 업데이트 비활성화

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

이 설정의 의미는 다음과 같습니다:

앱 버전에 따른 사용자 1.2.3 will receive updates up to 1.9.9
사용자는 다음 버전을 받지 2.0.0 않습니다
자동으로 업데이트되지 않음. 이전 버전의 Native code에 breaking changes가 전달되는 것을 방지합니다.
비교 시 전송된 Native Build 기준을 사용합니다. version_build

세부 제어 옵션

# Block target bundles outside the native major.minor line (1.2.x won't get 1.3.0)
npx @capgo/cli channel set stable --disable-auto-update minor

# Block target bundles outside the exact native MAJOR.MINOR.PATCH core (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: Native 버전 제약 조건

각 번들에 최소 Native 앱 버전을 (min_update_version) 지정하여 Capgo가 네이티브 바이너리가 충분히 최신인 기기에만 번들을 전달하도록 합니다.

이 방식은 다음 채널 메타데이터 전략 (--disable-auto-update metadata)과 --min-update-version 또는 --auto-min-update-version 를 업로드 시 사용합니다. 별도의 --native-version CLI 플래그는 없습니다.

채널에서 메타데이터 타겟팅 활성화

# one-time: require min_update_version metadata on uploads to this channel
npx @capgo/cli@latest channel set production --disable-auto-update metadata

업로드 시 최소 Native Build 버전 설정

Bundle을 업로드할 때, 해당 번들을 수신할 수 있는 가장 낮은 Native Build 버전을 전달하세요:

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

또는 Capgo가 Native 패키지 호환성을 기준으로 최소 버전을 설정하도록 하세요:

npx @capgo/cli@latest bundle upload \
  --channel production \
  --auto-min-update-version

사용 사례

새로운 네이티브 플러그인이 필요한 경우

# Bundle needs Camera plugin added in v2.0.0
npx @capgo/cli@latest bundle upload \
  --channel production \
  --min-update-version "2.0.0"

네이티브 API 변경 사항으로 인한 중단 발생 시

# Bundle uses new Capacitor 6 APIs
npx @capgo/cli@latest bundle upload \
  --channel production \
  --min-update-version "3.0.0"

단계적 마이그레이션

# one-time: enable metadata gating on beta
npx @capgo/cli@latest channel set beta --disable-auto-update metadata

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

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

사용자가 현재 Native Build 버전보다 낮은 버전의 bundle을 받지 않도록 방지합니다.

Channel Settings에서 활성화

Capgo dashboard에서:

다음으로 이동: 채널 → 채널 선택
활성화 “Native 버전에서 자동 다운그레이드 비활성화”
변경 사항 저장

또는 CLI를 통해:

npx @capgo/cli@latest channel set production --no-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 스타일의 워크플로우 완성

모든 전략을 결합한 전체 예시는 다음과 같습니다:

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

# Create production channel, then enable metadata min-version gating
npx @capgo/cli@latest channel add production
npx @capgo/cli@latest channel set production \
  --disable-auto-update metadata \
  --no-downgrade

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

2. Breaking Change 배포 (App v2.0.0)

# Create v2 channel for new version
npx @capgo/cli@latest channel add v2
npx @capgo/cli@latest channel set v2 \
  --disable-auto-update metadata \
  --no-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@latest bundle upload \
  --channel production \
  --min-update-version "1.0.0"

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

4. 버전별 배포 현황 모니터링

Capgo 대시보드에서 다음 항목을 확인하세요:

v1 vs v2 사용자 수 비교
버전별 Bundle 채택률
버전별 에러 및 크래시 발생률

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)

Channel 우선순위

여러 Channel 설정이 있는 경우, Capgo는 다음 우선순위를 따릅니다:

기기 오버라이드 (Dashboard 또는 API) - 최우선 순위이며 Device Override UI에 표시됨
로컬 플러그인 채널 via setChannel() - 기기에만 저장되며 Device Override UI에는 표시되지 않음
defaultChannel capacitor.config.ts 내
기본 채널 (Cloud 설정) - 최저 순위

모범 사례

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. 별도 브랜치 유지하기

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

# ❌ Bad: Single branch for all versions

4. 배포 전 테스트 수행

# one-time: create beta and enable metadata gating
# (production is set up in the complete workflow above)
npx @capgo/cli@latest channel add beta
npx @capgo/cli@latest channel set beta --disable-auto-update metadata

# Test on beta channel first
npx @capgo/cli@latest bundle upload \
  --channel beta \
  --auto-min-update-version

# Monitor for issues, then promote to production
npx @capgo/cli@latest bundle upload \
  --channel production \
  --auto-min-update-version

5. 버전 배포 현황 모니터링

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

사용자들이 최신 Native 버전으로 업데이트하고 있나요?
구버전의 트래픽이 여전히 높은가요?
오래된 채널을 중단(deprecate)해야 할까요?

Ionic AppFlow와의 비교

다음에서 마이그레이션하는 팀의 경우: Ionic AppFlow Capgo의 버전 타겟팅은 다음과 같이 다릅니다:

기능	Ionic AppFlow	Capgo
버전 기반 라우팅	Native 버전 기준 자동 설정	다음 방식으로 자동 설정: `defaultChannel` + 다중 전략 사용
시맨틱 버전 관리 (Semantic versioning)	기본 지원	다음 기능을 통한 고급 설정: `--disable-auto-update` (major/minor/patch)
Native 버전 제약 조건	AppFlow dashboard에서 수동 설정	내장됨 `--min-update-version` / `--auto-min-update-version` metadata channel 활용
Channel 관리	Web UI + CLI	Web UI + CLI + API
디바이스 오버라이드	제한적인 디바이스 레벨 제어	Dashboard/API를 통한 전체 제어
자동 다운그레이드 방지	지원	Yes via `--no-downgrade`
멀티 버전 유지 관리	수동 브랜치/채널 관리	채널 우선순위 기반 자동화
셀프 호스팅	아니요	예 (완전한 제어 가능)
버전별 분석	기본	버전별 상세 메트릭

문제 해결

업데이트를 받지 못하는 사용자

다음 사항을 확인하세요:

채널 할당: 디바이스가 올바른 채널에 있는지 확인

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

버전 제약 조건: 번들에 Native Version 요구 사항이 있는지 확인
- Dashboard → Bundles → “Native Version” 컬럼 확인
Semver 설정: 채널의 disable-auto-update 설정 확인
터미널 창
```
npx @capgo/cli channel list
```
기기 오버라이드: 기기에 수동 오버라이드가 설정되어 있는지 확인
- Dashboard → Devices → 기기 검색 → 채널/버전 확인

번들이 잘못된 버전으로 전달됨

defaultChannel 검토: 올바른 채널이 설정되었는지 확인 capacitor.config.ts
번들 업로드 확인: 번들이 의도한 채널로 업로드되었는지 확인
최소 업데이트 버전 검사: 확인 --min-update-version (또는 --auto-min-update-version) 설정되었으며, 해당 채널은 다음을 사용합니다 --disable-auto-update metadata

이전 버전에 영향을 미치는 Breaking Changes

즉각적인 해결 방법: 영향을 받는 디바이스를 안전한 bundle로 오버라이드
- 대시보드 → Devices → 일괄 선택 → 버전 설정
장기적인 해결 방법: 버전별 채널을 생성하고 별도의 브랜치를 유지
예방: 배포 전 항상 대표 디바이스에서 업데이트를 테스트하세요

Ionic AppFlow에서 마이그레이션하기

만약 다음에서 마이그레이션 중이라면 Ionic AppFlow, Capgo의 버전 타겟팅 방식은 매우 유사하며, 더욱 유연한 기능을 제공합니다:

개념 매핑

AppFlow 개념	Capgo 대응 항목	참고 사항
채널 배포	Capgo 채널	동일한 개념, 더 강력한 기능
Native Version Lock	`--min-update-version` / `--auto-min-update-version`	더 세밀한 제어
Channel 우선순위	Channel 우선순위 (override → cloud → default)	더 투명한 우선순위
배포 대상	Channel + semver 제어	다양한 전략 활용 가능
프로덕션 채널	`production` channel (또는 임의의 이름)	유연한 네이밍
Git 기반 배포	브랜치에서 CLI bundle upload	동일한 워크플로우
자동 버전 매칭	`defaultChannel` + 버전 제약 조건	다양한 전략으로 기능 강화

AppFlow 사용자를 위한 주요 차이점

더 많은 제어권: Capgo는 조합 가능한 다양한 전략(channels, semver, native version)을 제공합니다
향상된 가시성: Dashboard에서 버전 분포 및 호환성 문제를 확인할 수 있습니다
API 액세스: 버전 타겟팅에 대한 완전한 프로그래밍 방식 제어
셀프 호스팅: 동일한 버전 로직으로 자체 업데이트 서버를 운영하는 옵션

마이그레이션 단계

AppFlow 채널을 Capgo 채널로 매핑 (보통 1:1)
설정 defaultChannel 에서 capacitor.config.ts 각 메이저 버전별로
semver 규칙 설정 버전 경계에서 자동 차단을 원한다면
버전별 번들 업로드 사용 --min-update-version (채널에 metadata 전략 사용 필수)
버전 분포 모니터링 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는 버전별 업데이트 배포를 위한 다양한 전략을 제공합니다:

채널 기반 라우팅: 다음을 통한 자동 버전 분리 defaultChannel
시맨틱 버저닝: 메이저/마이너/패치 경계 간 업데이트 방지
네이티브 버전 제약 조건: 번들에 필요한 최소 네이티브 버전 지정
자동 다운그레이드 방지: 최신 네이티브 버전에 이전 번들 배포 방지
디바이스 오버라이드: 테스트 및 타겟팅을 위한 수동 제어

이러한 전략들을 조합하면 AppFlow 스타일의 자동 업데이트 배포를 구현하면서도 훨씬 더 높은 유연성과 제어력을 확보할 수 있습니다. 앱의 버전 관리 및 배포 워크플로우에 가장 적합한 방식을 선택하세요.

상세 기능에 대한 자세한 내용은:

Breaking Changes 가이드 - 상세한 채널 버전 관리 전략
채널 관리 - 채널 설정 전체 레퍼런스
업데이트 동작 - 네이티브 버전 지연 및 조건

Version Targeting에서 계속하기

사용 중이라면 버전 타겟팅 채널 라우팅과 단계적 배포를 계획하려면, 다음을 연결하세요: 채널 Channels의 구현 세부 사항은 다음을 참고하세요: 채널 Channels의 구현 세부 사항은 다음을 참고하세요: 채널 Channels의 구현 세부 사항은 다음을 참고하세요: Beta Testing 솔루션 Beta Testing 솔루션의 제품 워크플로우를 위한, 그리고 버전 타겟팅 솔루션 Version Targeting Solution의 제품 워크플로우용.